Documentation/block/inline-encryption.rst

12 Inline encryption hardware sits logically between memory and disk, and can
14 can control exactly how the inline encryption hardware will en/decrypt the data
18 Some inline encryption hardware accepts all encryption parameters including raw
20 hardware instead has a fixed number of "keyslots" and requires that the key,
24 Note that inline encryption hardware is very different from traditional crypto
27 hardware operates on I/O requests.  Thus, inline encryption hardware needs to be
30 Inline encryption hardware is also very different from "self-encrypting drives",
33 verify the correctness of the resulting ciphertext.  Inline encryption hardware
42 encryption hardware is absent.  We also want inline encryption to work with
44 the inline encryption hardware of the underlying devices if present, or else
56 - Different inline encryption hardware has different supported algorithms,
61 - Inline encryption hardware usually (but not always) requires that keys be
81 hardware-wrapped); the actual bytes of the key; the size of the key; the
96 blk_crypto_profile serves as the way that drivers for inline encryption hardware
102 The blk_crypto_profile also manages the hardware's keyslots, when applicable.
136 filesystems) to be testable without real inline encryption hardware, and
169 without actual inline encryption hardware.  Second, similar to actual inline
170 encryption hardware, the crypto API doesn't accept keys directly in requests but
176 Note that regardless of whether real inline encryption hardware or
179 encryption hardware's implementation and the kernel crypto API's implementation
190 block_device -- either via hardware or via blk-crypto-fallback.  This function
247 hardware, e.g. how to program and evict keyslots.  Most drivers will need to
264 If there are situations where the inline encryption hardware loses the contents
284 At the time of this patch, there is no real hardware that supports both these
297 that it changes the on disk format depending on whether hardware inline
302 Because there isn't any real hardware yet, it seems prudent to assume that
303 hardware implementations might not implement both features together correctly,
305 kernel will pretend that the device does not support hardware inline encryption
343 Hardware-wrapped keys are a feature of inline encryption hardware that is
358 Inline encryption hardware typically has "keyslots" into which software can
359 program keys for the hardware to use; the contents of keyslots typically can't
382 hardware about a key, without actually having the raw key itself.
389 To solve all these problems, some vendors of inline encryption hardware have
390 made their hardware support *hardware-wrapped keys*.  Hardware-wrapped keys
391 are encrypted keys that can only be unwrapped (decrypted) and used by hardware
392 -- either by the inline encryption hardware itself, or by a dedicated hardware
393 block that can directly provision keys to the inline encryption hardware.
395 (We refer to them as "hardware-wrapped keys" rather than simply "wrapped keys"
399 The key which wraps (encrypts) hardware-wrapped keys is a hardware-internal key
404 hardware-wrapped keys are always ephemerally-wrapped, not long-term wrapped.
406 As inline encryption hardware can only be used to encrypt/decrypt data on-disk,
407 the hardware also includes a level of indirection; it doesn't use the unwrapped
410 tasks that can't use the inline encryption hardware, such as filenames
416 Here is the key hierarchy for a hardware-wrapped key::
429 - *Hardware-wrapped key*: a key for the hardware's KDF (Key Derivation
431   hardware implementation detail that doesn't impact kernel operation, but a
434 - *Hardware KDF*: a KDF (Key Derivation Function) which the hardware uses to
435   derive subkeys after unwrapping the wrapped key.  The hardware's choice of KDF
438   All known hardware uses the SP800-108 KDF in Counter Mode with AES-256-CMAC,
439   with a particular choice of labels and contexts; new hardware should use this
442 - *Inline encryption key*: a derived key which the hardware directly provisions
443   to a keyslot of the inline encryption hardware, without exposing it to
444   software.  In all known hardware, this will always be an AES-256-XTS key.
448 - *Software secret*: a derived key which the hardware returns to software so
457 particular set of encrypted directories) is made hardware-wrapped.  The inline
463 hardware-wrapped key, without any further key derivation.  Thus, in the case of
464 fscrypt, currently hardware-wrapped keys are only compatible with the "inline
467 make the hardware derive per-file keys using per-file nonces passed down the
468 storage stack, and in fact some hardware already supports this; future work is
475 been extended to support hardware-wrapped keys as an alternative to raw keys,
476 when hardware support is available.  This works in the following way:
480   they support raw keys, hardware-wrapped keys, or both.
482 - ``struct blk_crypto_key`` can now contain a hardware-wrapped key as an
485   This allows users of blk-crypto to en/decrypt data using a hardware-wrapped
489   that support hardware-wrapped keys must implement this method.  Users of
492 - The programming and eviction of hardware-wrapped keys happens via
495   driver supports hardware-wrapped keys, then it must handle hardware-wrapped
498 blk-crypto-fallback doesn't support hardware-wrapped keys.  Therefore,
499 hardware-wrapped keys can only be used with actual inline encryption hardware.
501 All the above deals with hardware-wrapped keys in ephemerally-wrapped form only.
513   does not support hardware-wrapped keys.  An errno of ``EOVERFLOW`` indicates
517   hardware generate the key instead of importing one.  It takes in a pointer to
535 raw keys; they are only for hardware-wrapped keys.
540 Both the hardware KDF and the inline encryption itself are well-defined
544 by the inline encryption hardware.
548 "generate" case where the hardware generates the key itself.  The correct
550 the hardware RNG and its use to generate the key, as well as the testing of the
554 "import" mode, see the fscrypt hardware-wrapped key tests in xfstests, or