summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordrebs <drebs@riseup.net>2017-11-03 10:47:35 -0200
committerdrebs <drebs@riseup.net>2017-11-03 10:47:35 -0200
commitc3c1721b8e0f614a7333dc1ce8a8f5a5c196480e (patch)
treea62dee3786058da4f57f46c2233e28aa25063e77
parente7135df8167e77dccd8f2117153594cb05cad276 (diff)
[doc] add blob data format to docs
-rw-r--r--docs/reference/blobs/client.rst43
1 files changed, 34 insertions, 9 deletions
diff --git a/docs/reference/blobs/client.rst b/docs/reference/blobs/client.rst
index 734866fe..5d9369f3 100644
--- a/docs/reference/blobs/client.rst
+++ b/docs/reference/blobs/client.rst
@@ -14,6 +14,35 @@ called ``{uuid}_blobs.db`` that lies in the same directory as the Soledad
Client's JSON documents database (see :ref:`client-databases`). All actions
performed locally are mirrored remotelly using the :ref:`blobs-http-api`.
+Client-side encryption and authentication
+-----------------------------------------
+
+When uploading, the content of the blob is encrypted with a symmetric secret
+prior to being sent to the server. When downloading, the content of the blob is
+decrypted accordingly. See :ref:`client-encryption` for more details.
+
+When a blob is uploaded by a client, a preamble is created and prepended to the
+encrypted content. The preamble is an encoded struct that contains the
+following metadata:
+
+- A 2 character **magic hexadecimal number** for easy identification of a Blob
+ data type. Currently, the value used for the magic number is: ``\x13\x37``.
+- The **cryptographic scheme** used for encryption. Currently, the only valid
+ schemes are ``symkey`` and ``external``.
+- The **encryption method** used. Currently, the only valid methods are
+ ``aes_256_gcm`` and ``pgp``.
+- The **initialization vector**.
+- The **blob_id**.
+- The **revision**, which is a fixed value (``ImmutableRev``) in the case of
+ blobs.
+- The **size** of the blob.
+
+The final format of a blob that is uploaded to the server is the following:
+
+- The URL-safe base64-encoded **preamble** (see above).
+- A space to act as a **separator**.
+- The URL-safe base64-encoded concatenated **encrypted data and MAC tag**.
+
Namespaces
----------
@@ -22,6 +51,7 @@ blobs without interfering in each another. Namespaces are also used to
implement the server-side :ref:`incoming-http-api`, used for mail delivery. All
methods that deal with blobs storage, transfer and flagging provide
a `namespace` parameter. If no namespace is given, the value `default` is used.
+See :ref:`blobmanager-api` for information on how to use namespaces.
Remote flags
------------
@@ -29,7 +59,8 @@ Remote flags
In order to allow clients to control the processing of blobs that are delivered
by external applications, the Blobs API has the concept of **remote flags**.
The client can get and set the following flags for Blobs that reside in the
-server: ``PENDING``, ``PROCESSING``, ``PROCESSED``, and ``FAILED``.
+server: ``PENDING``, ``PROCESSING``, ``PROCESSED``, and ``FAILED``. See
+:ref:`blobmanager-api` for more information on how to use flags.
Remote listing
--------------
@@ -38,11 +69,5 @@ The client can obtain a list of blobs in the server side so it can compare with
its own local list and queue up blobs for download and upload. The remote
listing can be ordered by *upload date* and filtered by *namespace* and *flag*.
The listing can also only return the number of matches instead of the whole
-content.
-
-Client-side encryption
-----------------------
-
-When uploading, the content of the blob is encrypted with a symmetric secret
-prior to being sent to the server. When downloading, the content of the blob is
-decrypted accordingly.
+content. See :ref:`blobmanager-api` for more information on how to use remote
+listing.