From 28bc4cff649a36ab2e337cfbf052f9110330e8e5 Mon Sep 17 00:00:00 2001 From: cbullinger Date: Fri, 10 Nov 2023 13:34:15 -0500 Subject: [PATCH] Add note to all SDKs --- .../dotnet/realm-files/encrypt-a-realm.txt | 7 ++++ .../realm-database/realm-files/encrypt.txt | 12 +++++++ .../realm-files/encrypt-a-realm.txt | 35 ++++++++++++++----- source/sdk/node/realm-files/encrypt.txt | 14 ++++++++ .../sdk/react-native/realm-files/encrypt.txt | 7 ++++ .../sdk/swift/realm-files/encrypt-a-realm.txt | 7 ++++ 6 files changed, 73 insertions(+), 9 deletions(-) diff --git a/source/sdk/dotnet/realm-files/encrypt-a-realm.txt b/source/sdk/dotnet/realm-files/encrypt-a-realm.txt index 3c1aa084612..5702c1f6f06 100644 --- a/source/sdk/dotnet/realm-files/encrypt-a-realm.txt +++ b/source/sdk/dotnet/realm-files/encrypt-a-realm.txt @@ -28,6 +28,13 @@ 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 *cannot* encrypt an existing unencrypted realm. + If you pass an encryption key to a configuration + that does not already have one, Realm throws an + error when you attempt to open the existing realm. + Considerations -------------- diff --git a/source/sdk/flutter/realm-database/realm-files/encrypt.txt b/source/sdk/flutter/realm-database/realm-files/encrypt.txt index 63534458484..edd712c61c0 100644 --- a/source/sdk/flutter/realm-database/realm-files/encrypt.txt +++ b/source/sdk/flutter/realm-database/realm-files/encrypt.txt @@ -27,6 +27,18 @@ 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 *cannot* encrypt an existing unencrypted realm. + If you pass an encryption key to a configuration + that does not already have one, Realm throws an + error when you attempt to open the existing realm. + + You can copy an unencrypted realm 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 943a4af9f5d..30ec8c72834 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,27 @@ 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 *cannot* encrypt an existing unencrypted realm. + If you pass an encryption key to a configuration + that does not already have one, Realm throws an + error when you attempt to open the existing realm. + + Instead, 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 +58,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 +74,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 +114,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 3f3fe9c2c9d..0853d75ca97 100644 --- a/source/sdk/node/realm-files/encrypt.txt +++ b/source/sdk/node/realm-files/encrypt.txt @@ -23,6 +23,20 @@ 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 *cannot* encrypt an existing unencrypted realm. + If you pass an encryption key to a configuration + that does not already have one, Realm throws an + error when you attempt to open the existing realm. + + You can copy an unencrypted realm 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 1e1ed2af226..da2355bf520 100644 --- a/source/sdk/react-native/realm-files/encrypt.txt +++ b/source/sdk/react-native/realm-files/encrypt.txt @@ -22,6 +22,13 @@ 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 *cannot* encrypt an existing unencrypted realm. + If you pass an encryption key to a configuration + that does not already have one, Realm throws an + error when you attempt to open the existing realm. + 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 9c5a1b832a5..ea4d499ae27 100644 --- a/source/sdk/swift/realm-files/encrypt-a-realm.txt +++ b/source/sdk/swift/realm-files/encrypt-a-realm.txt @@ -26,6 +26,13 @@ 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 *cannot* encrypt an existing unencrypted realm. + If you pass an encryption key to a configuration + that does not already have one, Realm throws an + error when you attempt to open the existing realm. + Considerations --------------