Documentation/client_side_encryption/key_hierarchy.txt

   1 ============================================
   2 Lustre client-level encryption key hierarchy
   3 ============================================
   4
   5 Lustre client-level encryption relies on kernel's fscrypt, and more
   6 precisely on v2 encryption policies.
   7 fscrypt is a library which filesystems can hook into to support
   8 transparent encryption of files and directories.
   9
  10 As a consequence, the following key hierarchy description, extracted
  11 from fscrypt's, is directly applicable to Lustre client-level encryption.
  12
  13 Ref:
  14 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/filesystems/fscrypt.rst
  15
  16 Master Keys
  17 -----------
  18
  19 Each encrypted directory tree is protected by a *master key*.  Master
  20 keys can be up to 64 bytes long, and must be at least as long as the
  21 greater of the key length needed by the contents and filenames
  22 encryption modes being used.  For example, if AES-256-XTS is used for
  23 contents encryption, the master key must be 64 bytes (512 bits).  Note
  24 that the XTS mode is defined to require a key twice as long as that
  25 required by the underlying block cipher.
  26
  27 To "unlock" an encrypted directory tree, userspace must provide the
  28 appropriate master key.  There can be any number of master keys, each
  29 of which protects any number of directory trees on any number of
  30 filesystems.
  31
  32 Master keys should be pseudorandom, i.e. indistinguishable from random
  33 bytestrings of the same length.  This implies that users **must not**
  34 directly use a password as a master key, zero-pad a shorter key, or
  35 repeat a shorter key.  Instead, users should generate master keys
  36 either using a cryptographically secure random number generator, or by
  37 using a KDF (Key Derivation Function).  Note that whenever a KDF is
  38 used to "stretch" a lower-entropy secret such as a passphrase, it is
  39 critical that a KDF designed for this purpose be used, such as scrypt,
  40 PBKDF2, or Argon2.
  41
  42 Key derivation function
  43 -----------------------
  44
  45 With one exception, fscrypt never uses the master key(s) for
  46 encryption directly.  Instead, they are only used as input to a KDF
  47 (Key Derivation Function) to derive the actual keys.
  48
  49 For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
  50 passed as the "input keying material", no salt is used, and a distinct
  51 "application-specific information string" is used for each distinct
  52 key to be derived.  For example, when a per-file encryption key is
  53 derived, the application-specific information string is the file's
  54 nonce prefixed with "fscrypt\0" and a context byte.  Different context
  55 bytes are used for other types of derived keys.
  56
  57 HKDF-SHA512 is preferred KDF because HKDF is more flexible, is
  58 nonreversible, and evenly distributes entropy from the master key.
  59 HKDF is also standardized and widely used by other software.
  60
  61 Per-file keys
  62 -------------
  63
  64 Since each master key can protect many files, it is necessary to
  65 "tweak" the encryption of each file so that the same plaintext in two
  66 files doesn't map to the same ciphertext, or vice versa.  In most
  67 cases, fscrypt does this by deriving per-file keys.  When a new
  68 encrypted inode (regular file, directory, or symlink) is created,
  69 fscrypt randomly generates a 16-byte nonce and stores it in the
  70 inode's encryption xattr.  Then, it uses a KDF (as described in `Key
  71 derivation function`_) to derive the file's key from the master key
  72 and nonce.
  73
  74 Key derivation was chosen over key wrapping because wrapped keys would
  75 require larger xattrs which would be less likely to fit in-line in the
  76 filesystem's inode table, and there didn't appear to be any
  77 significant advantages to key wrapping.  In particular, currently
  78 there is no requirement to support unlocking a file with multiple
  79 alternative master keys or to support rotating master keys.  Instead,
  80 the master keys may be wrapped in userspace, e.g. as is done by the
  81 `fscrypt <https://github.com/google/fscrypt>`_ tool.
  82
  83 Including the inode number in the IVs was considered.  However, it was
  84 rejected as it would have prevented ext4 filesystems from being
  85 resized, and by itself still wouldn't have been sufficient to prevent
  86 the same key from being directly reused for both XTS and CTS-CBC.
  87
  88 DIRECT_KEY and per-mode keys
  89 ----------------------------
  90
  91 The Adiantum encryption mode is suitable for both contents and
  92 filenames encryption, and it accepts long IVs --- long enough to hold
  93 both an 8-byte logical block number and a 16-byte per-file nonce.
  94 Also, the overhead of each Adiantum key is greater than that of an
  95 AES-256-XTS key.
  96
  97 Therefore, to improve performance and save memory, for Adiantum a
  98 "direct key" configuration is supported.  When the user has enabled
  99 this by setting FSCRYPT_POLICY_FLAG_DIRECT_KEY in the fscrypt policy,
 100 per-file keys are not used.  Instead, whenever any data (contents or
 101 filenames) is encrypted, the file's 16-byte nonce is included in the
 102 IV.  Moreover, for v2 encryption policies, the encryption is done with
 103 a per-mode key derived using the KDF.  Users may use the same master
 104 key for other v2 encryption policies.
 105
 106 Key identifiers
 107 ---------------
 108
 109 For master keys used for v2 encryption policies, a unique 16-byte "key
 110 identifier" is also derived using the KDF.  This value is stored in
 111 the clear, since it is needed to reliably identify the key itself.
 112