@@ -77,10 +77,10 @@ Basic design
7777============
7878
7979We introduce ``struct blk_crypto_key `` to represent an inline encryption key and
80- how it will be used. This includes the actual bytes of the key; the size of the
81- key ; the algorithm and data unit size the key will be used with; and the number
82- of bytes needed to represent the maximum data unit number the key will be used
83- with.
80+ how it will be used. This includes the type of the key (raw or
81+ hardware-wrapped) ; the actual bytes of the key; the size of the key; the
82+ algorithm and data unit size the key will be used with; and the number of bytes
83+ needed to represent the maximum data unit number the key will be used with.
8484
8585We introduce ``struct bio_crypt_ctx `` to represent an encryption context. It
8686contains a data unit number and a pointer to a blk_crypto_key. We add pointers
@@ -301,3 +301,250 @@ kernel will pretend that the device does not support hardware inline encryption
301301When the crypto API fallback is enabled, this means that all bios with and
302302encryption context will use the fallback, and IO will complete as usual. When
303303the fallback is disabled, a bio with an encryption context will be failed.
304+
305+ .. _hardware_wrapped_keys :
306+
307+ Hardware-wrapped keys
308+ =====================
309+
310+ Motivation and threat model
311+ ---------------------------
312+
313+ Linux storage encryption (dm-crypt, fscrypt, eCryptfs, etc.) traditionally
314+ relies on the raw encryption key(s) being present in kernel memory so that the
315+ encryption can be performed. This traditionally isn't seen as a problem because
316+ the key(s) won't be present during an offline attack, which is the main type of
317+ attack that storage encryption is intended to protect from.
318+
319+ However, there is an increasing desire to also protect users' data from other
320+ types of attacks (to the extent possible), including:
321+
322+ - Cold boot attacks, where an attacker with physical access to a system suddenly
323+ powers it off, then immediately dumps the system memory to extract recently
324+ in-use encryption keys, then uses these keys to decrypt user data on-disk.
325+
326+ - Online attacks where the attacker is able to read kernel memory without fully
327+ compromising the system, followed by an offline attack where any extracted
328+ keys can be used to decrypt user data on-disk. An example of such an online
329+ attack would be if the attacker is able to run some code on the system that
330+ exploits a Meltdown-like vulnerability but is unable to escalate privileges.
331+
332+ - Online attacks where the attacker fully compromises the system, but their data
333+ exfiltration is significantly time-limited and/or bandwidth-limited, so in
334+ order to completely exfiltrate the data they need to extract the encryption
335+ keys to use in a later offline attack.
336+
337+ Hardware-wrapped keys are a feature of inline encryption hardware that is
338+ designed to protect users' data from the above attacks (to the extent possible),
339+ without introducing limitations such as a maximum number of keys.
340+
341+ Note that it is impossible to **fully ** protect users' data from these attacks.
342+ Even in the attacks where the attacker "just" gets read access to kernel memory,
343+ they can still extract any user data that is present in memory, including
344+ plaintext pagecache pages of encrypted files. The focus here is just on
345+ protecting the encryption keys, as those instantly give access to **all ** user
346+ data in any following offline attack, rather than just some of it (where which
347+ data is included in that "some" might not be controlled by the attacker).
348+
349+ Solution overview
350+ -----------------
351+
352+ Inline encryption hardware typically has "keyslots" into which software can
353+ program keys for the hardware to use; the contents of keyslots typically can't
354+ be read back by software. As such, the above security goals could be achieved
355+ if the kernel simply erased its copy of the key(s) after programming them into
356+ keyslot(s) and thereafter only referred to them via keyslot number.
357+
358+ However, that naive approach runs into a couple problems:
359+
360+ - It limits the number of unlocked keys to the number of keyslots, which
361+ typically is a small number. In cases where there is only one encryption key
362+ system-wide (e.g., a full-disk encryption key), that can be tolerable.
363+ However, in general there can be many logged-in users with many different
364+ keys, and/or many running applications with application-specific encrypted
365+ storage areas. This is especially true if file-based encryption (e.g.
366+ fscrypt) is being used.
367+
368+ - Inline crypto engines typically lose the contents of their keyslots if the
369+ storage controller (usually UFS or eMMC) is reset. Resetting the storage
370+ controller is a standard error recovery procedure that is executed if certain
371+ types of storage errors occur, and such errors can occur at any time.
372+ Therefore, when inline crypto is being used, the operating system must always
373+ be ready to reprogram the keyslots without user intervention.
374+
375+ Thus, it is important for the kernel to still have a way to "remind" the
376+ hardware about a key, without actually having the raw key itself.
377+
378+ Somewhat less importantly, it is also desirable that the raw keys are never
379+ visible to software at all, even while being initially unlocked. This would
380+ ensure that a read-only compromise of system memory will never allow a key to be
381+ extracted to be used off-system, even if it occurs when a key is being unlocked.
382+
383+ To solve all these problems, some vendors of inline encryption hardware have
384+ made their hardware support *hardware-wrapped keys *. Hardware-wrapped keys
385+ are encrypted keys that can only be unwrapped (decrypted) and used by hardware
386+ -- either by the inline encryption hardware itself, or by a dedicated hardware
387+ block that can directly provision keys to the inline encryption hardware.
388+
389+ (We refer to them as "hardware-wrapped keys" rather than simply "wrapped keys"
390+ to add some clarity in cases where there could be other types of wrapped keys,
391+ such as in file-based encryption. Key wrapping is a commonly used technique.)
392+
393+ The key which wraps (encrypts) hardware-wrapped keys is a hardware-internal key
394+ that is never exposed to software; it is either a persistent key (a "long-term
395+ wrapping key") or a per-boot key (an "ephemeral wrapping key"). The long-term
396+ wrapped form of the key is what is initially unlocked, but it is erased from
397+ memory as soon as it is converted into an ephemerally-wrapped key. In-use
398+ hardware-wrapped keys are always ephemerally-wrapped, not long-term wrapped.
399+
400+ As inline encryption hardware can only be used to encrypt/decrypt data on-disk,
401+ the hardware also includes a level of indirection; it doesn't use the unwrapped
402+ key directly for inline encryption, but rather derives both an inline encryption
403+ key and a "software secret" from it. Software can use the "software secret" for
404+ tasks that can't use the inline encryption hardware, such as filenames
405+ encryption. The software secret is not protected from memory compromise.
406+
407+ Key hierarchy
408+ -------------
409+
410+ Here is the key hierarchy for a hardware-wrapped key::
411+
412+ Hardware-wrapped key
413+ |
414+ |
415+ <Hardware KDF>
416+ |
417+ -----------------------------
418+ | |
419+ Inline encryption key Software secret
420+
421+ The components are:
422+
423+ - *Hardware-wrapped key *: a key for the hardware's KDF (Key Derivation
424+ Function), in ephemerally-wrapped form. The key wrapping algorithm is a
425+ hardware implementation detail that doesn't impact kernel operation, but a
426+ strong authenticated encryption algorithm such as AES-256-GCM is recommended.
427+
428+ - *Hardware KDF *: a KDF (Key Derivation Function) which the hardware uses to
429+ derive subkeys after unwrapping the wrapped key. The hardware's choice of KDF
430+ doesn't impact kernel operation, but it does need to be known for testing
431+ purposes, and it's also assumed to have at least a 256-bit security strength.
432+ All known hardware uses the SP800-108 KDF in Counter Mode with AES-256-CMAC,
433+ with a particular choice of labels and contexts; new hardware should use this
434+ already-vetted KDF.
435+
436+ - *Inline encryption key *: a derived key which the hardware directly provisions
437+ to a keyslot of the inline encryption hardware, without exposing it to
438+ software. In all known hardware, this will always be an AES-256-XTS key.
439+ However, in principle other encryption algorithms could be supported too.
440+ Hardware must derive distinct subkeys for each supported encryption algorithm.
441+
442+ - *Software secret *: a derived key which the hardware returns to software so
443+ that software can use it for cryptographic tasks that can't use inline
444+ encryption. This value is cryptographically isolated from the inline
445+ encryption key, i.e. knowing one doesn't reveal the other. (The KDF ensures
446+ this.) Currently, the software secret is always 32 bytes and thus is suitable
447+ for cryptographic applications that require up to a 256-bit security strength.
448+ Some use cases (e.g. full-disk encryption) won't require the software secret.
449+
450+ Example: in the case of fscrypt, the fscrypt master key (the key that protects a
451+ particular set of encrypted directories) is made hardware-wrapped. The inline
452+ encryption key is used as the file contents encryption key, while the software
453+ secret (rather than the master key directly) is used to key fscrypt's KDF
454+ (HKDF-SHA512) to derive other subkeys such as filenames encryption keys.
455+
456+ Note that currently this design assumes a single inline encryption key per
457+ hardware-wrapped key, without any further key derivation. Thus, in the case of
458+ fscrypt, currently hardware-wrapped keys are only compatible with the "inline
459+ encryption optimized" settings, which use one file contents encryption key per
460+ encryption policy rather than one per file. This design could be extended to
461+ make the hardware derive per-file keys using per-file nonces passed down the
462+ storage stack, and in fact some hardware already supports this; future work is
463+ planned to remove this limitation by adding the corresponding kernel support.
464+
465+ Kernel support
466+ --------------
467+
468+ The inline encryption support of the kernel's block layer ("blk-crypto") has
469+ been extended to support hardware-wrapped keys as an alternative to raw keys,
470+ when hardware support is available. This works in the following way:
471+
472+ - A ``key_types_supported `` field is added to the crypto capabilities in
473+ ``struct blk_crypto_profile ``. This allows device drivers to declare that
474+ they support raw keys, hardware-wrapped keys, or both.
475+
476+ - ``struct blk_crypto_key `` can now contain a hardware-wrapped key as an
477+ alternative to a raw key; a ``key_type `` field is added to
478+ ``struct blk_crypto_config `` to distinguish between the different key types.
479+ This allows users of blk-crypto to en/decrypt data using a hardware-wrapped
480+ key in a way very similar to using a raw key.
481+
482+ - A new method ``blk_crypto_ll_ops::derive_sw_secret `` is added. Device drivers
483+ that support hardware-wrapped keys must implement this method. Users of
484+ blk-crypto can call ``blk_crypto_derive_sw_secret() `` to access this method.
485+
486+ - The programming and eviction of hardware-wrapped keys happens via
487+ ``blk_crypto_ll_ops::keyslot_program `` and
488+ ``blk_crypto_ll_ops::keyslot_evict ``, just like it does for raw keys. If a
489+ driver supports hardware-wrapped keys, then it must handle hardware-wrapped
490+ keys being passed to these methods.
491+
492+ blk-crypto-fallback doesn't support hardware-wrapped keys. Therefore,
493+ hardware-wrapped keys can only be used with actual inline encryption hardware.
494+
495+ All the above deals with hardware-wrapped keys in ephemerally-wrapped form only.
496+ To get such keys in the first place, new block device ioctls have been added to
497+ provide a generic interface to creating and preparing such keys:
498+
499+ - ``BLKCRYPTOIMPORTKEY `` converts a raw key to long-term wrapped form. It takes
500+ in a pointer to a ``struct blk_crypto_import_key_arg ``. The caller must set
501+ ``raw_key_ptr `` and ``raw_key_size `` to the pointer and size (in bytes) of the
502+ raw key to import. On success, ``BLKCRYPTOIMPORTKEY `` returns 0 and writes
503+ the resulting long-term wrapped key blob to the buffer pointed to by
504+ ``lt_key_ptr ``, which is of maximum size ``lt_key_size ``. It also updates
505+ ``lt_key_size `` to be the actual size of the key. On failure, it returns -1
506+ and sets errno. An errno of ``EOPNOTSUPP `` indicates that the block device
507+ does not support hardware-wrapped keys. An errno of ``EOVERFLOW `` indicates
508+ that the output buffer did not have enough space for the key blob.
509+
510+ - ``BLKCRYPTOGENERATEKEY `` is like ``BLKCRYPTOIMPORTKEY ``, but it has the
511+ hardware generate the key instead of importing one. It takes in a pointer to
512+ a ``struct blk_crypto_generate_key_arg ``.
513+
514+ - ``BLKCRYPTOPREPAREKEY `` converts a key from long-term wrapped form to
515+ ephemerally-wrapped form. It takes in a pointer to a ``struct
516+ blk_crypto_prepare_key_arg ``. The caller must set ``lt_key_ptr `` and
517+ ``lt_key_size `` to the pointer and size (in bytes) of the long-term wrapped
518+ key blob to convert. On success, ``BLKCRYPTOPREPAREKEY `` returns 0 and writes
519+ the resulting ephemerally-wrapped key blob to the buffer pointed to by
520+ ``eph_key_ptr ``, which is of maximum size ``eph_key_size ``. It also updates
521+ ``eph_key_size `` to be the actual size of the key. On failure, it returns -1
522+ and sets errno. Errno values of ``EOPNOTSUPP `` and ``EOVERFLOW `` mean the
523+ same as they do for ``BLKCRYPTOIMPORTKEY ``. An errno of ``EBADMSG `` indicates
524+ that the long-term wrapped key is invalid.
525+
526+ Userspace needs to use either ``BLKCRYPTOIMPORTKEY `` or ``BLKCRYPTOGENERATEKEY ``
527+ once to create a key, and then ``BLKCRYPTOPREPAREKEY `` each time the key is
528+ unlocked and added to the kernel. Note that these ioctls have no relevance for
529+ raw keys; they are only for hardware-wrapped keys.
530+
531+ Testability
532+ -----------
533+
534+ Both the hardware KDF and the inline encryption itself are well-defined
535+ algorithms that don't depend on any secrets other than the unwrapped key.
536+ Therefore, if the unwrapped key is known to software, these algorithms can be
537+ reproduced in software in order to verify the ciphertext that is written to disk
538+ by the inline encryption hardware.
539+
540+ However, the unwrapped key will only be known to software for testing if the
541+ "import" functionality is used. Proper testing is not possible in the
542+ "generate" case where the hardware generates the key itself. The correct
543+ operation of the "generate" mode thus relies on the security and correctness of
544+ the hardware RNG and its use to generate the key, as well as the testing of the
545+ "import" mode as that should cover all parts other than the key generation.
546+
547+ For an example of a test that verifies the ciphertext written to disk in the
548+ "import" mode, see the fscrypt hardware-wrapped key tests in xfstests, or
549+ `Android's vts_kernel_encryption_test
550+ <https://android.googlesource.com/platform/test/vts-testcase/kernel/+/refs/heads/main/encryption/> `_.
0 commit comments