diff options
| -rw-r--r-- | docs/intro.rst | 2 | ||||
| -rw-r--r-- | docs/reference.rst | 2 | ||||
| -rw-r--r-- | docs/reference/blobs/sync.rst | 19 | ||||
| -rw-r--r-- | docs/reference/client-database.rst | 2 | ||||
| -rw-r--r-- | docs/reference/client-encryption.rst | 52 | ||||
| -rw-r--r-- | docs/reference/document-encryption.rst | 27 | ||||
| -rw-r--r-- | docs/reference/document-sync.rst | 2 |
7 files changed, 70 insertions, 36 deletions
diff --git a/docs/intro.rst b/docs/intro.rst index 90ae6cf3..2a1768e4 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -14,7 +14,7 @@ Key aspects of Soledad include: <soledad-server>` and a :ref:`client application library <soledad-client>`. * **Client-side encrypted sync:** Soledad puts very little trust in the server - by :ref:`encrypting all data <document-encryption>` before it is + by :ref:`encrypting all data <client-encryption>` before it is :ref:`synchronized <document-sync>` to the server and by limiting ways in which the server can modify the user’s data. diff --git a/docs/reference.rst b/docs/reference.rst index 97c1e40f..bd3cb9de 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -10,7 +10,7 @@ This page gathers reference documentation to understanding the internals of Sole reference/storage-secrets reference/server-database reference/client-database - reference/document-encryption + reference/client-encryption reference/document-sync reference/auth reference/blobs diff --git a/docs/reference/blobs/sync.rst b/docs/reference/blobs/sync.rst index bdfad0cf..93fb7cb0 100644 --- a/docs/reference/blobs/sync.rst +++ b/docs/reference/blobs/sync.rst @@ -1,3 +1,5 @@ +.. _blobs-sync: + Blobs Synchronization ===================== @@ -5,7 +7,7 @@ Because blobs are immutable, synchronization is much simpler than the JSON-based :ref:`document-sync`. The synchronization process is as follows: 1. The client asks the server for a list of Blobs and compares it with the local list. -2. A local list is updated with pending blobs download and upload. +2. A local list is updated with pending downloads and uploads. 3. Downloads and uploads are triggered. Immutability brings some characteristics to the blobs system: @@ -13,11 +15,18 @@ Immutability brings some characteristics to the blobs system: - There's no need for storage of versions or revisions. - Updating is not possible (you would need to delete and recreate a blob). +Client-side encryption +---------------------- + +Blobs are encrypted before being sent to the server and decrypted after being +received. A MAC is also calculated to authenticate the contents of each blob. +See :ref:`client-encryption` for more details of how this is done. + Synchronization status ---------------------- -In the client-side, each has an associated synchronization status, which can be -one of: +In the client-side, each blob has an associated synchronization status, which +can be one of: - ``SYNCED``: The blob exists both in this client and in the server. - ``PENDING_UPLOAD``: The blob was inserted locally, but has not yet been uploaded. @@ -29,8 +38,8 @@ Concurrency limits In order to increase the speed of synchronization on the client-size, concurrent database operations and transfers to the server are allowed. Despite -that, to prevent indiscriminated use or client resources (cpu, memory, -bandwith), concurrenty limits are set both for database operations and for data +that, to prevent indiscriminated use of client resources (cpu, memory, +bandwith), concurrenty limits are set both for database operations and data transfer. Transfer retries diff --git a/docs/reference/client-database.rst b/docs/reference/client-database.rst index ac59c1bd..85827817 100644 --- a/docs/reference/client-database.rst +++ b/docs/reference/client-database.rst @@ -7,7 +7,7 @@ These are some important information about Soledad's client-side databases: - Soledad Client uses `SQLCipher <https://www.zetetic.net/sqlcipher/>`_ for storing data. -- :ref:`Documents <document-encryption>` and :ref:`blobs <blobs>` are stored in +- :ref:`Documents <client-encryption>` and :ref:`blobs <blobs>` are stored in different databases protected with the same symmetric key. - The symmetric key used to unlock databases is chosen randomly and is stored encrypted by the user's passphrase (see :ref:`storage-secrets` for more details). diff --git a/docs/reference/client-encryption.rst b/docs/reference/client-encryption.rst new file mode 100644 index 00000000..acffff52 --- /dev/null +++ b/docs/reference/client-encryption.rst @@ -0,0 +1,52 @@ +.. _client-encryption: + +Client-side encryption and authentication +========================================= + +Before any user data is sent to the server, Soledad Client **symmetrically +encrypts** it using `AES-256 +<https://en.wikipedia.org/wiki/Advanced_Encryption_Standard>`_ operating in +`GCM mode <https://en.wikipedia.org/wiki/Galois/Counter_Mode>`_. That mode of +encryption automatically calculates a **Message Authentication Code** (a `MAC +<https://en.wikipedia.org/wiki/Message_authentication_code>`_) during block +encryption, and so gives Soledad the ability to encrypt on the fly while +transmitting data to the server. Similarly, when downloading a symmetrically +encrypted document from the server, Soledad Client will decrypt it and verify +the MAC tag in the end before accepting the document. + +The symmetric key used to encrypt a document is derived from the storage secret +and the document id, with HMAC using SHA-256 as a hash function. + +MAC verification of JSON documents +---------------------------------- + +JSON documents are versioned (see :ref:`document-sync`), so in this case the +calculation of the MAC also takes into account the document revision to avoid +tampering. Soledad Client will refuse to accept a document if it does not +include a higher revision. In this way, the server cannot rollback a document +to an older revision. The server also cannot delete a document, since document +deletion is handled by removing the document contents, marking it as deleted, +and incrementing the revision. However, a server can withhold from the client +new documents and new revisions of a document (including withholding document +deletion). + +MAC verification of Blobs +------------------------- + +Because Blobs are immutable (see :ref:`blobs-sync`), in this case the MAC is +calculated over the content of the blob only (i.e. no metadata is taken into +account). Blob downloads will fail irrecoverably if the client is unable to +verify the MAC after a certain number of retries. + +Outsourced encryption by third-party applications +------------------------------------------------- + +Soledad Client will allways do **symmetric encryption** with a secret known +only to the client. But data can also be delivered directly to the user's +database in the server by other applications. One example is mail delivery: the +MX application receives a message targetted to a user, encrypts it with the +user's OpenPGP public key and delivers it directly to the user's database in +the server. + +Server-side applications can define their own encryption schemes and Soledad +Client will not attempt decryption and verification in those cases. diff --git a/docs/reference/document-encryption.rst b/docs/reference/document-encryption.rst deleted file mode 100644 index 724c78d1..00000000 --- a/docs/reference/document-encryption.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _document-encryption: - -Document encryption -=================== - -Before a JSON document is sent to the server, Soledad Client symmetrically -encrypts it using AES-256 operating in GCM mode. That mode of encryption -automatically calculates a MAC during block encryption, and so gives Soledad -the ability to encrypt on the fly while transmitting data to the server. -Similarly, when downloading a symmetrically encrypted document from the server, -Soledad Client will decrypt it and verify the MAC tag in the end before -accepting the document. - -Soledad Client will allways do *symmetric encryption*. Server-side applications -can define their own encryption schemes and Soledad Client will not try to -decrypt in those cases. The symmetric key used to encrypt a document is derived -from the storage secret and the document id, with HMAC using SHA-256 as a hash -function. - -The calculation of the MAC also takes into account the document revision to -avoid tampering. Soledad Client will refuse to accept a document if it does not -include a higher revision. In this way, the server cannot rollback a document -to an older revision. The server also cannot delete a document, since document -deletion is handled by removing the document contents, marking it as deleted, -and incrementing the revision. However, a server can withhold from the client -new documents and new revisions of a document (including withholding document -deletion). diff --git a/docs/reference/document-sync.rst b/docs/reference/document-sync.rst index 51a02945..3640df48 100644 --- a/docs/reference/document-sync.rst +++ b/docs/reference/document-sync.rst @@ -9,7 +9,7 @@ Soledad follows `the U1DB synchronization protocol * A synchronization always happens between the Soledad Server and one Soledad Client. Many clients can synchronize with the same server. -* Soledad Client :ref:`always encrypts <document-encryption>` before sending +* Soledad Client :ref:`always encrypts <client-encryption>` before sending data to the server. * Soledad Client refuses to receive a document if it is encrypted and the MAC |