Documentation/block/inline-encryption.rst

19 keys directly in low-level I/O requests.  However, most inline encryption
61 - Inline encryption hardware usually (but not always) requires that keys be
64   key for every I/O request, but rather keep track of which keys are in the
67 - Upper layers typically define a specific end-of-life for crypto keys, e.g.
69   At these times, keys are wiped from memory.  We must provide a way for upper
70   layers to also evict keys from any keyslots they are present in.
98 functions to program and evict keys) to upper layers.  Each device driver that
170 encryption hardware, the crypto API doesn't accept keys directly in requests but
171 rather requires that keys be set ahead of time, and setting keys can be
313 Hardware-wrapped keys
330   in-use encryption keys, then uses these keys to decrypt user data on-disk.
334   keys can be used to decrypt user data on-disk.  An example of such an online
341   keys to use in a later offline attack.
343 Hardware-wrapped keys are a feature of inline encryption hardware that is
345 without introducing limitations such as a maximum number of keys.
351 protecting the encryption keys, as those instantly give access to **all** user
359 program keys for the hardware to use; the contents of keyslots typically can't
366 - It limits the number of unlocked keys to the number of keyslots, which
370   keys, and/or many running applications with application-specific encrypted
384 Somewhat less importantly, it is also desirable that the raw keys are never
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
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"
396 to add some clarity in cases where there could be other types of 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.
460 (HKDF-SHA512) to derive other subkeys such as filenames encryption keys.
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
475 been extended to support hardware-wrapped keys as an alternative to raw keys,
480   they support raw keys, hardware-wrapped keys, or both.
489   that support hardware-wrapped keys must implement this method.  Users of
492 - The programming and eviction of hardware-wrapped keys happens via
494   ``blk_crypto_ll_ops::keyslot_evict``, just like it does for raw keys.  If a
495   driver supports hardware-wrapped keys, then it must handle hardware-wrapped
496   keys being passed to these methods.
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.
502 To get such keys in the first place, new block device ioctls have been added to
503 provide a generic interface to creating and preparing such keys:
513   does not support hardware-wrapped keys.  An errno of ``EOVERFLOW`` indicates
535 raw keys; they are only for hardware-wrapped keys.