diff --git a/source/sdk/dotnet/realm-files/encrypt-a-realm.txt b/source/sdk/dotnet/realm-files/encrypt-a-realm.txt index 3c1aa08461..bf23d657a8 100644 --- a/source/sdk/dotnet/realm-files/encrypt-a-realm.txt +++ b/source/sdk/dotnet/realm-files/encrypt-a-realm.txt @@ -28,6 +28,14 @@ integrity using a :wikipedia:`hash-based message authentication code .. include:: /includes/encrypt-use-strong-cryptographic-hash.rst +.. 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. + + .. update with writeCopy API when available + Considerations -------------- diff --git a/source/sdk/flutter/realm-database/realm-files/encrypt.txt b/source/sdk/flutter/realm-database/realm-files/encrypt.txt index 6353445848..c0c7850e51 100644 --- a/source/sdk/flutter/realm-database/realm-files/encrypt.txt +++ b/source/sdk/flutter/realm-database/realm-files/encrypt.txt @@ -27,6 +27,17 @@ integrity using a :wikipedia:`hash-based message authentication code .. include:: /includes/encrypt-use-strong-cryptographic-hash.rst +.. note:: Encrypt a Realm on Open or Copy 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. + + Alternatively, you can copy the unencrypted realm data to a new + encrypted realm using the + :flutter-sdk:`Realm.writeCopy() ` method. + Refer to :ref:`` for more information. + Considerations -------------- diff --git a/source/sdk/kotlin/realm-database/realm-files/encrypt-a-realm.txt b/source/sdk/kotlin/realm-database/realm-files/encrypt-a-realm.txt index 943a4af9f5..f0e9300c2e 100644 --- a/source/sdk/kotlin/realm-database/realm-files/encrypt-a-realm.txt +++ b/source/sdk/kotlin/realm-database/realm-files/encrypt-a-realm.txt @@ -12,8 +12,8 @@ Encrypt a Realm - Kotlin SDK 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 -:ref:`opening the realm `. +disk with AES-256 + SHA-2 by supplying a 64-byte encryption key when first +:ref:`opening the realm `. Realm transparently encrypts and decrypts data with standard :wikipedia:`AES-256 encryption ` using the @@ -24,13 +24,26 @@ integrity using a :wikipedia:`hash-based message authentication code .. include:: /includes/encrypt-use-strong-cryptographic-hash.rst +.. note:: Encrypt a Realm on Open or Copy 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. + + Alternatively, you can copy the unencrypted realm data to a new + encrypted realm using the + `Realm.writeCopyTo() <{+kotlin-local-prefix+}io.realm.kotlin/-realm/write-copy-to.html>`__ + method. + Refer to :ref:`` for more information. + Encrypt a Local Realm --------------------- To encrypt a local realm, pass your encryption key to the `encryptionKey <{+kotlin-local-prefix+}io.realm.kotlin/-configuration/encryption-key.html>`__ -property in your -`RealmConfiguration.Builder() <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html>`__. +property in the +`RealmConfiguration.Builder() <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html>`__ +used to open the realm. The following code demonstrates how to generate an encryption key and open an encrypted local realm: @@ -44,14 +57,15 @@ open an encrypted local realm: Encrypt a Synced Realm ---------------------- -You can encrypt a :ref:`synced realm `, similar +If your app uses Atlas Device Sync, you can encrypt a synced realm, similar to encrypting a local realm. To encrypt a synced realm, pass your encryption key to the `encryptionKey <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb/-app-configuration/encryption-key.html>`__ -property in your +property in the `SyncConfiguration.Builder() -<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.sync/-sync-configuration/-builder/-builder.html>`__. +<{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.sync/-sync-configuration/-builder/-builder.html>`__ +used to open the realm. The following code demonstrates how to open an encrypted synced realm: @@ -59,6 +73,8 @@ The following code demonstrates how to open an encrypted synced realm: :language: kotlin :emphasize-lines: 5-6 +Refer to :ref:`` for more information. + Encryption and Atlas Device Sync ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -97,8 +113,8 @@ Performance Impact Reads and writes on encrypted realms can be up to 10% slower than unencrypted realms. -Access Encrypted Realm from Multiple Processes ----------------------------------------------- +Access Encrypted Realms from Multiple Processes +----------------------------------------------- .. versionchanged:: 10.8.0 diff --git a/source/sdk/node/realm-files/encrypt.txt b/source/sdk/node/realm-files/encrypt.txt index 3f3fe9c2c9..af3e38b37f 100644 --- a/source/sdk/node/realm-files/encrypt.txt +++ b/source/sdk/node/realm-files/encrypt.txt @@ -23,6 +23,19 @@ integrity using a :wikipedia:`hash-based message authentication code .. include:: /includes/encrypt-use-strong-cryptographic-hash.rst +.. note:: Encrypt a Realm on Open or Copy 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. + + Alternatively, you can copy the unencrypted realm data to a new + encrypted realm using the + :js-sdk:`Realm.writeCopyTo() ` + method. + Refer to :ref:`` + for more information. + The following code demonstrates how to generate an encryption key and open an encrypted realm: diff --git a/source/sdk/react-native/realm-files/encrypt.txt b/source/sdk/react-native/realm-files/encrypt.txt index 1e1ed2af22..aaaa57807f 100644 --- a/source/sdk/react-native/realm-files/encrypt.txt +++ b/source/sdk/react-native/realm-files/encrypt.txt @@ -22,6 +22,14 @@ integrity using a :wikipedia:`hash-based message authentication code .. include:: /includes/encrypt-use-strong-cryptographic-hash.rst +.. 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. + + .. update with writeCopy API info once available + The following code demonstrates how to generate an encryption key and open an encrypted realm: diff --git a/source/sdk/swift/realm-files/encrypt-a-realm.txt b/source/sdk/swift/realm-files/encrypt-a-realm.txt index 9c5a1b832a..3b0d474296 100644 --- a/source/sdk/swift/realm-files/encrypt-a-realm.txt +++ b/source/sdk/swift/realm-files/encrypt-a-realm.txt @@ -26,6 +26,14 @@ integrity using a :wikipedia:`hash-based message authentication code .. include:: /includes/encrypt-use-strong-cryptographic-hash.rst +.. 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. + + .. update with writeCopy API when available + Considerations --------------