docs: document data blob format

diff --git a/docs/backup-protocol.rst b/docs/backup-protocol.rst
index 27adcb1d5c87ccef18b76442efa29e3054e71869..f21c7efc60c2711c2d99eacc0cf35c516e8143b1 100644 (file)
--- a/docs/backup-protocol.rst
+++ b/docs/backup-protocol.rst
@@ -38,7 +38,7 @@ Upload Blobs
 ~~~~~~~~~~~~
 
 Uploading blobs is done using ``POST /blob``. The HTTP body contains the
-data encoded as ``DataBlob`` (see source code).
+data encoded as :ref:`Data Blob <data-blob-format>`).
 
 The file name needs to end with ``.blob``, and is automatically added
 to the backup manifest.
@@ -50,7 +50,7 @@ Upload Chunks
 Chunks belong to an index, so you first need to open an index (see
 below). After that, you can upload chunks using ``POST /fixed_chunk``
 and ``POST /dynamic_chunk``. The HTTP body contains the chunk data
-encoded as ``DataBlob`` (see source code).
+encoded as :ref:`Data Blob <data-blob-format>`).
 
 
 Upload Fixed Indexes
@@ -122,14 +122,14 @@ Download Blobs
 ~~~~~~~~~~~~~~
 
 Downloading blobs is done using ``GET /download``. The HTTP body contains the
-data encoded as ``DataBlob`` (see source code).
+data encoded as :ref:`Data Blob <data-blob-format>`.
 
 
 Download Chunks
 ~~~~~~~~~~~~~~~
 
 Downloading chunks is done using ``GET /chunk``. The HTTP body contains the
-data encoded as ``DataBlob`` (see source code).
+data encoded as :ref:`Data Blob <data-blob-format>`).
 
 
 Download Index Files

diff --git a/docs/file-formats.rst b/docs/file-formats.rst
index bb72564926216fd8df8b99a696988e12fb472c4f..71c4f468c0c9c975095467a6bad42b5b2fb3a591 100644 (file)
--- a/docs/file-formats.rst
+++ b/docs/file-formats.rst
@@ -6,7 +6,51 @@ File Formats
 Proxmox File Archive Format (``.pxar``)
 ---------------------------------------
 
-
 .. graphviz:: pxar-format-overview.dot
 
-             
+
+.. _data-blob-format:
+
+Data Blob Format
+----------------
+
+The data blob format is used to store small binary data. The magic number decides the exact format:
+
+.. list-table::
+   :widths: auto
+
+   * - ``[66, 171, 56, 7, 190, 131, 112, 161]``
+     - unencrypted
+     - uncompressed
+   * - ``[49, 185, 88, 66, 111, 182, 163, 127]``
+     - unencrypted
+     - compressed
+   * - ``[123, 103, 133, 190, 34, 45, 76, 240]``
+     - encrypted
+     - uncompressed
+   * - ``[230, 89, 27, 191, 11, 191, 216, 11]``
+     - encrypted
+     - compressed
+
+Compression algorithm is ``zstd``. Encryption cipher is ``AES_256_GCM``.
+
+Unencrypted blobs use the following format:
+
+.. list-table::
+   :widths: auto
+
+   * - ``MAGIC: [u8; 8]``
+   * - ``CRC32: [u8; 4]``
+   * - ``Data: (max 16MiB)``
+
+Encrypted blobs additionally contains a 16 byte IV, followed by a 16
+byte Authenticated Encyryption (AE) tag, followed by the encrypted
+data:
+
+.. list-table::
+
+   * - ``MAGIC: [u8; 8]``
+   * - ``CRC32: [u8; 4]``
+   * - ``ÌV: [u8; 16]``
+   * - ``TAG: [u8; 16]``
+   * - ``Data: (max 16MiB)``