Using the encrypted local store feature

The EncryptedLocalStore class

To gain access to the encryption functionality that is built into Adobe AIR, you leverage the EncryptedLocalStore class. The class has only three methods and all of them are static (that is, they don't require an instance of the class):

• When you want to put something in the store, simply call EncryptedLocalStore.setItem().
• To get something out of the store call EncryptedLocalStore.getItem().
• To remove something entirely from the store, EncryptedLocalStore.removeItem().

Note: The encrypted local store was added in AIR beta 2. The storage mechanism has changed in Adobe AIR 1.0 and previously existing encrypted data is no longer accessible. Before Adobe AIR 1.0 can use this feature you must call EncryptedLocalStore.reset() to clear all previously existing data. You may want to use an Adobe AIR beta 2 application to retrieve the data prior to resetting the store, as all existing data will be destroyed.

Encryption details

Here's an overview of how encryption is implemented in Adobe AIR:

• Each Adobe AIR application has its own encrypted local store.
• The encrypted local store can only be accessed from the application security sandbox.
• Adobe AIR uses DPAPI on Windows and Keychain on Mac OS X.
• Data is encrypted to the local store using AES-CBC 128-bit.

How it works

Everything is put in the store, and retrieved from the store, as a ByteArray. This can be a little confusing at first when you think about just simple data such as passwords. The encryption mechanism however can be leveraged on entire files, not just text, and the ByteArray accommodates more diverse scenarios.

Putting data into the store

Take a look at the common case of remembering a user's login information starting with storing the data. This means getting the information out of the input field, writing it to a ByteArray, and then putting the data in the encrypted store:

When calling EncryptedLocalStore.setItem(), you need to have the data already in a ByteArray. When storing a string, this can be easily accomplished by creating a new ByteArray instance, and then using ByteArray.writeUTFBytes(), which takes a string argument. The other important part of EncryptedLocalStore.setItem() is the name of the item you're setting. This acts as a label for reference later when you want to get, change, or remove the data.

When using the encrypted local store, it is important to always read and write the data using UTF-8.

When you choose to store the user's login credentials is really up to you. You might choose to store the data when the user clicks the Remember me check box. You might choose to store the data when the user clicks the Sign In button. Or you might even wait to store the data, until a successful login has been made. As a general rule, you'll probably want to wait for a successful login so you can be sure that the data you are storing will actually be accurate for future use.

Retrieving data from the store

Next up comes getting the data back out of the encrypted local store. In the case of "Remember me" functionality, this will most commonly be done when the Adobe AIR application starts. You get the data using the item name (label) you used previously. Using ByteArray.readUTFBytes() will get the string back out of the ByteArray.

In this scenario a call is made for each value, user name and password. You might choose to concatenate both user name and password into one comma-separated value before you store it. That in turn would mean only one call to get that value back out of the store. If you went that direction here, you'd likely end up with more code to split the values back apart (that is, String.split()). Keep in mind that EncryptedLocalStore doesn't really care about the independent values, just that it is encrypting a ByteArray.

Finally comes the task of removing the data in the situation that the user no longer wants the application to store it. The EncryptedLocalStore class also makes that task easy enough by providing EncryptedLocalStore.removeItem(). Just like EncryptedLocalStore.getItem(), you pass the label of the item you want to remove when calling EncryptedLocalStore.removeItem(), which returns no value.

Just like the decision as to when to store the data, and how to store the data, when to remove the data is also up to you. The data that you're encrypting doesn't have to be text, it can be anything that can be represented by a ByteArray. The encrypted local store is flexible. The important part of course is that your user's data can now be securely stored on the desktop as part of your application's functionality.