Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Device SDKs
/
C++ SDK
/
Realm Files

Encrypt a Realm - C++ SDK

On this page

  • Store & Reuse Keys
  • Performance Impact
  • Encryption and Atlas Device Sync
  • Encrypt a Synced Realm
  • Encrypt Metadata

You can 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.

Encrypt a realm by calling the set_encryption_key() function on your db_config:

// Check if we already have a key stored in the platform's secure storage.
// If we don't, generate a new one.
// Use your preferred method to generate a key. This example key is
// NOT representative of a secure encryption key. It only exists to
// illustrate the form your key might take.
std::array<char, 64> exampleKey = {
    0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0,
    0, 0, 3, 3, 0, 0, 0, 0, 0, 0, 4, 4, 0, 0, 0, 0, 0, 0, 5, 5, 0, 0,
    0, 0, 0, 0, 6, 6, 0, 0, 0, 0, 0, 0, 7, 7, 0, 0, 0, 0, 0, 0};
// Store the key securely to be used next time we want to open the database.
// We don't illustrate this here because it varies depending on the platform.
// Create a database configuration.
auto config = realm::db_config();
// Set the encryption key in your config.
config.set_encryption_key(exampleKey);
// Open or create a database with the config containing the encryption key.
auto realm = realm::db(config);

Tip

You cannot encrypt a realm that already exists on device

The C++ SDK does not yet support encrypting a realm that already exists on device. You must encrypt the realm the first time you open it.

Store & Reuse Keys

You must pass the same encryption key every time you open the encrypted 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 securely on the device 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

Encrypt a Synced Realm

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.

Encrypt Metadata

You can encrypt the metadata that Realm stores on the device. For more information, refer to Encrypt App Metadata.

Back

Reduce Realm File Size

Next

CRUD - C++ SDK

On this page