Add various documentation indices

[nncp.git] / doc / eblob.texi

diff --git a/doc/eblob.texi b/doc/eblob.texi
index 74e6661021ff879bbfa312684c6bde892f4d8d9f..a7e9b8f47d43c6cf5d5642950845d8e18955ee87 100644 (file)
--- a/doc/eblob.texi
+++ b/doc/eblob.texi
@@ -1,7 +1,9 @@
 @node EBlob
+@cindex eblob
+@cindex encrypted configuration
 @unnumbered EBlob format
 
-Eblob is an encrypted blob (binary large object, in the terms of
+EBlob is an encrypted blob (binary large object, in the terms of
 databases), holding any kind of symmetrically encrypted data with the
 passphrase used to derive the key. It is used to secure configuration
 files, holding valuable private keys, allowing them to be transferred
@@ -20,6 +22,9 @@ is @strong{not} the password. Password is a short string of high entropy
 low-entropy characters. Low-entropy text is much more easier to
 remember, and its length provides pretty enough entropy as a result.
 
+@cindex password
+@cindex balloon
+@cindex Argon2
 Password strengthening function is applied to that passphrase to
 mitigate brute-force and dictionary attacks on it. Here,
 @url{https://crypto.stanford.edu/balloon/, Balloon} memory-hard password
@@ -29,19 +34,19 @@ attacks and seems more secure than Argon2
 (@url{https://password-hashing.net/, Password Hashing Competition}
 winner).
 
-Eblob is an @url{https://tools.ietf.org/html/rfc4506, XDR}-encoded structure:
+EBlob is an @url{https://tools.ietf.org/html/rfc4506, XDR}-encoded structure:
 
 @verbatim
-+-------+------------------+------------+
-| MAGIC | S | T | P | SALT | BLOB | MAC |
-+-------+------------------+------------+
++-------+------------------+------+
+| MAGIC | S | T | P | SALT | BLOB |
++-------+------------------+------+
 @end verbatim
 
 @multitable @columnfractions 0.2 0.3 0.5
 @headitem @tab XDR type @tab Value
 @item Magic number @tab
     8-byte, fixed length opaque data @tab
-    @verb{|N N C P B 0x00 0x00 0x02|}
+    @verb{|N N C P B 0x00 0x00 0x03|}
 @item S, T, P @tab
     unsigned integer @tab
     Space cost, time cost and parallel jobs number
@@ -50,22 +55,12 @@ Eblob is an @url{https://tools.ietf.org/html/rfc4506, XDR}-encoded structure:
     Randomly generated salt
 @item Blob @tab
     variable length opaque data @tab
-    Encrypted data itself
-@item MAC @tab
-    32 bytes, fixed length opaque data @tab
-    BLAKE2b-256 MAC of encrypted blob
+    Authenticated and Encrypted data itself
 @end multitable
 
 @enumerate
-@item generate the main key using @code{balloon(BLAKE2b-256, S, T, P,
-salt, password)}
-@item initialize @url{https://blake2.net/, BLAKE2Xb} XOF with generated
-main key and 96-byte output length
-@item feed @verb{|N N C P B 0x00 0x00 0x02|} magic number to XOF
-@item read 32-bytes of blob encryption key
-@item read 64-bytes of blob authentication key
-@item encrypt the blob using @url{https://cr.yp.to/chacha.html,
-ChaCha20}. Blob is splitted on 128 KiB blocks. Each block is encrypted
-with increasing nonce counter
-@item authenticate ciphertext with MAC
+@item generate the key using @code{balloon(BLAKE2b-256, S, T, P, salt, password)}
+@item encrypt and authenticate blob using
+    @url{https://cr.yp.to/chacha.html, ChaCha20}-@url{https://en.wikipedia.org/wiki/Poly1305, Poly1305}.
+    EBlob packet itself, with empty blob field, is fed as an additional authenticated data
 @end enumerate