doc/eblob.texi

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