[doc] generalize client side encryption doc

5 files changed, 68 insertions, 34 deletions

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