Documentation/client_side_encryption/modes_usage.txt

   1 ==============================================
   2 Lustre client-level encryption modes and usage
   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 encryption modes and usage described here,
  11 extracted from fscrypt's doc, apply 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 Encryption modes
  17 ----------------
  18
  19 fscrypt allows one encryption mode to be specified for file contents
  20 and one encryption mode to be specified for filenames.  Different
  21 directory trees are permitted to use different encryption modes.
  22 Currently, the following pairs of encryption modes are supported:
  23
  24 - AES-256-XTS for contents and AES-256-CTS-CBC for filenames
  25 - AES-128-CBC for contents and AES-128-CTS-CBC for filenames
  26 - Adiantum for both contents and filenames
  27
  28 If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair.
  29
  30 AES-128-CBC was added only for low-powered embedded devices with
  31 crypto accelerators such as CAAM or CESA that do not support XTS.
  32
  33 Adiantum is a (primarily) stream cipher-based mode that is fast even
  34 on CPUs without dedicated crypto instructions.  It's also a true
  35 wide-block mode, unlike XTS.  It can also eliminate the need to derive
  36 per-file keys.  However, it depends on the security of two primitives,
  37 XChaCha12 and AES-256, rather than just one.  See the paper
  38 "Adiantum: length-preserving encryption for entry-level processors"
  39 (https://eprint.iacr.org/2018/720.pdf) for more details.  To use
  40 Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled.  Also, fast
  41 implementations of ChaCha and NHPoly1305 should be enabled, e.g.
  42 CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM.
  43
  44 Contents encryption
  45 -------------------
  46
  47 For file contents, each filesystem block is encrypted independently.
  48 Currently, only the case where the filesystem block size is equal to
  49 the system's page size (usually 4096 bytes) is supported.
  50
  51 Each block's IV is set to the logical block number within the file as
  52 a little endian number, except that:
  53
  54 - With CBC mode encryption, ESSIV is also used.  Specifically, each IV
  55   is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
  56   of the file's data encryption key.
  57
  58 - In the "direct key" configuration (FSCRYPT_POLICY_FLAG_DIRECT_KEY
  59   set in the fscrypt_policy), the file's nonce is also appended to the
  60   IV.  Currently this is only allowed with the Adiantum encryption
  61   mode.
  62
  63 Filenames encryption
  64 --------------------
  65
  66 For filenames, each full filename is encrypted at once.  Because of
  67 the requirements to retain support for efficient directory lookups and
  68 filenames of up to 255 bytes, the same IV is used for every filename
  69 in a directory.
  70
  71 However, each encrypted directory still uses a unique key; or
  72 alternatively (for the "direct key" configuration) has the file's
  73 nonce included in the IVs.  Thus, IV reuse is limited to within a
  74 single directory.
  75
  76 With CTS-CBC, the IV reuse means that when the plaintext filenames
  77 share a common prefix at least as long as the cipher block size (16
  78 bytes for AES), the corresponding encrypted filenames will also share
  79 a common prefix.  This is undesirable.  Adiantum does not have this
  80 weakness, as it is a wide-block encryption mode.
  81
  82 All supported filenames encryption modes accept any plaintext length
  83 >= 16 bytes; cipher block alignment is not required.  However,
  84 filenames shorter than 16 bytes are NUL-padded to 16 bytes before
  85 being encrypted.  In addition, to reduce leakage of filename lengths
  86 via their ciphertexts, all filenames are NUL-padded to the next 4, 8,
  87 16, or 32-byte boundary (configurable).  32 is recommended since this
  88 provides the best confidentiality, at the cost of making directory
  89 entries consume slightly more space.  Note that since NUL (``\0``) is
  90 not otherwise a valid character in filenames, the padding will never
  91 produce duplicate plaintexts.
  92
  93 Symbolic link targets are considered a type of filename and are
  94 encrypted in the same way as filenames in directory entries, except
  95 that IV reuse is not a problem as each symlink has its own inode.
  96
  97