Encrypt a Realm - Java SDK
On this page
Overview
You can encrypt your realms to ensure that the data stored to disk can't be read outside of your application. You encrypt the realm file on disk with AES-256 + SHA-2 by supplying a 64-byte encryption key when opening a realm.
Realm transparently encrypts and decrypts data with standard AES-256 encryption using the first 256 bits of the given 512-bit encryption key. Realm uses the other 256 bits of the 512-bit encryption key to validate integrity using a hash-based message authentication code (HMAC).
Warning
Do not use cryptographically-weak hashes for realm encryption keys. For optimal security, we recommend generating random rather than derived encryption keys.
Considerations
The following are key impacts to consider when encrypting a realm.
Storing & Reusing Keys
You must pass the same encryption key to RealmConfiguration.Builder.encryptionKey() each time you open the realm. If you don't provide a key or specify the wrong key for an encrypted realm, the Realm SDK throws an error.
Apps should store the encryption key in the Android KeyStore so that other apps cannot read the key.
Performance Impact
Reads and writes on encrypted realms can be up to 10% slower than unencrypted realms.
Encryption and Atlas Device Sync
You can encrypt a synced realm.
Realm only encrypts the data on the device and stores the data unencrypted in your Atlas data source. Any users with authorized access to the Atlas data source can read the data, but the following still applies:
Users must have the correct read permissions to read the synced data.
Data stored in Atlas is always encrypted at a volume (disk) level.
The transfer between client and server is always fully encrypted.
You can also enable Customer Key Management to encrypt stored Atlas data using your cloud provider's key (e.g. AWS KMS, Azure Key Vault, Google Cloud KMS).
If you need unique keys for each user of your application, you can use an OAuth provider or use one of the Realm authentication providers and an authentication trigger to create a 64-bit key and store that key in a user object.
Accessing an Encrypted Realm from Multiple Processes
Changed in version 10.14.0.
Starting with Realm Java SDK version 10.14.0, Realm supports opening the same encrypted realm in multiple processes.
If your app uses Realm Java SDK version 10.14.0 or earlier, attempting to
open an encrypted realm from multiple processes throws this error:
Encrypted interprocess sharing is currently unsupported.
Example
The following steps describe the recommended way to use the Android KeyStore for encryption with Realm:
Generate an asymmetric RSA key that Android can securely store and retrieve using the Android KeyStore.
Note
Android Version M and Above: Keystore Security
Versions M and above require user PIN or fingerprint to unlock the KeyStore.
Generate a symmetric key (AES) you can use to encrypt the realm.
Encrypt the symmetric AES key using your private RSA key.
Store the encrypted AES key on filesystem (in a
SharedPreferences, for example).
When you need to use your encrypted realm:
Retrieve your encrypted AES key.
Decrypt your encrypted AES key using the public RSA key.
Use the decrypted AES key in the
RealmConfigurationto open the encrypted realm.
Tip
See also:
For an end-to-end example of storing and reusing encryption keys, see the store_password example project, which demonstrates the fingerprint API.
Generate and Store an Encryption Key
The following code demonstrates how to securely generate and store an encryption key for a realm:
Access an Existing Encryption Key
The following code demonstrates how to access and decrypt a securely stored encryption key for a realm:
Open an Encrypted Realm
The following code demonstrates how to open an encrypted realm with the encryptionKey() method: