doc/eblob.texi

   1 @node EBlob
   2 @unnumbered EBlob format
   3
   4 Eblob is an encrypted blob (binary large object, in the terms of
   5 databases), holding any kind of symmetrically encrypted data with the
   6 passphrase used to derive the key. It is used to secure configuration
   7 files, holding valuable private keys, allowing them to be transferred
   8 safely everywhere.
   9
  10 In fact it uses two factors for securing the data:
  11
  12 @itemize
  13 @item @strong{salt}, that is kept inside @file{eblob}, something @emph{you have}
  14 @item @strong{passphrase}, that is kept inside the head, something @emph{you know}
  15 @end itemize
  16
  17 Whole security depends on the passphrase itself. Pay attention that this
  18 is @strong{not} the password. Password is a short string of high entropy
  19 (highly random) characters, but passphrase is (very) long string of
  20 low-entropy characters. Low-entropy text is much more easier to
  21 remember, and its length provides pretty enough entropy as a result.
  22
  23 Password strengthening function is applied to that passphrase to
  24 mitigate brute-force and dictionary attacks on it. Here,
  25 @url{https://crypto.stanford.edu/balloon/, Balloon} memory-hard password
  26 hashing function is used, together with BLAKE2b-256 hash. It has proven
  27 memory-hardness properties, very easy to implement, resistant to cache
  28 attacks and seems more secure than Argon2
  29 (@url{https://password-hashing.net/, Password Hashing Competition}
  30 winner).
  31
  32 Eblob is an @url{https://tools.ietf.org/html/rfc4506, XDR}-encoded structure:
  33
  34 @verbatim
  35 +-------+------------------+------+
  36 | MAGIC | S | T | P | SALT | BLOB |
  37 +-------+------------------+------+
  38 @end verbatim
  39
  40 @multitable @columnfractions 0.2 0.3 0.5
  41 @headitem @tab XDR type @tab Value
  42 @item Magic number @tab
  43     8-byte, fixed length opaque data @tab
  44     @verb{|N N C P B 0x00 0x00 0x03|}
  45 @item S, T, P @tab
  46     unsigned integer @tab
  47     Space cost, time cost and parallel jobs number
  48 @item Salt @tab
  49     32 bytes, fixed length opaque data @tab
  50     Randomly generated salt
  51 @item Blob @tab
  52     variable length opaque data @tab
  53     Authenticated and Encrypted data itself
  54 @end multitable
  55
  56 @enumerate
  57 @item generate the main key using @code{balloon(BLAKE2b-256, S, T, P,
  58 salt, password)}
  59 @item initialize @url{https://blake2.net/, BLAKE2Xb} XOF with generated
  60 main key and 32-byte output length
  61 @item feed @verb{|N N C P B 0x00 0x00 0x03|} magic number to XOF
  62 @item read 32-bytes of blob AEAD encryption key
  63 @item encrypt and authenticate blob using
  64     @url{https://cr.yp.to/chacha.html, ChaCha20}-@url{https://en.wikipedia.org/wiki/Poly1305, Poly1305}.
  65     Blob is splitted on 128 KiB blocks. Each block is encrypted with
  66     increasing nonce counter. Eblob packet itself, with empty blob
  67     field, is fed as an additional authenticated data
  68 @end enumerate