Clarify storage secrets use case and backups in documentation

1 files changed, 35 insertions, 17 deletions

diff --git a/docs/reference/storage-secrets.rst b/docs/reference/storage-secrets.rst
index d3886d7a..842be7d5 100644
--- a/docs/reference/storage-secrets.rst
+++ b/docs/reference/storage-secrets.rst
@@ -3,13 +3,39 @@
 Storage secrets
 ===============
 
-Soledad randomly generates secrets that are used to derive encryption keys for
-protecting all data that is stored in the server and in the local storage.
-These secrets are themselves encrypted using a key derived from the user’s
-passphrase, and saved locally on disk.
+All data stored locally and remotelly is encrypted using "storage secrets".
 
-The encrypted secrets are stored in a local file in the user's in a JSON
-structure that looks like this::
+Storage secrets are backed up in the provider
+---------------------------------------------
+
+Storage secrets are currently backed up in the provider (encrypted with the
+user's passphrase) for the case where the user looses or resets her device (see
+:ref:`shared-database` for more information). There are plans to make this
+feature optional, allowing for less trust in the provider while increasing the
+responsibility of the user.
+
+Because of that, whenever Soledad is initialized for the first time, it checks
+for existence of storage secrets in local storage. If these are not found, then
+it checks if there is an available backup in the provider. These steps are
+currently mandatory because Soledad needs to make sure it will have any
+previously used secrets in order to encrypt/decrypt previously synchronized
+data accordingly. If the device is offline during the first initialization,
+Soledad will raise an exception and fail to initialize.
+
+For testing purposes, it is possible to initialize Soledad passing a `None`
+value as server url, but offline mode is currently not supported and may lead
+to unintended consequences.
+
+If the user looses her passphrase, there is currently no way of recovering her
+data.
+
+Format of the secrets file
+--------------------------
+
+When created for the first time, storage secrets are themselves encrypted using
+a key derived from the user’s passphrase, and saved locally on disk. The
+encrypted secrets are stored in a local file in the user's in a JSON structure
+that looks like this::
 
     {
         'version': 2,
@@ -23,15 +49,7 @@ structure that looks like this::
     }
 
 When a client application first wants to use Soledad, it must provide the
-user’s password to unlock the storage secrets. Currently, the storage secrets
-are shared among all devices with access to a particular user's Soledad
-database.
+user’s password to unlock the storage secrets.
 
-The storage secrets are currently backed up in the provider (encrypted with the
-user's passphrase) for the case where the user looses or resets her device (see
-:ref:`shared-database` for more information). There are plans to make this
-feature optional, allowing for less trust in the provider while increasing the
-responsibility of the user.
-
-If the user looses her passphrase, there is currently no way of recovering her
-data.
+Currently, the same storage secrets are shared among all devices with access to
+a particular user's Soledad database.