From f770b8761065663dc82f328e87b3630a00d58438 Mon Sep 17 00:00:00 2001 From: drebs Date: Sat, 2 Jun 2018 09:57:27 -0300 Subject: Clarify storage secrets use case and backups in documentation --- docs/reference/storage-secrets.rst | 52 +++++++++++++++++++++++++------------- 1 file 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. -- cgit v1.2.3