1.. SPDX-License-Identifier: GPL-2.0 2 3.. _inline_encryption: 4 5================= 6Inline Encryption 7================= 8 9Background 10========== 11 12Inline encryption hardware sits logically between memory and disk, and can 13en/decrypt data as it goes in/out of the disk. For each I/O request, software 14can control exactly how the inline encryption hardware will en/decrypt the data 15in terms of key, algorithm, data unit size (the granularity of en/decryption), 16and data unit number (a value that determines the initialization vector(s)). 17 18Some inline encryption hardware accepts all encryption parameters including raw 19keys directly in low-level I/O requests. However, most inline encryption 20hardware instead has a fixed number of "keyslots" and requires that the key, 21algorithm, and data unit size first be programmed into a keyslot. Each 22low-level I/O request then just contains a keyslot index and data unit number. 23 24Note that inline encryption hardware is very different from traditional crypto 25accelerators, which are supported through the kernel crypto API. Traditional 26crypto accelerators operate on memory regions, whereas inline encryption 27hardware operates on I/O requests. Thus, inline encryption hardware needs to be 28managed by the block layer, not the kernel crypto API. 29 30Inline encryption hardware is also very different from "self-encrypting drives", 31such as those based on the TCG Opal or ATA Security standards. Self-encrypting 32drives don't provide fine-grained control of encryption and provide no way to 33verify the correctness of the resulting ciphertext. Inline encryption hardware 34provides fine-grained control of encryption, including the choice of key and 35initialization vector for each sector, and can be tested for correctness. 36 37Objective 38========= 39 40We want to support inline encryption hardware in the kernel. The API for using 41such hardware should also support a fallback to the CPU, so that users only need 42to use a single API and more of the code can be tested without actual hardware. 43We also want inline encryption to work with layered devices like device-mapper 44and loopback (i.e. we want to be able to use the inline encryption hardware of 45the underlying devices if present, or else fall back to the CPU). 46 47Constraints and notes 48===================== 49 50- We need a way for upper layers (e.g. filesystems) to specify an encryption 51 context to use for en/decrypting a bio, and device drivers (e.g. UFSHCD) need 52 to be able to use that encryption context when they process the request. 53 Encryption contexts also introduce constraints on bio merging; the block layer 54 needs to be aware of these constraints. 55 56- Different inline encryption hardware has different supported algorithms, 57 supported data unit sizes, maximum data unit numbers, etc. We call these 58 properties the "crypto capabilities". We need a way for device drivers to 59 advertise crypto capabilities to upper layers in a generic way. 60 61- Inline encryption hardware usually (but not always) requires that keys be 62 programmed into keyslots before being used. Since programming keyslots may be 63 slow and there may not be very many keyslots, we shouldn't just program the 64 key for every I/O request, but rather keep track of which keys are in the 65 keyslots and reuse an already-programmed keyslot when possible. 66 67- Upper layers typically define a specific end-of-life for crypto keys, e.g. 68 when an encrypted directory is locked or when a crypto mapping is torn down. 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. 71 72- When possible, device-mapper devices must be able to pass through the inline 73 encryption support of their underlying devices. However, it doesn't make 74 sense for device-mapper devices to have keyslots themselves. 75 76Basic design 77============ 78 79We introduce ``struct blk_crypto_key`` to represent an inline encryption key and 80how it will be used. This includes the type of the key (raw or 81hardware-wrapped); the actual bytes of the key; the size of the key; the 82algorithm and data unit size the key will be used with; and the number of bytes 83needed to represent the maximum data unit number the key will be used with. 84 85We introduce ``struct bio_crypt_ctx`` to represent an encryption context. It 86contains a data unit number and a pointer to a blk_crypto_key. We add pointers 87to a bio_crypt_ctx to ``struct bio`` and ``struct request``; this allows users 88of the block layer (e.g. filesystems) to provide an encryption context when 89creating a bio and have it be passed down the stack for processing by the block 90layer and device drivers. Note that the encryption context doesn't explicitly 91say whether to encrypt or decrypt, as that is implicit from the direction of the 92bio; WRITE means encrypt, and READ means decrypt. 93 94We also introduce ``struct blk_crypto_profile`` to contain all generic inline 95encryption-related state for a particular inline encryption device. The 96blk_crypto_profile serves as the way that drivers for inline encryption hardware 97advertise their crypto capabilities and provide certain functions (e.g., 98functions to program and evict keys) to upper layers. Each device driver that 99wants to support inline encryption will construct a blk_crypto_profile, then 100associate it with the disk's request_queue. 101 102The blk_crypto_profile also manages the hardware's keyslots, when applicable. 103This happens in the block layer, so that users of the block layer can just 104specify encryption contexts and don't need to know about keyslots at all, nor do 105device drivers need to care about most details of keyslot management. 106 107Specifically, for each keyslot, the block layer (via the blk_crypto_profile) 108keeps track of which blk_crypto_key that keyslot contains (if any), and how many 109in-flight I/O requests are using it. When the block layer creates a 110``struct request`` for a bio that has an encryption context, it grabs a keyslot 111that already contains the key if possible. Otherwise it waits for an idle 112keyslot (a keyslot that isn't in-use by any I/O), then programs the key into the 113least-recently-used idle keyslot using the function the device driver provided. 114In both cases, the resulting keyslot is stored in the ``crypt_keyslot`` field of 115the request, where it is then accessible to device drivers and is released after 116the request completes. 117 118``struct request`` also contains a pointer to the original bio_crypt_ctx. 119Requests can be built from multiple bios, and the block layer must take the 120encryption context into account when trying to merge bios and requests. For two 121bios/requests to be merged, they must have compatible encryption contexts: both 122unencrypted, or both encrypted with the same key and contiguous data unit 123numbers. Only the encryption context for the first bio in a request is 124retained, since the remaining bios have been verified to be merge-compatible 125with the first bio. 126 127To make it possible for inline encryption to work with request_queue based 128layered devices, when a request is cloned, its encryption context is cloned as 129well. When the cloned request is submitted, it is then processed as usual; this 130includes getting a keyslot from the clone's target device if needed. 131 132blk-crypto-fallback 133=================== 134 135It is desirable for the inline encryption support of upper layers (e.g. 136filesystems) to be testable without real inline encryption hardware, and 137likewise for the block layer's keyslot management logic. It is also desirable 138to allow upper layers to just always use inline encryption rather than have to 139implement encryption in multiple ways. 140 141Therefore, we also introduce *blk-crypto-fallback*, which is an implementation 142of inline encryption using the kernel crypto API. blk-crypto-fallback is built 143into the block layer, so it works on any block device without any special setup. 144Essentially, when a bio with an encryption context is submitted to a 145block_device that doesn't support that encryption context, the block layer will 146handle en/decryption of the bio using blk-crypto-fallback. 147 148For encryption, the data cannot be encrypted in-place, as callers usually rely 149on it being unmodified. Instead, blk-crypto-fallback allocates bounce pages, 150fills a new bio with those bounce pages, encrypts the data into those bounce 151pages, and submits that "bounce" bio. When the bounce bio completes, 152blk-crypto-fallback completes the original bio. If the original bio is too 153large, multiple bounce bios may be required; see the code for details. 154 155For decryption, blk-crypto-fallback "wraps" the bio's completion callback 156(``bi_end_io``) and private data (``bi_private``) with its own, unsets the 157bio's encryption context, then submits the bio. If the read completes 158successfully, blk-crypto-fallback restores the bio's original completion 159callback and private data, then decrypts the bio's data in-place using the 160kernel crypto API. Decryption happens from a workqueue, as it may sleep. 161Afterwards, blk-crypto-fallback completes the bio. 162 163In both cases, the bios that blk-crypto-fallback submits no longer have an 164encryption context. Therefore, lower layers only see standard unencrypted I/O. 165 166blk-crypto-fallback also defines its own blk_crypto_profile and has its own 167"keyslots"; its keyslots contain ``struct crypto_skcipher`` objects. The reason 168for this is twofold. First, it allows the keyslot management logic to be tested 169without actual inline encryption hardware. Second, similar to actual inline 170encryption hardware, the crypto API doesn't accept keys directly in requests but 171rather requires that keys be set ahead of time, and setting keys can be 172expensive; moreover, allocating a crypto_skcipher can't happen on the I/O path 173at all due to the locks it takes. Therefore, the concept of keyslots still 174makes sense for blk-crypto-fallback. 175 176Note that regardless of whether real inline encryption hardware or 177blk-crypto-fallback is used, the ciphertext written to disk (and hence the 178on-disk format of data) will be the same (assuming that both the inline 179encryption hardware's implementation and the kernel crypto API's implementation 180of the algorithm being used adhere to spec and function correctly). 181 182blk-crypto-fallback is optional and is controlled by the 183``CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK`` kernel configuration option. 184 185API presented to users of the block layer 186========================================= 187 188``blk_crypto_init_key()`` allows users to initialize a blk_crypto_key. 189 190Users must call ``blk_crypto_start_using_key()`` before actually starting to use 191a blk_crypto_key on a block_device. This is needed to initialize 192blk-crypto-fallback if it will be needed. This must not be called from the data 193path, as this may have to allocate resources, which may deadlock in that case. 194 195Next, to attach an encryption context to a bio, users should call 196``bio_crypt_set_ctx()``. This function allocates a bio_crypt_ctx and attaches 197it to a bio, given the blk_crypto_key and the data unit number that will be used 198for en/decryption. Users don't need to worry about freeing the bio_crypt_ctx 199later, as that happens automatically when the bio is freed or reset. 200 201To submit a bio that uses inline encryption, users must call 202``blk_crypto_submit_bio()`` instead of the usual ``submit_bio()``. This will 203submit the bio to the underlying driver if it supports inline crypto, or else 204call the blk-crypto fallback routines before submitting normal bios to the 205underlying drivers. 206 207Finally, when done using inline encryption with a blk_crypto_key on a 208block_device, users must call ``blk_crypto_evict_key()``. This ensures that 209the key is evicted from all keyslots it may be programmed into and unlinked from 210any kernel data structures it may be linked into. 211 212In summary, for users of the block layer, the lifecycle of a blk_crypto_key is 213as follows: 214 2151. ``blk_crypto_init_key()`` 2162. ``blk_crypto_start_using_key()`` 2173. ``bio_crypt_set_ctx()`` (potentially many times) 2184. ``blk_crypto_evict_key()`` (after all I/O has completed) 2195. Zeroize the blk_crypto_key (this has no dedicated function) 220 221If a blk_crypto_key is being used on multiple block_devices, then 222``blk_crypto_start_using_key()`` and ``blk_crypto_evict_key()`` must be called 223on each block_device. 224 225API presented to device drivers 226=============================== 227 228A device driver that wants to support inline encryption must set up a 229blk_crypto_profile in the request_queue of its device. To do this, it first 230must call ``blk_crypto_profile_init()`` (or its resource-managed variant 231``devm_blk_crypto_profile_init()``), providing the number of keyslots. 232 233Next, it must advertise its crypto capabilities by setting fields in the 234blk_crypto_profile, e.g. ``modes_supported`` and ``max_dun_bytes_supported``. 235 236It then must set function pointers in the ``ll_ops`` field of the 237blk_crypto_profile to tell upper layers how to control the inline encryption 238hardware, e.g. how to program and evict keyslots. Most drivers will need to 239implement ``keyslot_program`` and ``keyslot_evict``. For details, see the 240comments for ``struct blk_crypto_ll_ops``. 241 242Once the driver registers a blk_crypto_profile with a request_queue, I/O 243requests the driver receives via that queue may have an encryption context. All 244encryption contexts will be compatible with the crypto capabilities declared in 245the blk_crypto_profile, so drivers don't need to worry about handling 246unsupported requests. Also, if a nonzero number of keyslots was declared in the 247blk_crypto_profile, then all I/O requests that have an encryption context will 248also have a keyslot which was already programmed with the appropriate key. 249 250If the driver implements runtime suspend and its blk_crypto_ll_ops don't work 251while the device is runtime-suspended, then the driver must also set the ``dev`` 252field of the blk_crypto_profile to point to the ``struct device`` that will be 253resumed before any of the low-level operations are called. 254 255If there are situations where the inline encryption hardware loses the contents 256of its keyslots, e.g. device resets, the driver must handle reprogramming the 257keyslots. To do this, the driver may call ``blk_crypto_reprogram_all_keys()``. 258 259Finally, if the driver used ``blk_crypto_profile_init()`` instead of 260``devm_blk_crypto_profile_init()``, then it is responsible for calling 261``blk_crypto_profile_destroy()`` when the crypto profile is no longer needed. 262 263Layered Devices 264=============== 265 266Request queue based layered devices like dm-rq that wish to support inline 267encryption need to create their own blk_crypto_profile for their request_queue, 268and expose whatever functionality they choose. When a layered device wants to 269pass a clone of that request to another request_queue, blk-crypto will 270initialize and prepare the clone as necessary. 271 272Interaction between inline encryption and blk integrity 273======================================================= 274 275At the time of this patch, there is no real hardware that supports both these 276features. However, these features do interact with each other, and it's not 277completely trivial to make them both work together properly. In particular, 278when a WRITE bio wants to use inline encryption on a device that supports both 279features, the bio will have an encryption context specified, after which 280its integrity information is calculated (using the plaintext data, since 281the encryption will happen while data is being written), and the data and 282integrity info is sent to the device. Obviously, the integrity info must be 283verified before the data is encrypted. After the data is encrypted, the device 284must not store the integrity info that it received with the plaintext data 285since that might reveal information about the plaintext data. As such, it must 286re-generate the integrity info from the ciphertext data and store that on disk 287instead. Another issue with storing the integrity info of the plaintext data is 288that it changes the on disk format depending on whether hardware inline 289encryption support is present or the kernel crypto API fallback is used (since 290if the fallback is used, the device will receive the integrity info of the 291ciphertext, not that of the plaintext). 292 293Because there isn't any real hardware yet, it seems prudent to assume that 294hardware implementations might not implement both features together correctly, 295and disallow the combination for now. Whenever a device supports integrity, the 296kernel will pretend that the device does not support hardware inline encryption 297(by setting the blk_crypto_profile in the request_queue of the device to NULL). 298When the crypto API fallback is enabled, this means that all bios with an 299encryption context will use the fallback, and IO will complete as usual. When 300the fallback is disabled, a bio with an encryption context will be failed. 301 302.. _hardware_wrapped_keys: 303 304Hardware-wrapped keys 305===================== 306 307Motivation and threat model 308--------------------------- 309 310Linux storage encryption (dm-crypt, fscrypt, eCryptfs, etc.) traditionally 311relies on the raw encryption key(s) being present in kernel memory so that the 312encryption can be performed. This traditionally isn't seen as a problem because 313the key(s) won't be present during an offline attack, which is the main type of 314attack that storage encryption is intended to protect from. 315 316However, there is an increasing desire to also protect users' data from other 317types of attacks (to the extent possible), including: 318 319- Cold boot attacks, where an attacker with physical access to a system suddenly 320 powers it off, then immediately dumps the system memory to extract recently 321 in-use encryption keys, then uses these keys to decrypt user data on-disk. 322 323- Online attacks where the attacker is able to read kernel memory without fully 324 compromising the system, followed by an offline attack where any extracted 325 keys can be used to decrypt user data on-disk. An example of such an online 326 attack would be if the attacker is able to run some code on the system that 327 exploits a Meltdown-like vulnerability but is unable to escalate privileges. 328 329- Online attacks where the attacker fully compromises the system, but their data 330 exfiltration is significantly time-limited and/or bandwidth-limited, so in 331 order to completely exfiltrate the data they need to extract the encryption 332 keys to use in a later offline attack. 333 334Hardware-wrapped keys are a feature of inline encryption hardware that is 335designed to protect users' data from the above attacks (to the extent possible), 336without introducing limitations such as a maximum number of keys. 337 338Note that it is impossible to **fully** protect users' data from these attacks. 339Even in the attacks where the attacker "just" gets read access to kernel memory, 340they can still extract any user data that is present in memory, including 341plaintext pagecache pages of encrypted files. The focus here is just on 342protecting the encryption keys, as those instantly give access to **all** user 343data in any following offline attack, rather than just some of it (where which 344data is included in that "some" might not be controlled by the attacker). 345 346Solution overview 347----------------- 348 349Inline encryption hardware typically has "keyslots" into which software can 350program keys for the hardware to use; the contents of keyslots typically can't 351be read back by software. As such, the above security goals could be achieved 352if the kernel simply erased its copy of the key(s) after programming them into 353keyslot(s) and thereafter only referred to them via keyslot number. 354 355However, that naive approach runs into a couple problems: 356 357- It limits the number of unlocked keys to the number of keyslots, which 358 typically is a small number. In cases where there is only one encryption key 359 system-wide (e.g., a full-disk encryption key), that can be tolerable. 360 However, in general there can be many logged-in users with many different 361 keys, and/or many running applications with application-specific encrypted 362 storage areas. This is especially true if file-based encryption (e.g. 363 fscrypt) is being used. 364 365- Inline crypto engines typically lose the contents of their keyslots if the 366 storage controller (usually UFS or eMMC) is reset. Resetting the storage 367 controller is a standard error recovery procedure that is executed if certain 368 types of storage errors occur, and such errors can occur at any time. 369 Therefore, when inline crypto is being used, the operating system must always 370 be ready to reprogram the keyslots without user intervention. 371 372Thus, it is important for the kernel to still have a way to "remind" the 373hardware about a key, without actually having the raw key itself. 374 375Somewhat less importantly, it is also desirable that the raw keys are never 376visible to software at all, even while being initially unlocked. This would 377ensure that a read-only compromise of system memory will never allow a key to be 378extracted to be used off-system, even if it occurs when a key is being unlocked. 379 380To solve all these problems, some vendors of inline encryption hardware have 381made their hardware support *hardware-wrapped keys*. Hardware-wrapped keys 382are encrypted keys that can only be unwrapped (decrypted) and used by hardware 383-- either by the inline encryption hardware itself, or by a dedicated hardware 384block that can directly provision keys to the inline encryption hardware. 385 386(We refer to them as "hardware-wrapped keys" rather than simply "wrapped keys" 387to add some clarity in cases where there could be other types of wrapped keys, 388such as in file-based encryption. Key wrapping is a commonly used technique.) 389 390The key which wraps (encrypts) hardware-wrapped keys is a hardware-internal key 391that is never exposed to software; it is either a persistent key (a "long-term 392wrapping key") or a per-boot key (an "ephemeral wrapping key"). The long-term 393wrapped form of the key is what is initially unlocked, but it is erased from 394memory as soon as it is converted into an ephemerally-wrapped key. In-use 395hardware-wrapped keys are always ephemerally-wrapped, not long-term wrapped. 396 397As inline encryption hardware can only be used to encrypt/decrypt data on-disk, 398the hardware also includes a level of indirection; it doesn't use the unwrapped 399key directly for inline encryption, but rather derives both an inline encryption 400key and a "software secret" from it. Software can use the "software secret" for 401tasks that can't use the inline encryption hardware, such as filenames 402encryption. The software secret is not protected from memory compromise. 403 404Key hierarchy 405------------- 406 407Here is the key hierarchy for a hardware-wrapped key:: 408 409 Hardware-wrapped key 410 | 411 | 412 <Hardware KDF> 413 | 414 ----------------------------- 415 | | 416 Inline encryption key Software secret 417 418The components are: 419 420- *Hardware-wrapped key*: a key for the hardware's KDF (Key Derivation 421 Function), in ephemerally-wrapped form. The key wrapping algorithm is a 422 hardware implementation detail that doesn't impact kernel operation, but a 423 strong authenticated encryption algorithm such as AES-256-GCM is recommended. 424 425- *Hardware KDF*: a KDF (Key Derivation Function) which the hardware uses to 426 derive subkeys after unwrapping the wrapped key. The hardware's choice of KDF 427 doesn't impact kernel operation, but it does need to be known for testing 428 purposes, and it's also assumed to have at least a 256-bit security strength. 429 All known hardware uses the SP800-108 KDF in Counter Mode with AES-256-CMAC, 430 with a particular choice of labels and contexts; new hardware should use this 431 already-vetted KDF. 432 433- *Inline encryption key*: a derived key which the hardware directly provisions 434 to a keyslot of the inline encryption hardware, without exposing it to 435 software. In all known hardware, this will always be an AES-256-XTS key. 436 However, in principle other encryption algorithms could be supported too. 437 Hardware must derive distinct subkeys for each supported encryption algorithm. 438 439- *Software secret*: a derived key which the hardware returns to software so 440 that software can use it for cryptographic tasks that can't use inline 441 encryption. This value is cryptographically isolated from the inline 442 encryption key, i.e. knowing one doesn't reveal the other. (The KDF ensures 443 this.) Currently, the software secret is always 32 bytes and thus is suitable 444 for cryptographic applications that require up to a 256-bit security strength. 445 Some use cases (e.g. full-disk encryption) won't require the software secret. 446 447Example: in the case of fscrypt, the fscrypt master key (the key that protects a 448particular set of encrypted directories) is made hardware-wrapped. The inline 449encryption key is used as the file contents encryption key, while the software 450secret (rather than the master key directly) is used to key fscrypt's KDF 451(HKDF-SHA512) to derive other subkeys such as filenames encryption keys. 452 453Note that currently this design assumes a single inline encryption key per 454hardware-wrapped key, without any further key derivation. Thus, in the case of 455fscrypt, currently hardware-wrapped keys are only compatible with the "inline 456encryption optimized" settings, which use one file contents encryption key per 457encryption policy rather than one per file. This design could be extended to 458make the hardware derive per-file keys using per-file nonces passed down the 459storage stack, and in fact some hardware already supports this; future work is 460planned to remove this limitation by adding the corresponding kernel support. 461 462Kernel support 463-------------- 464 465The inline encryption support of the kernel's block layer ("blk-crypto") has 466been extended to support hardware-wrapped keys as an alternative to raw keys, 467when hardware support is available. This works in the following way: 468 469- A ``key_types_supported`` field is added to the crypto capabilities in 470 ``struct blk_crypto_profile``. This allows device drivers to declare that 471 they support raw keys, hardware-wrapped keys, or both. 472 473- ``struct blk_crypto_key`` can now contain a hardware-wrapped key as an 474 alternative to a raw key; a ``key_type`` field is added to 475 ``struct blk_crypto_config`` to distinguish between the different key types. 476 This allows users of blk-crypto to en/decrypt data using a hardware-wrapped 477 key in a way very similar to using a raw key. 478 479- A new method ``blk_crypto_ll_ops::derive_sw_secret`` is added. Device drivers 480 that support hardware-wrapped keys must implement this method. Users of 481 blk-crypto can call ``blk_crypto_derive_sw_secret()`` to access this method. 482 483- The programming and eviction of hardware-wrapped keys happens via 484 ``blk_crypto_ll_ops::keyslot_program`` and 485 ``blk_crypto_ll_ops::keyslot_evict``, just like it does for raw keys. If a 486 driver supports hardware-wrapped keys, then it must handle hardware-wrapped 487 keys being passed to these methods. 488 489blk-crypto-fallback doesn't support hardware-wrapped keys. Therefore, 490hardware-wrapped keys can only be used with actual inline encryption hardware. 491 492All the above deals with hardware-wrapped keys in ephemerally-wrapped form only. 493To get such keys in the first place, new block device ioctls have been added to 494provide a generic interface to creating and preparing such keys: 495 496- ``BLKCRYPTOIMPORTKEY`` converts a raw key to long-term wrapped form. It takes 497 in a pointer to a ``struct blk_crypto_import_key_arg``. The caller must set 498 ``raw_key_ptr`` and ``raw_key_size`` to the pointer and size (in bytes) of the 499 raw key to import. On success, ``BLKCRYPTOIMPORTKEY`` returns 0 and writes 500 the resulting long-term wrapped key blob to the buffer pointed to by 501 ``lt_key_ptr``, which is of maximum size ``lt_key_size``. It also updates 502 ``lt_key_size`` to be the actual size of the key. On failure, it returns -1 503 and sets errno. An errno of ``EOPNOTSUPP`` indicates that the block device 504 does not support hardware-wrapped keys. An errno of ``EOVERFLOW`` indicates 505 that the output buffer did not have enough space for the key blob. 506 507- ``BLKCRYPTOGENERATEKEY`` is like ``BLKCRYPTOIMPORTKEY``, but it has the 508 hardware generate the key instead of importing one. It takes in a pointer to 509 a ``struct blk_crypto_generate_key_arg``. 510 511- ``BLKCRYPTOPREPAREKEY`` converts a key from long-term wrapped form to 512 ephemerally-wrapped form. It takes in a pointer to a ``struct 513 blk_crypto_prepare_key_arg``. The caller must set ``lt_key_ptr`` and 514 ``lt_key_size`` to the pointer and size (in bytes) of the long-term wrapped 515 key blob to convert. On success, ``BLKCRYPTOPREPAREKEY`` returns 0 and writes 516 the resulting ephemerally-wrapped key blob to the buffer pointed to by 517 ``eph_key_ptr``, which is of maximum size ``eph_key_size``. It also updates 518 ``eph_key_size`` to be the actual size of the key. On failure, it returns -1 519 and sets errno. Errno values of ``EOPNOTSUPP`` and ``EOVERFLOW`` mean the 520 same as they do for ``BLKCRYPTOIMPORTKEY``. An errno of ``EBADMSG`` indicates 521 that the long-term wrapped key is invalid. 522 523Userspace needs to use either ``BLKCRYPTOIMPORTKEY`` or ``BLKCRYPTOGENERATEKEY`` 524once to create a key, and then ``BLKCRYPTOPREPAREKEY`` each time the key is 525unlocked and added to the kernel. Note that these ioctls have no relevance for 526raw keys; they are only for hardware-wrapped keys. 527 528Testability 529----------- 530 531Both the hardware KDF and the inline encryption itself are well-defined 532algorithms that don't depend on any secrets other than the unwrapped key. 533Therefore, if the unwrapped key is known to software, these algorithms can be 534reproduced in software in order to verify the ciphertext that is written to disk 535by the inline encryption hardware. 536 537However, the unwrapped key will only be known to software for testing if the 538"import" functionality is used. Proper testing is not possible in the 539"generate" case where the hardware generates the key itself. The correct 540operation of the "generate" mode thus relies on the security and correctness of 541the hardware RNG and its use to generate the key, as well as the testing of the 542"import" mode as that should cover all parts other than the key generation. 543 544For an example of a test that verifies the ciphertext written to disk in the 545"import" mode, see the fscrypt hardware-wrapped key tests in xfstests, or 546`Android's vts_kernel_encryption_test 547<https://android.googlesource.com/platform/test/vts-testcase/kernel/+/refs/heads/main/encryption/>`_. 548