Encrypt a Realm - .NET 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 the 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.
Note
Cannot Encrypt an Existing Unencrypted Realm
You must encrypt a realm the first time you open it. If you try to open an existing unencrypted realm using a configuration that contains an encryption key, Realm throws an error.
Considerations
The following are key impacts to consider when encrypting a realm.
Storing & Reusing 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, typically in the target platform's secure key/value storage, so that other apps cannot read the key. For example, you can use MAUI Secure Storage or Xamarin Secure Storage to simplify the access to underlying storage. Ultimately, it is the developer's responsibility to ensure that attackers cannot access the key.
Performance Impact
Reads and writes on encrypted realms can be up to 10% slower than unencrypted realms.
Important
The same encryption key must be supplied every time you obtain a Realm instance.
If you don't provide a key, or specify the wrong key, for an encrypted
Realm, you will get a
RealmFileAccessErrorException
when you call GetInstance.
Encryption and Atlas Device Sync
You can encrypt a synced realm.
If you need unique keys for each user of your application, you can use an OAuth provider (such as MAUI.Auth) and Xamarin.Auth), 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 Process
Changed in version 11.0.0.
Starting with Realm .NET SDK version 11.0.0, Realm supports opening the same encrypted realm in multiple processes.
In earlier versions of the Realm .NET SDK, you cannot open the same encrypted realm from multiple processes. Attempting to do so throws the error: "Encrypted interprocess sharing is currently unsupported."
Example
Warning
Do not use cryptographically-weak hashes for realm encryption keys. For optimal security, we recommend generating random rather than derived encryption keys.
The following code demonstrates how to generate an encryption key and open an encrypted realm:
// Check if we already have a key stored in the platform's secure storage. // If we don't, generate a new one: var encryptionKey = new byte[64]; using var rng = RandomNumberGenerator.Create(); rng.GetBytes(encryptionKey); // Store the key securely to be used next time we want to open the Realm. // Create configuration. var config = new RealmConfiguration { EncryptionKey = encryptionKey }; // Open or create a realm with the encryption key. var realm = Realm.GetInstance(config);