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 | MAC |
  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 0x02|}
  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     Encrypted data itself
  54 @item MAC @tab
  55     32 bytes, fixed length opaque data @tab
  56     BLAKE2b-256 MAC of encrypted blob
  57 @end multitable
  58
  59 @enumerate
  60 @item generate the main key using @code{balloon(BLAKE2b-256, S, T, P,
  61 salt, password)}
  62 @item initialize @url{https://blake2.net/, BLAKE2Xb} XOF with generated
  63 main key and 96-byte output length
  64 @item feed @verb{|N N C P B 0x00 0x00 0x02|} magic number to XOF
  65 @item read 32-bytes of blob encryption key
  66 @item read 64-bytes of blob authentication key
  67 @item encrypt the blob using @url{https://cr.yp.to/chacha.html,
  68 ChaCha20}. Blob is splitted on 128 KiB blocks. Each block is encrypted
  69 with increasing nonce counter
  70 @item authenticate ciphertext with MAC
  71 @end enumerate