Storing sensitive data in encrypted cache
This tutorial covers the following topics:
- What is encrypted cache?
- Supported browsers and devices
- Creating and opening encrypted cache
- Reading, writing, and removing data by using encrypted cache
- Closing and destroying encrypted cache
- Changing the encryption key
- Sample application
What is encrypted cache?
Encrypted cache is a mechanism for storing sensitive data on the client side.
Encrypted cache is implemented by using HTML5 web storage technology, which allows data to be saved locally and retrieved on subsequent application use or restart.
The data is encrypted by a combination of a user-provided key and a server-retrieved randomly generated token, which makes it more secure.
Data is stored in key-value pairs.
Encrypted cache is like a security deposit box: it remains open until you close it, so it is important to remember to close the cache when you are finished working with it.
Encrypted cache is similar to technologies such as:
- Local web or DOM storage
- Indexed database API
- Cordova API: Storage API or File API
The following table shows how some features provided by encrypted cache compare with other technologies.
(1): These features are further described in the JSONStore tutorial.
(2): Reliable storage means that your data is not deleted unless the application is removed from the device or one of the methods that removes data is called.
(3): "Dev. Only means that it is designed only for development. There are no security features and a ~5 MB storage space limit.
Supported browsers and devices
You implement encrypted cache by using HTML5 web storage technology.
The following table shows which browsers support web storage for mobile devices.
For more information, see the Can I use page.
Creating and opening encrypted cache
To create or open previously created encrypted cache, use the following API:
WL.EncryptedCache.open(credentials, createIfNone, onComplete, onError);
credentials– A string value that represents a user-provided password.
createIfNone– A Boolean value that specifies whether a new encrypted cache is created if none is found.
onComplete– A callback function to be invoked after the cache is opened or created.
onError- A callback function to be invoked when the cache is not successfully opened or created.
Note: Before you create a new encrypted cache, make sure that the application can connect to the MobileFirst Server instance.
A callback function can receive one of the following statuses:
WL.EncryptedCache.OK– The encrypted cache was successfully opened or created.
WL.EncryptedCache.ERROR_CREDENTIALS_MISMATCH– An attempt was made to open existing encrypted cache by using wrong credentials.
WL.EncryptedCache.ERROR_SECURE_RANDOM_GENERATOR_UNAVAILABLE– Unable to generate random token due to MobileFirst Server unavailability.
WL.EncryptedCache.ERROR_NO_EOC– Could not open encrypted cache because it was not previously created.
WL.EncryptedCache.ERROR_LOCAL_STORAGE_NOT_SUPPORTED– The device does not support HTML5 local storage.
changeCredentials()request is already running.
Reading, writing, and removing data by using encrypted cache
When the encrypted cache is open, operations such as reading, writing, and removing data can be performed.
To store data in encrypted cache, use the following API:
WL.EncryptedCache.write(key, value, onSuccess, onFailure);
To read data from the encrypted cache, use the following API:
WL.EncryptedCache.read(key, onSuccess, onFailure);
To remove data from the encrypted cache, use the following API:
WL.EncryptedCache.remove(key, onSuccess, onFailure);
Closing and destroying encrypted cache
To avoid possible unwanted access to encrypted cache, close it.
After an encrypted cache is closed, access to its data is not possible without the encryption key that was used to create it.
To close the encrypted cache, use the following API:
Changing the encryption key
While encrypted cache is in the open state, you can change the encryption key.
To do so, use the following API:
WL.EncryptedCache.changeCredentials(credentials, onComplete, onError)
credentials– The new user password to be used.
onComplete– A callback function to be invoked when the change has completed.
onError– A callback function to be invoked in case of an error.
Each parameter is a callback and receives a status object as its response. The available statuses for the
changeCredentials method are the same as the statuses for the
WL.EncryptedCache.open method (see Creating and opening encrypted cache).
Click to download the Studio project.