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

SHA3

A new SHA3 algorithm is available for use with the Hash function. You can now use SHA3-256 (SHA3 with 256-bit digest) and SHA3-512 (SHA3 with a 512 bit digest) from the Crypto.HashAlgorithms enumeration for stronger encryption or compatibility with something else that uses them.

Var hash As String
hash = Crypto.Hash("YourPasswordSentence", Crypto.HashAlgorithms.SHA3_512)

BlowFish / TwoFish

The BlowFish and TwoFish encryption algorithms can now be used in Xojo. These two algorithms are similar, with BlowFish being the original algorithm and TwoFish being a newer, more secure version that was derived from BlowFish.

You can use them in Xojo with the Crypto.BlowFishEncrypt, Crypto.BlowFishDecrypt, Crypto.TwoFishEncrypt and Crypto.TwoFishDecrypt methods.

You can use either to encrypt data, but in general you’ll want to avoid BlowFish for your own code, although it might prove useful for compatibility with other libraries or tools.

AES

AES (Advanced Encryption Standard) is also used to encrypt data. You can do this using the Crypto.AESEncrypt and Crypto.AESDecrypt methods. Here is a quick sample:

Var encrypted As MemoryBlock

Var dataToEncrypt As MemoryBlock = "Secret!"
Var key As MemoryBlock = Crypto.GenerateRandomBytes(16)
Var initVector As MemoryBlock = Crypto.GenerateRandomBytes(16)
encrypted = Crypto.AESEncrypt(key, dataToEncrypt, Crypto.BlockModes.CBC, initVector)

Var decrypted As MemoryBlock
decrypted = Crypto.AESDecrypt(key, encrypted, Crypto.BlockModes.CBC, initVector)
// decrypted = "Secret!"

CRC-32

CRC32 is just a simple way to test data integrity and is not cryptographically secure. It still has its uses for fast data comparison and simple hash tables. It can be called like this:

Var crc32 As String
crc32 = Crypto.Hash("StringOrDataToTest", Crypto.HashAlgorithms.CRC32)

RSASign

RSASign now takes an optional parameter and RSASignModes let you specify the hash to use.

Learn more about the Crypto module in the Xojo Documentation.

Updated (Nov 22, 2021): Added AES section

Systems like Apple’s iMessage (their text messaging service) use encryption ensuring that all messages sent between Apple devices via iMessage are encrypted with keys that Apple does not have. They keys are on your device. Law enforcement agencies want Apple and others to provide a means of decrypting those messages without having to obtain the device itself. The problem is that if the government and Apple can get in, others will inevitably find a way to exploit that same back door too, making us and our data less safe and secure.

What some governments have failed to understand is that the bad guys can bypass any back door by using their own encryption. The smart bad guys probably assume that these back doors exist now (or at least aren’t taking any chances) and are already using their own encryption for their communications. How hard is it to write software to encrypt and decrypt messages? Do bad guys have access to programmers smart enough to do this? Yes, they almost certainly do.

Let’s take a look at what is involved in using Xojo to write an app that encrypts and decrypts messages. First, two keys need to be generated, a public key and a private one. The public key allows anyone to encrypt a message that only the holder of the matching private key can decrypt. Public keys can only encrypt. They are no good for decrypting messages. This means you can give anyone your public key which they can then use to send encrypted messages to you that no one else but you can decrypt.

Dim privateKey As String
Dim publicKey As String
If Crypto.RSAGenerateKeyPair(KeySize, privateKey, publicKey) Then
 PrivKey.Text = privateKey
 PubKey.Text = publickey
 SaveNewKeys(privateKey, publicKey)
Else
 Beep
 MsgBox "An error has occured. Keys could not be generated."
End If

This is just 10 lines of code and it could be further reduced. I wrote this to make it easier to read. The important function is RSAGenerateKeyPair on the third line. Next, you need to be able to encrypt a message using someone else’s public key. Let’s take a look at the code to do that:

Dim publicKey As String = RecipientsPublicKey.Text
Dim msg As MemoryBlock = OriginalMessage.Text
try
 Dim encryptedData As MemoryBlock = Crypto.RSAEncrypt(msg, publicKey)
 beep
 If encryptedData = Nil Then
  MsgBox("Encryption failed.")
 else
  Dim c As New Clipboard
  c.Text = Encodebase64(encryptedData)
  c.close
  MsgBox("Your encrypted message has been copied to the clipboard.")
 End If
Catch rte As RuntimeException
 If rte IsA CryptoException Then
  Beep
  MsgBox "Encryption failed because the Public key provided is not valid."
 Else
  Raise rte
 End If
End Try

This is 21 lines of code, most of which is handling errors. The one line that is really doing the work is the fourth one that contains RSAEncrypt. Next we need to be be able to decrypt. Here’s what that code looks like:

Dim privateKey As String = privKey.Text
try
 Dim decryptedData As MemoryBlock = Crypto.RSADecrypt(DecodeBase64(EncryptedMessage.Text), privateKey)
 Decryptedmessage.Text = DefineEncoding(decryptedData.StringValue(0, decryptedData.size), Encodings.UTF8)
Catch rte As RuntimeException
 If rte IsA CryptoException Then
 Beep
 MsgBox "The message could not be decrypted because the incorrect key was provided."
 Else
 Raise rte
 End If
End Try

This is 12 lines of code and like the other code examples, is mostly error checking. The important line is the third one that calls RSADecrypt. There is some additional code to save the keys to a text file and load them back in automatically when the app is launched. However, even adding in all that code gets you to only about 80 lines total. In other words, this is not a big app and not beyond the ability of someone with intermediate programming skills or even perhaps a very dedicated novice. (To learn about this in more depth, read Using Public/Private Key Encryption in Xojo).

If you’d like to try out encrypting messages with the app from which the code above originated, you can download CryptoMessage for macOS, CryptoMessage for Windows or CryptoMessage for Linux. Have a friend do it as well and you can send encrypted messages back and forth. If you’re more adventurous and would like to try playing around with the source code itself, make sure you have Xojo installed (which can be downloaded and used for free) then download the CryptoMessage Xojo Project.

Xojo has a crypto library (the part that provides key generation, encryption and decryption) built-in to it. However, if a programmer wasn’t using Xojo, they could easily find a crypto library on the Internet to use. In other words, building your own app to encrypt and decrypt messages is not very challenging. As I mentioned earlier, the bad guys (at least the smart ones) are likely already doing this as they are probably sufficiently paranoid that despite public announcements to the contrary, the back doors already exist.

The assumption that compromising our security enables catching more bad guys is a flawed one that I have written about before. It won’t work and we will all suffer needlessly. Imagine not being able to carry on a private conversation via your smartphone. That would make your device feel a lot less useful. Some governments have “experts” that have suggested it would be possible to have a back door Law Enforcement could use but could not be compromised by anyone else. That is a logical impossibility. Governments do not possess magic powers. They are made of up people like you and me. That is wishful thinking at best and negligent at worse.

When your government starts making noises about doing this, I advise you to make it clear to them that for the reasons I have stated in this post, such a compromising security is all downside with no upside at all.

All the methods related to cryptography and data ciphering are available under the Crypto module of Xojo, using behind the scene the Crypto++ 5.6.3 library. From the practical side, this allows us to use the RSA public key ciphering and other algorithms to compute unique footprints for given data, as for example Hash, MD5 or SHA. Paul blogged about using Public/Private Key Encryption in Xojo back when we added RSA encryption functions in 2014.

Among the methods related to RSA, we can find the ones to create the Private/Public keys, test the integrity of the public key, signing the given data and, of course, check the integrity of the signature, and ciphering / deciphering the given group of data.

As you probably already know, when we work with RSA we have to keep the Private key in a safe place, using the Public one to give to other people/service/app to whom we want to share information with in a safe manner. This way the users and/or apps and services will be able to use our public key to cipher the data that they want to share with us, and we will be able to use our private key to decipher that group of data so it is legible again.

RSA: Creating and interchanging the keys

Generating the pair of keys could not be more easy in Xojo, with this snippet of code:

Dim publicKey As String
Dim privateKey As String
If Crypto.RSAGenerateKeyPair( 1024, privateKey, publicKey ) Then msgBox “Successfully generated Keys!"

As you can see, the RSAGenerateKeyPair method receives the Integer number that indicates the strength (robustness) of the generated keys, followed by the String variables containing the generated Private and Public keys, passed by reference.

But in some cases it is possible that you want to use these keys beyond the scope of Xojo, for example when integrating your app with a service or solution developed in PHP. In these cases you have to consider that the keys generated with Xojo are in hexadecimal format.

What does this mean? Well, a public key generated with Xojo will look like this chunk of data:

30819D300D06092A864886F70D010101050003818B0030818702818100B4B531D3402C250D8640E739601F01FBE8ABB39635BE1778A7F4E55C49419C0595EF5A5824EA8E7A1871FB63B8960EDBB97B08C2E7EA43229903AEBCB45B9FD9E24780B15BCADB5E026849592CC1FA9B399EBD8457CC4E7A686CF53E9146E1D867ACEB675728E8821DEDA4C2F807FD668A81601F551484C5D1334B62D5E90E33020111

While other external libraries (as is the case in most of the web development frameworks), expect other data format codified as Base64. This is, something like this:

-----BEGIN PUBLIC KEY-----

MIGHAoGBALS1MdNALCUNhkDnOWAfAfvoq7OWNb4XeKf05VxJQZwFle9aWCTqjnoYcftjuJYO27l7
CMLn6kMimQOuvLRbn9niR4CxW8rbXgJoSVkswfqbOZ69hFfMTnpobPU+kUbh2Ges62dXKOiCHe2k
wvgH/WaKgWAfVRSExdEzS2LV6Q4zAgER

-----END PUBLIC KEY-----

So the first step to encode our Xojo keys (Public or Private ones) as Base64 is converting them previously from his hexadecimal form to the DER encoding (Distinguished Encoding Rules). Here is where we have to employ the DEREncodePrivateKey and DEREncodePublicKey methods if we want to encode the Private or the Public key, respectively. Once we have done this, we will be able to encode the resulting chunk of data as Base64 without forgetting to add the header “—–BEGIN PUBLIC KEY—–“ and the footer “—–END PUBLIC KEY—–“ with the accompanying ends of lines, or maybe the header “—–BEGIN CERTIFICATE—–” and the footer “—–END CERTIFICATE—–“ if we are dealing with a Public Key (for the Private keys we have to use the header “—–BEGIN RSA PRIVATE KEY—–” and the footer “—–END RSA PRIVATE KEY—–“).

You can interchange and use the Private and Public keys generated with Xojo using the PHPSecLib library.

In addition, as pointed by Thom McGrath, you can use also these keys with OpenSSL this way:

if (@openssl_public_encrypt($data, $result, $public_key, OPENSSL_PKCS1_OAEP_PADDING)) {
         return $result;
 } else {
         throw new \Exception('Unable to encrypt');
 }

Xojo’s Crypto library will be able to use a private key to decrypt $result in this case.

Finally, if you are interested in the cryptography topic, let me recommend you some good books: Applied Cryptography and Cryptography Engineering.

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers and the Snippery app, among others.

The answer is yes. There are plenty of options that don’t require a global back door. I’m not passing judgment on whether these are inherently good or bad options, just that they are available when there is a reason to track a Bad Guy.

Keyloggers
A keylogger is used to track everything someone types. They come in both software and hardware varieties. Once installed, they can provide regular data about passwords and other communications the Bad Guy is making. Some store the data for later retrieval, while others broadcast it on a regular basis. They exist in varieties for both computers and cell phones.

Online Man in the Middle
With proper authorization, the Good Guys can stand between the Bad Guys and common online services they might be using. Working with their internet provider, they can gather data similar to keyloggers by intercepting and relaying data back and forth.

Digital Evidence Collection
When a warrant is served and computers or mobile devices are retrieved for analysis, gathering evidence quickly is paramount. The Bad Guys may have countermeasures installed on their devices, so being able to copy data from hard drives and other storage mediums across platforms while they are still online is important. Once images of the data are created, the evidence can be safely analyzed without being concerned about time bombs or other countermeasures. Xojo has been used to create tools that are used for both digital evidence collection and analysis. Being a cross platform tool is a particular advantage in this scenario.

None of the above options require a global back door, and they can all be limited to just the Bad Guys in question when surveillance is warranted. A recently released Harvard study has similar findings. Some options are better than others depending on the region in the world and the technical prowess of the Bad Guys. Smartphone Encryption is a Red Herring, but the Good Guys have other options. We don’t need universal back doors.

Today, terrorists are using encryption to hide their communications just like the Nazis did in WWII. What makes encryption different today is that it is also being used by millions of ordinary people, many of whom have no idea they are even using it. Almost every smartphone in use today, encrypts text messages and other data automatically. This is all done behind the scenes without the user ever being aware of it.

The type of encryption used on the iPhone and Android is called AES and it’s formidable. Intercepting your text messages isn’t actually difficult but decrypting those messages is, at best, impractical. To decrypt a message, just like with the Enigma machine, you need to know the key that was used to encrypt it. If you don’t have that key, you’d have to guess at what the key might be then look at the results of decrypting the message with that key to see if you have anything but unintelligible gibberish. Even with access to the fastest computers in the world, it could literally take years to guess the right key. It will come as no surprise that governments at almost every level don’t like this one bit. At their most transparent, they are used to getting a search warrant and being able to look at whatever you’ve got to see if it supports their suspicion that you are in fact up to no good. At their least, they wish to get on your phone (ideally from a secure, remote location) and take your data without a warrant or you having any idea they were ever there. The problem for governments is that they can’t. In Apple’s case, even if Apple was willing to compile with a request that they decrypt the data on your phone, they can’t. The key is stored on your phone in a way that even Apple can’t get to it. In this sense, Apple is in complete alignment with you in terms of your privacy.

There are lawmakers here in the United States that want to force companies like Apple and Google to provide a back door. This would be a way for Apple to get into your data should a search warrant (presumably) be issued. Apple’s CEO Tim Cook as pointed out what a bad idea this is. Back doors don’t get used by just the good guys. They will get used by the bad guys as well. In an effort to make it possible for law enforcement to get at the data of the tiny percentage of the population that is doing wrong, we would be opening everyone up to being hacked remotely. It’s not possible to make a back door that only the good guys can use. Think about your contacts, text messages, email, photos, all being exposed. Just the increased level of extortion alone would be so bad that your smartphone would go back to being useful as nothing more than a phone. Do any of you really want to go back to the 1980s?

What is worse than that, however, is what is not being talked about in the news. Smartphone encryption is a red herring. A back door wouldn’t solve the problem. Bad guys would simply write their own apps to encrypt the data themselves before they send it. This is incredibly easy to do. Xojo, the development tool my company created, has this same type of AES encryption built-in. Many other development tools have it as well. I could write an app to encrypt a message in a few minutes. Even if you have never written a line of code in your life, after a few hours learning Xojo, you could write the same app yourself. If you or I can do it, the bad guys can too. The smartest of them are almost certainly already doing this today. The end result would be that every law-abiding citizen’s personal and private data would become hackable- causing a digital tsunami of cybercrime that would be impossible for law enforcement to stop while achieving next to nothing towards actual security.

I understand why our lawmakers and law enforcement are concerned about encryption. It is a barrier to evidence for them. Tim Cook has argued that we have to balance law enforcement with our personal privacy. That’s certainly true. However, in this case, you don’t even have to go that far. What our elected officials are proposing will not work and will only create an exponentially greater problem. You may be asking yourself, “Surely they have thought of this, right?” Clearly they haven’t. Too often people make decisions without complete information or having taken sufficient time to to think the matter through. We have all seen this many times in our lives. Smartphone encryption is just the latest example. It’s not the first and won’t be the last. I’m all for looking for better ways to catch the bad guys but smartphone back doors will not work. Your elected officials are wasting your precious taxpayer dollars. If you want to stop this, contact them and ask them to better educate themselves on this topic. You can point them to this blog post to start. I can’t speak for countries outside the United States, but here elected officials give considerable weight to their constituents that reach out to them. You can contact your Representatives in the House here and your Senators here.

Lastly, while I am proud of Tim Cook for fighting back on this issue, it saddens me that he appears alone on the world stage while doing this. Powerful people in technology such as Mark Zukerberg of Facebook, Larry Page and Sergey Brin of Google, Satya Nadella of Microsoft and others should be taking an equal stand. They are in an even better position than we are as individuals to make it clear that the proposed solution won’t work. Until then, contact your elected officials and tell them that dog won’t hunt.

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.