Lines Matching +full:hardware +full:- +full:based
1 .. SPDX-License-Identifier: GPL-2.0
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
19 keys directly in low-level I/O requests. However, most inline encryption
20 hardware instead has a fixed number of "keyslots" and requires that the key,
22 low-level I/O request then just contains a keyslot index and data unit number.
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",
31 such as those based on the TCG Opal or ATA Security standards. Self-encrypting
32 drives don't provide fine-grained control of encryption and provide no way to
33 verify the correctness of the resulting ciphertext. Inline encryption hardware
34 provides fine-grained control of encryption, including the choice of key and
42 encryption hardware is absent. We also want inline encryption to work with
43 layered devices like device-mapper and loopback (i.e. we want to be able to use
44 the inline encryption hardware of the underlying devices if present, or else
50 - We need a way for upper layers (e.g. filesystems) to specify an encryption
56 - Different inline encryption hardware has different supported algorithms,
61 - Inline encryption hardware usually (but not always) requires that keys be
65 keyslots and reuse an already-programmed keyslot when possible.
67 - Upper layers typically define a specific end-of-life for crypto keys, e.g.
72 - When possible, device-mapper devices must be able to pass through the inline
74 sense for device-mapper devices to have keyslots themselves.
81 hardware-wrapped); the actual bytes of the key; the size of the key; the
95 encryption-related state for a particular inline encryption device. 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.
109 in-flight I/O requests are using it. When the block layer creates a
112 keyslot (a keyslot that isn't in-use by any I/O), then programs the key into the
113 least-recently-used idle keyslot using the function the device driver provided.
124 retained, since the remaining bios have been verified to be merge-compatible
127 To make it possible for inline encryption to work with request_queue based
132 blk-crypto-fallback
136 filesystems) to be testable without real inline encryption hardware, and
141 Therefore, we also introduce *blk-crypto-fallback*, which is an implementation
142 of inline encryption using the kernel crypto API. blk-crypto-fallback is built
146 handle en/decryption of the bio using blk-crypto-fallback.
148 For encryption, the data cannot be encrypted in-place, as callers usually rely
149 on it being unmodified. Instead, blk-crypto-fallback allocates bounce pages,
152 blk-crypto-fallback completes the original bio. If the original bio is too
155 For decryption, blk-crypto-fallback "wraps" the bio's completion callback
158 successfully, blk-crypto-fallback restores the bio's original completion
159 callback and private data, then decrypts the bio's data in-place using the
161 Afterwards, blk-crypto-fallback completes the bio.
163 In both cases, the bios that blk-crypto-fallback submits no longer have an
166 blk-crypto-fallback also defines its own blk_crypto_profile and has its own
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
174 makes sense for blk-crypto-fallback.
176 Note that regardless of whether real inline encryption hardware or
177 blk-crypto-fallback is used, the ciphertext written to disk (and hence the
178 on-disk format of data) will be the same (assuming that both the inline
179 encryption hardware's implementation and the kernel crypto API's implementation
182 blk-crypto-fallback is optional and is controlled by the
190 block_device -- either via hardware or via blk-crypto-fallback. This function
193 size, etc. This function can be useful if blk-crypto-fallback is disabled.
199 was called earlier). This is needed to initialize blk-crypto-fallback if it
233 must call ``blk_crypto_profile_init()`` (or its resource-managed variant
241 hardware, e.g. how to program and evict keyslots. Most drivers will need to
254 while the device is runtime-suspended, then the driver must also set the ``dev``
256 resumed before any of the low-level operations are called.
258 If there are situations where the inline encryption hardware loses the contents
269 Request queue based layered devices like dm-rq that wish to support inline
272 pass a clone of that request to another request_queue, blk-crypto will
278 At the time of this patch, there is no real hardware that supports both these
289 re-generate the integrity info from the ciphertext data and store that on disk
291 that it changes the on disk format depending on whether hardware inline
296 Because there isn't any real hardware yet, it seems prudent to assume that
297 hardware implementations might not implement both features together correctly,
299 kernel will pretend that the device does not support hardware inline encryption
307 Hardware-wrapped keys
311 ---------------------------
313 Linux storage encryption (dm-crypt, fscrypt, eCryptfs, etc.) traditionally
322 - Cold boot attacks, where an attacker with physical access to a system suddenly
324 in-use encryption keys, then uses these keys to decrypt user data on-disk.
326 - Online attacks where the attacker is able to read kernel memory without fully
328 keys can be used to decrypt user data on-disk. An example of such an online
330 exploits a Meltdown-like vulnerability but is unable to escalate privileges.
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
337 Hardware-wrapped keys are a feature of inline encryption hardware that is
350 -----------------
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
360 - It limits the number of unlocked keys to the number of keyslots, which
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.
368 - Inline crypto engines typically lose the contents of their keyslots if the
376 hardware about a key, without actually having the raw key itself.
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.
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.
389 (We refer to them as "hardware-wrapped keys" rather than simply "wrapped keys"
391 such as in file-based encryption. Key wrapping is a commonly used technique.)
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
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.
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
404 tasks that can't use the inline encryption hardware, such as filenames
408 -------------
410 Here is the key hierarchy for a hardware-wrapped key::
412 Hardware-wrapped key
415 <Hardware KDF>
417 -----------------------------
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.
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
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.
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.
440 Hardware must derive distinct subkeys for each supported encryption algorithm.
442 - *Software secret*: a derived key which the hardware returns to software so
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.
451 particular set of encrypted directories) is made hardware-wrapped. The inline
454 (HKDF-SHA512) to derive other subkeys such as filenames encryption keys.
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
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
466 --------------
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:
472 - A ``key_types_supported`` field is added to the crypto capabilities in
474 they support raw keys, hardware-wrapped keys, or both.
476 - ``struct blk_crypto_key`` can now contain a hardware-wrapped key as an
479 This allows users of blk-crypto to en/decrypt data using a hardware-wrapped
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.
486 - The programming and eviction of hardware-wrapped keys happens via
489 driver supports hardware-wrapped keys, then it must handle hardware-wrapped
492 blk-crypto-fallback doesn't support hardware-wrapped keys. Therefore,
493 hardware-wrapped keys can only be used with actual inline encryption hardware.
495 All the above deals with hardware-wrapped keys in ephemerally-wrapped form only.
499 - ``BLKCRYPTOIMPORTKEY`` converts a raw key to long-term wrapped form. It takes
503 the resulting long-term wrapped key blob to the buffer pointed to by
505 ``lt_key_size`` to be the actual size of the key. On failure, it returns -1
507 does not support hardware-wrapped keys. An errno of ``EOVERFLOW`` indicates
510 - ``BLKCRYPTOGENERATEKEY`` is like ``BLKCRYPTOIMPORTKEY``, but it has the
511 hardware generate the key instead of importing one. It takes in a pointer to
514 - ``BLKCRYPTOPREPAREKEY`` converts a key from long-term wrapped form to
515 ephemerally-wrapped form. It takes in a pointer to a ``struct
517 ``lt_key_size`` to the pointer and size (in bytes) of the long-term wrapped
519 the resulting ephemerally-wrapped key blob to the buffer pointed to by
521 ``eph_key_size`` to be the actual size of the key. On failure, it returns -1
524 that the long-term wrapped key is invalid.
529 raw keys; they are only for hardware-wrapped keys.
532 -----------
534 Both the hardware KDF and the inline encryption itself are well-defined
538 by the inline encryption hardware.
542 "generate" case where the hardware generates the key itself. The correct
544 the hardware RNG and its use to generate the key, as well as the testing of the
548 "import" mode, see the fscrypt hardware-wrapped key tests in xfstests, or
550 <https://android.googlesource.com/platform/test/vts-testcase/kernel/+/refs/heads/main/encryption/>`…