Which function should you use when your app needs to:

• remember a user’s password,
• save an API token in a local settings file,
• check that an API request was not changed, or
• verify that an update came from you?

The examples below answer those questions with small, focused scenarios. They show where each function fits. They are not complete security products.

A good starting point is:

• Use PBKDF2 when you need to check a password later.
• Use AES when you need to hide data that your app must read again.
• Use HMAC when two trusted systems share a secret and need to detect changed messages.
• Use Ed25519 when one side signs data and other parties only need to verify it.

Example 1: Remembering a user’s password with PBKDF2

Imagine a desktop or web app with a login screen. When a user creates an account, you need to save something that lets you check the password later.

Do not save this: correct horse battery staple

If somebody gets the database, they immediately have the user’s password. A plain SHA-256 hash is not a good replacement because attackers can calculate fast hashes very quickly and try large lists of common passwords. PBKDF2 is designed for this job. It combines the password with a random salt and repeats the calculation many times.

Var password As String = "correct horse battery staple"
Var salt As String = EncodeHex(Crypto.GenerateRandomBytes(16))
Var iterations As Integer = 100000
Var derived As MemoryBlock = Crypto.PBKDF2(salt, password, iterations, 32, Crypto.HashAlgorithms.SHA2_512)
Var storedHash As String = EncodeHex(derived)

Save salt, iterations, the algorithm name, and storedHash in the user’s record. The salt does not need to be secret. You need it again when the user logs in.

Var suppliedPassword As String = "correct horse battery staple"
Var calculated As MemoryBlock = Crypto.PBKDF2(salt, suppliedPassword, iterations, 32, Crypto.HashAlgorithms.SHA2_512)
Var calculatedHash As String = EncodeHex(calculated)

If calculatedHash = storedHash Then
  MessageBox("Password accepted")
Else
  MessageBox("Password rejected")
End If

The app never needs to recover the original password. It calculates the value again and compares it with the stored one.

The iteration count in this example is only an example. Test it on the slowest computer you support. Store the count with the hash so you can increase it later and update old records after a successful login.

Use Crypto.GenerateRandomBytes here because the salt must not be predictable. The same function is useful when you need a random token, nonce, or initialization vector.

Example 2: Saving an API token in an encrypted settings file

Now imagine a desktop app that lets a user connect to an online service. After the user enters an API token, the app should remember it without saving readable text to its settings file.

This is a job for symmetric encryption. The app uses the same secret key to encrypt and decrypt the value.

AES accepts keys that are 16, 24, or 32 bytes long. The initialization vector is 16 bytes for AES. This example uses a 32-byte key and a new 16-byte IV:

Var secretKey As String = Crypto.GenerateRandomBytes(32)
Var initializationVector As MemoryBlock = Crypto.GenerateRandomBytes(16)
Var apiToken As String = "token-from-the-service"
Var encryptedToken As MemoryBlock = Crypto.AESEncrypt(secretKey, apiToken, Crypto.BlockModes.CBC, initializationVector)

To read the token later:

Var decryptedToken As MemoryBlock = Crypto.AESDecrypt(secretKey, encryptedToken, Crypto.BlockModes.CBC, initializationVector)
Var apiTokenAgain As String = decryptedToken

The IV is not a password and does not need to be secret. Save it with the encrypted value. You need the same IV for decryption.

The key is the difficult part. If you generate a new key every time the app starts, the app cannot decrypt yesterday’s settings. A real application must store the key in a suitable secret store, derive it from a user-provided secret, or keep the sensitive value on a server. Do not put a production key directly in the source code.

The encrypted record might contain these fields:

version
iv
ciphertext

Store the IV and ciphertext as Base64 or hexadecimal text if the settings format cannot hold binary data. Store a version so you can change the format later.

CBC encryption hides the token, but it does not prove that the ciphertext was not changed. For real data, authenticate the encrypted record as well. With CBC, that means using an encrypt-then-MAC design with a separate MAC key. Another option is a vetted authenticated-encryption library or a service that provides an AEAD mode.

Do not reuse an IV with the same key, and do not use ECB mode for application data.

Example 3: Signing an API request with HMAC

Suppose you control both a client and a server application. The client sends an order to the server, and the server needs to know whether somebody changed the request while it was being sent.

The client and server can share a secret. The client signs the request with HMAC, and the server calculates the same HMAC. If the values differ, the server rejects the request.

Var sharedSecret As String = "replace-this-with-a-real-secret"
Var requestText As String = "POST|/api/orders|1714492800|{""id"":42}"
Var requestData As MemoryBlock = requestText
Var signature As MemoryBlock = Crypto.HMAC(sharedSecret, requestData, Crypto.HashAlgorithms.SHA2_256)
Var signatureText As String = EncodeBase64(signature)

Send requestText and signatureText to the server. The server must build exactly the same text before calculating its own signature. A different separator, line ending, or JSON layout produces a different result.

A signature by itself does not stop somebody from sending the same valid request again. Include a timestamp and reject requests that are too old. For an operation that must only happen once, include a unique request ID and record IDs that the server has already processed.

HMAC is a good fit for two backend services or a controlled client-server arrangement. It is a poor fit when you ship the shared secret inside an untrusted desktop or mobile app. A secret compiled into an app can eventually be extracted.

Example 4: Verifying an update with Ed25519

A different situation comes up when you distribute application updates. The update server should be able to sign a file, but the installed app should only need to verify it. The installed app should not possess a secret that could create fake signatures.

Use a public and private key pair:

• Keep the private key on the signing machine.
• Put the public key in the application or distribute it through a trusted channel.

Var privateKey As String
Var publicKey As String

If Crypto.ED25519GenerateKeyPair(privateKey, publicKey) Then
  Var updateInfo As String = "version=4.2.1|sha256=..."
  Var signature As MemoryBlock = Crypto.ED25519Sign(updateInfo, privateKey)

  If signature <> Nil And Crypto.ED25519VerifySignature(updateInfo, signature, publicKey) Then
    MessageBox("Update information is authentic")
  End If
End If

In a real updater, verify the signature before trusting the version or downloading the file. The signature does not prove that the update is safe by itself. It proves that the data matches the private key associated with the public key.

Keep the exact bytes stable. If the signing tool adds a line ending but the app removes it before verification, the signature will fail.

Which function solves which problem?

Start with the problem, not the function name. Ask what the other side needs to do:

• Does it need to check a password? Use PBKDF2.
• Does it need to read the original data? Use encryption.
• Does it need to detect a changed message and share a secret with the sender? Use HMAC.
• Does it need to verify a message without being able to create signatures? Use a public-key signature.

A short safety checklist

1. Never store plaintext passwords.
2. Do not use a fast general-purpose hash as a password-storage scheme.
3. Do not hard-code production secrets in source code or a desktop application.
4. Generate salts and IVs with Crypto.GenerateRandomBytes.
5. Use SHA2_256 or stronger for new hashes and HMACs. Avoid MD5 and SHA-1 for new security designs.
6. Do not treat AES-CBC ciphertext as authenticated unless you add an integrity check.
7. Keep the exact bytes being signed stable.
8. Test wrong passwords, wrong keys, changed messages, replayed requests, and corrupted ciphertext.
9. Check the Xojo compatibility notes for every algorithm you choose.
10. Use an established format or library instead of inventing a cryptographic protocol.

The Crypto module gives you the operations. Your application still has to decide where keys live, what gets signed, how data is formatted, and how keys are replaced. Those decisions determine whether the example can grow into something you can support.

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Here is the problem: How can you send a small message to me so that only I can read it? A technique called Public Key Cryptography is commonly used for this.

RSA Public Key Encryption

With Public Key Cryptography there are two keys: a public key and a private key. Since I am the one receiving messages, I would generate both of these keys. This can be done in Xojo using the Crypto.RSAGenerateKeyPair function:

Dim privateKey As StringDim publicKey As String

If Crypto.RSAGenerateKeyPair(1024, privateKey, publicKey) Then
  // 1024-bit private and public keys were generated
End If

I keep the private key to myself and do not share it with anyone. The public key is shared with you (or anyone, really). To make the public key more presentable, converting it to Base64 is a good idea:

viewablePublicKey = EncodeBase64(publicKey)

Here is a public key that I created (Base64 encoded):

MzA4MTlEMzAwRDA2MDkyQTg2NDg4NkY3MEQwMTAxMDEwNTAwMDM4MThCMDAzMDgxODcwMjgxODEwMEJGRDg2QTkzQkUzNjlFQTE2MDA2QTg2OTFGQkY2MTM5QTc2QkNGNDcwQUY0RjUzMjkyQjJEOUVEMEE2QzRENzIzRDRGMTRCRDY4Nzk4MkQ2QjEyNDVFNkU2QTEwRUNFNThCMzc2MUYyNDJFOTQyQTI1Q0ZGMjk0NzM3QUQ2MkVBRkU3RkU4NkFDNDBDNTMzODIxQzI0QkY4MjBGNTgxMjE2MEU5REE5OEI2RkEyQjY2NUZCN0Q5NEYyN0Q1MTIwMTQ1REU1NUY0MEQ3MDY5NTQzQ0FEOTI0MUE0MUFFMkRDNzJFQTRGN0FDRkFGNzQ5NkNDOUIwQTVFMkNDRkVCMDkwMjAxMTE=

The public key is used to encrypt the message. In Xojo, it is done like this:

Dim publicKey As String = DecodeBase64(PublicKeyArea.Text)
Dim textMessage As String = "Top-secret message for Paul."
Dim msg As MemoryBlockmsg = textMessage
// Encrypt msg using the publicKey
Dim encryptedData As MemoryBlock = Crypto.RSAEncrypt(msg, publicKey)
If encryptedData <> Nil Then
  MsgBox("Successfully encrypted.")
End If

Now you have an encrypted message that you can Base64Encode and send to me:

Dim msgForPaul As String = EncodeBase64(encryptedData)

You can paste this message in an email or even put in a a public forum. No one else will be able to read it. To decrypt it, the private key is needed and only I have the private key.

Xojo code to decrypt the message looks like this:

encryptedData = DecodeBase64(encryptedMsgForPaul)
Dim decryptedData As MemoryBlock = Crypto.RSADecrypt(encryptedData, privateKey)
Dim msg As String = decryptedData
MsgBox(msg)

Try the CryptoRSAExample (Examples/Framework) included with Xojo to see this in action.

To test this out, use RSAEncryptor with the above Public Key to leave me encrypted messages in the comments. I’ll decrypt it and post the decrypted version as a reply. Keep in mind that these “messages” that are being encrypted have to be pretty short (just a couple hundred characters to be safe). This is due to the complex mathematics involved in the generation of the data and it is way beyond anything I can understand, let alone explain. So typically this means that you do not use the above techniques for communicating lengthy messages. More typically these techniques are used to communicate another “secret key” of some kind that can be used to decrypt the actual message that was encrypted with some other technique.

For example, I could create a SQLite database that is encrypted in Xojo and then send you the database. This would be encrypted using AES-128. But how do you decrypt it to access its data since you’ll need the password to decrypt it? This is a perfect situation to use RSA to encrypt the password for the recipient to decrypt. Once they have decrypted the RSA message to get the password, it can be used to access the database. So the process for Julie to send an encrypted database to Paul is as follows:

1. Julie creates a SQLite database, adds data to it and encrypts it using a secret password.

2. Paul creates an RSA Public/Private key pair and gets the Public Key to Julie.

3. Julie encrypts the secret password using the Public Key from Paul to get an encrypted message that she sends to Paul.

4. Paul can decrypt the message from Julie using his Private Key to get the secret password.

5. Julie sends the encrypted database to Paul.

6. Paul accesses the database using the secret password he now has from step 4.

This is secure because the database cannot be accessed by anyone that does not have the secret password and only the person with the RSA Private Key pair for the Public Key used to encrypt the secret password will be able to decrypt it to open the database.

Signatures

Related to all this is the concept of signatures. A signature is used so that you can validate who sent a message and that the message was not modified before it reached you.

To do this, I sign my message using my Private Key (as generated above) and provide you with both the message and the signature. You then verify everything using my Public Key.

This is how I would sign a message using Xojo:

Dim signature As MemoryBlock = Crypto.RSASign(msg, privateKey)

You would then verify the message and signature using my Public Key:

If Crypto.RSAVerifySignature(msg, signature, publicKey) Then
  // msg is valid
End If

The “message” can actually be any data. For example, this is essentially what you are doing when you “code-sign” an application for OS X.

Try the CryptoRSAExample (Examples/Framework) included with Xojo to see this in action.