| 1 | |
| 2 |
|
| 3 | .. _inline_encryption:
|
| 4 |
|
| 5 | =================
|
| 6 | Inline Encryption
|
| 7 | =================
|
| 8 |
|
| 9 | Background
|
| 10 | ==========
|
| 11 |
|
| 12 | Inline encryption hardware sits logically between memory and disk, and can
|
| 13 | en/decrypt data as it goes in/out of the disk. For each I/O request, software
|
| 14 | can control exactly how the inline encryption hardware will en/decrypt the data
|
| 15 | in terms of key, algorithm, data unit size (the granularity of en/decryption),
|
| 16 | and data unit number (a value that determines the initialization vector(s)).
|
| 17 |
|
| 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,
|
| 21 | algorithm, and data unit size first be programmed into a keyslot. Each
|
| 22 | low-level I/O request then just contains a keyslot index and data unit number.
|
| 23 |
|
| 24 | Note that inline encryption hardware is very different from traditional crypto
|
| 25 | accelerators, which are supported through the kernel crypto API. Traditional
|
| 26 | crypto accelerators operate on memory regions, whereas inline encryption
|
| 27 | hardware operates on I/O requests. Thus, inline encryption hardware needs to be
|
| 28 | managed by the block layer, not the kernel crypto API.
|
| 29 |
|
| 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
|
| 35 | initialization vector for each sector, and can be tested for correctness.
|
| 36 |
|
| 37 | Objective
|
| 38 | =========
|
| 39 |
|
| 40 | We want to support inline encryption hardware in the kernel. The API for using
|
| 41 | such hardware should also support a fallback to the CPU, so that users only need
|
| 42 | to use a single API and more of the code can be tested without actual hardware.
|
| 43 | We also want inline encryption to work with layered devices like device-mapper
|
| 44 | and loopback (i.e. we want to be able to use the inline encryption hardware of
|
| 45 | the underlying devices if present, or else fall back to the CPU).
|
| 46 |
|
| 47 | Constraints 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 |
|
| 76 | Basic design
|
| 77 | ============
|
| 78 |
|
| 79 | We introduce ``struct blk_crypto_key`` to represent an inline encryption key and
|
| 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.
|
| 84 |
|
| 85 | We introduce ``struct bio_crypt_ctx`` to represent an encryption context. It
|
| 86 | contains a data unit number and a pointer to a blk_crypto_key. We add pointers
|
| 87 | to a bio_crypt_ctx to ``struct bio`` and ``struct request``; this allows users
|
| 88 | of the block layer (e.g. filesystems) to provide an encryption context when
|
| 89 | creating a bio and have it be passed down the stack for processing by the block
|
| 90 | layer and device drivers. Note that the encryption context doesn't explicitly
|
| 91 | say whether to encrypt or decrypt, as that is implicit from the direction of the
|
| 92 | bio; WRITE means encrypt, and READ means decrypt.
|
| 93 |
|
| 94 | We also introduce ``struct blk_crypto_profile`` to contain all generic inline
|
| 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
|
| 97 | advertise their crypto capabilities and provide certain functions (e.g.,
|
| 98 | functions to program and evict keys) to upper layers. Each device driver that
|
| 99 | wants to support inline encryption will construct a blk_crypto_profile, then
|
| 100 | associate it with the disk's request_queue.
|
| 101 |
|
| 102 | The blk_crypto_profile also manages the hardware's keyslots, when applicable.
|
| 103 | This happens in the block layer, so that users of the block layer can just
|
| 104 | specify encryption contexts and don't need to know about keyslots at all, nor do
|
| 105 | device drivers need to care about most details of keyslot management.
|
| 106 |
|
| 107 | Specifically, for each keyslot, the block layer (via the blk_crypto_profile)
|
| 108 | keeps track of which blk_crypto_key that keyslot contains (if any), and how many
|
| 109 | in-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
|
| 111 | that already contains the key if possible. Otherwise it waits for an idle
|
| 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.
|
| 114 | In both cases, the resulting keyslot is stored in the ``crypt_keyslot`` field of
|
| 115 | the request, where it is then accessible to device drivers and is released after
|
| 116 | the request completes.
|
| 117 |
|
| 118 | ``struct request`` also contains a pointer to the original bio_crypt_ctx.
|
| 119 | Requests can be built from multiple bios, and the block layer must take the
|
| 120 | encryption context into account when trying to merge bios and requests. For two
|
| 121 | bios/requests to be merged, they must have compatible encryption contexts: both
|
| 122 | unencrypted, or both encrypted with the same key and contiguous data unit
|
| 123 | numbers. Only the encryption context for the first bio in a request is
|
| 124 | retained, since the remaining bios have been verified to be merge-compatible
|
| 125 | with the first bio.
|
| 126 |
|
| 127 | To make it possible for inline encryption to work with request_queue based
|
| 128 | layered devices, when a request is cloned, its encryption context is cloned as
|
| 129 | well. When the cloned request is submitted, it is then processed as usual; this
|
| 130 | includes getting a keyslot from the clone's target device if needed.
|
| 131 |
|
| 132 | blk-crypto-fallback
|
| 133 | ===================
|
| 134 |
|
| 135 | It is desirable for the inline encryption support of upper layers (e.g.
|
| 136 | filesystems) to be testable without real inline encryption hardware, and
|
| 137 | likewise for the block layer's keyslot management logic. It is also desirable
|
| 138 | to allow upper layers to just always use inline encryption rather than have to
|
| 139 | implement encryption in multiple ways.
|
| 140 |
|
| 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
|
| 143 | into the block layer, so it works on any block device without any special setup.
|
| 144 | Essentially, when a bio with an encryption context is submitted to a
|
| 145 | block_device that doesn't support that encryption context, the block layer will
|
| 146 | handle en/decryption of the bio using blk-crypto-fallback.
|
| 147 |
|
| 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,
|
| 150 | fills a new bio with those bounce pages, encrypts the data into those bounce
|
| 151 | pages, and submits that "bounce" bio. When the bounce bio completes,
|
| 152 | blk-crypto-fallback completes the original bio. If the original bio is too
|
| 153 | large, multiple bounce bios may be required; see the code for details.
|
| 154 |
|
| 155 | For decryption, blk-crypto-fallback "wraps" the bio's completion callback
|
| 156 | (``bi_end_io``) and private data (``bi_private``) with its own, unsets the
|
| 157 | bio's encryption context, then submits the bio. If the read completes
|
| 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
|
| 160 | kernel crypto API. Decryption happens from a workqueue, as it may sleep.
|
| 161 | Afterwards, blk-crypto-fallback completes the bio.
|
| 162 |
|
| 163 | In both cases, the bios that blk-crypto-fallback submits no longer have an
|
| 164 | encryption context. Therefore, lower layers only see standard unencrypted I/O.
|
| 165 |
|
| 166 | blk-crypto-fallback also defines its own blk_crypto_profile and has its own
|
| 167 | "keyslots"; its keyslots contain ``struct crypto_skcipher`` objects. The reason
|
| 168 | for this is twofold. First, it allows the keyslot management logic to be tested
|
| 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
|
| 171 | rather requires that keys be set ahead of time, and setting keys can be
|
| 172 | expensive; moreover, allocating a crypto_skcipher can't happen on the I/O path
|
| 173 | at all due to the locks it takes. Therefore, the concept of keyslots still
|
| 174 | makes sense for blk-crypto-fallback.
|
| 175 |
|
| 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
|
| 180 | of the algorithm being used adhere to spec and function correctly).
|
| 181 |
|
| 182 | blk-crypto-fallback is optional and is controlled by the
|
| 183 | ``CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK`` kernel configuration option.
|
| 184 |
|
| 185 | API presented to users of the block layer
|
| 186 | =========================================
|
| 187 |
|
| 188 | ``blk_crypto_init_key()`` allows users to initialize a blk_crypto_key.
|
| 189 |
|
| 190 | Users must call ``blk_crypto_start_using_key()`` before actually starting to use
|
| 191 | a blk_crypto_key on a block_device. This is needed to initialize
|
| 192 | blk-crypto-fallback if it will be needed. This must not be called from the data
|
| 193 | path, as this may have to allocate resources, which may deadlock in that case.
|
| 194 |
|
| 195 | Next, 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
|
| 197 | it to a bio, given the blk_crypto_key and the data unit number that will be used
|
| 198 | for en/decryption. Users don't need to worry about freeing the bio_crypt_ctx
|
| 199 | later, as that happens automatically when the bio is freed or reset.
|
| 200 |
|
| 201 | To submit a bio that uses inline encryption, users must call
|
| 202 | ``blk_crypto_submit_bio()`` instead of the usual ``submit_bio()``. This will
|
| 203 | submit the bio to the underlying driver if it supports inline crypto, or else
|
| 204 | call the blk-crypto fallback routines before submitting normal bios to the
|
| 205 | underlying drivers.
|
| 206 |
|
| 207 | Finally, when done using inline encryption with a blk_crypto_key on a
|
| 208 | block_device, users must call ``blk_crypto_evict_key()``. This ensures that
|
| 209 | the key is evicted from all keyslots it may be programmed into and unlinked from
|
| 210 | any kernel data structures it may be linked into.
|
| 211 |
|
| 212 | In summary, for users of the block layer, the lifecycle of a blk_crypto_key is
|
| 213 | as follows:
|
| 214 |
|
| 215 | 1. ``blk_crypto_init_key()``
|
| 216 | 2. ``blk_crypto_start_using_key()``
|
| 217 | 3. ``bio_crypt_set_ctx()`` (potentially many times)
|
| 218 | 4. ``blk_crypto_evict_key()`` (after all I/O has completed)
|
| 219 | 5. Zeroize the blk_crypto_key (this has no dedicated function)
|
| 220 |
|
| 221 | If 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
|
| 223 | on each block_device.
|
| 224 |
|
| 225 | API presented to device drivers
|
| 226 | ===============================
|
| 227 |
|
| 228 | A device driver that wants to support inline encryption must set up a
|
| 229 | blk_crypto_profile in the request_queue of its device. To do this, it first
|
| 230 | must call ``blk_crypto_profile_init()`` (or its resource-managed variant
|
| 231 | ``devm_blk_crypto_profile_init()``), providing the number of keyslots.
|
| 232 |
|
| 233 | Next, it must advertise its crypto capabilities by setting fields in the
|
| 234 | blk_crypto_profile, e.g. ``modes_supported`` and ``max_dun_bytes_supported``.
|
| 235 |
|
| 236 | It then must set function pointers in the ``ll_ops`` field of the
|
| 237 | blk_crypto_profile to tell upper layers how to control the inline encryption
|
| 238 | hardware, e.g. how to program and evict keyslots. Most drivers will need to
|
| 239 | implement ``keyslot_program`` and ``keyslot_evict``. For details, see the
|
| 240 | comments for ``struct blk_crypto_ll_ops``.
|
| 241 |
|
| 242 | Once the driver registers a blk_crypto_profile with a request_queue, I/O
|
| 243 | requests the driver receives via that queue may have an encryption context. All
|
| 244 | encryption contexts will be compatible with the crypto capabilities declared in
|
| 245 | the blk_crypto_profile, so drivers don't need to worry about handling
|
| 246 | unsupported requests. Also, if a nonzero number of keyslots was declared in the
|
| 247 | blk_crypto_profile, then all I/O requests that have an encryption context will
|
| 248 | also have a keyslot which was already programmed with the appropriate key.
|
| 249 |
|
| 250 | If the driver implements runtime suspend and its blk_crypto_ll_ops don't work
|
| 251 | while the device is runtime-suspended, then the driver must also set the ``dev``
|
| 252 | field of the blk_crypto_profile to point to the ``struct device`` that will be
|
| 253 | resumed before any of the low-level operations are called.
|
| 254 |
|
| 255 | If there are situations where the inline encryption hardware loses the contents
|
| 256 | of its keyslots, e.g. device resets, the driver must handle reprogramming the
|
| 257 | keyslots. To do this, the driver may call ``blk_crypto_reprogram_all_keys()``.
|
| 258 |
|
| 259 | Finally, 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 |
|
| 263 | Layered Devices
|
| 264 | ===============
|
| 265 |
|
| 266 | Request queue based layered devices like dm-rq that wish to support inline
|
| 267 | encryption need to create their own blk_crypto_profile for their request_queue,
|
| 268 | and expose whatever functionality they choose. When a layered device wants to
|
| 269 | pass a clone of that request to another request_queue, blk-crypto will
|
| 270 | initialize and prepare the clone as necessary.
|
| 271 |
|
| 272 | Interaction between inline encryption and blk integrity
|
| 273 | =======================================================
|
| 274 |
|
| 275 | At the time of this patch, there is no real hardware that supports both these
|
| 276 | features. However, these features do interact with each other, and it's not
|
| 277 | completely trivial to make them both work together properly. In particular,
|
| 278 | when a WRITE bio wants to use inline encryption on a device that supports both
|
| 279 | features, the bio will have an encryption context specified, after which
|
| 280 | its integrity information is calculated (using the plaintext data, since
|
| 281 | the encryption will happen while data is being written), and the data and
|
| 282 | integrity info is sent to the device. Obviously, the integrity info must be
|
| 283 | verified before the data is encrypted. After the data is encrypted, the device
|
| 284 | must not store the integrity info that it received with the plaintext data
|
| 285 | since that might reveal information about the plaintext data. As such, it must
|
| 286 | re-generate the integrity info from the ciphertext data and store that on disk
|
| 287 | instead. Another issue with storing the integrity info of the plaintext data is
|
| 288 | that it changes the on disk format depending on whether hardware inline
|
| 289 | encryption support is present or the kernel crypto API fallback is used (since
|
| 290 | if the fallback is used, the device will receive the integrity info of the
|
| 291 | ciphertext, not that of the plaintext).
|
| 292 |
|
| 293 | Because there isn't any real hardware yet, it seems prudent to assume that
|
| 294 | hardware implementations might not implement both features together correctly,
|
| 295 | and disallow the combination for now. Whenever a device supports integrity, the
|
| 296 | kernel 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).
|
| 298 | When the crypto API fallback is enabled, this means that all bios with an
|
| 299 | encryption context will use the fallback, and IO will complete as usual. When
|
| 300 | the fallback is disabled, a bio with an encryption context will be failed.
|
| 301 |
|
| 302 | .. _hardware_wrapped_keys:
|
| 303 |
|
| 304 | Hardware-wrapped keys
|
| 305 | =====================
|
| 306 |
|
| 307 | Motivation and threat model
|
| 308 | ---------------------------
|
| 309 |
|
| 310 | Linux storage encryption (dm-crypt, fscrypt, eCryptfs, etc.) traditionally
|
| 311 | relies on the raw encryption key(s) being present in kernel memory so that the
|
| 312 | encryption can be performed. This traditionally isn't seen as a problem because
|
| 313 | the key(s) won't be present during an offline attack, which is the main type of
|
| 314 | attack that storage encryption is intended to protect from.
|
| 315 |
|
| 316 | However, there is an increasing desire to also protect users' data from other
|
| 317 | types 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 |
|
| 334 | Hardware-wrapped keys are a feature of inline encryption hardware that is
|
| 335 | designed to protect users' data from the above attacks (to the extent possible),
|
| 336 | without introducing limitations such as a maximum number of keys.
|
| 337 |
|
| 338 | Note that it is impossible to **fully** protect users' data from these attacks.
|
| 339 | Even in the attacks where the attacker "just" gets read access to kernel memory,
|
| 340 | they can still extract any user data that is present in memory, including
|
| 341 | plaintext pagecache pages of encrypted files. The focus here is just on
|
| 342 | protecting the encryption keys, as those instantly give access to **all** user
|
| 343 | data in any following offline attack, rather than just some of it (where which
|
| 344 | data is included in that "some" might not be controlled by the attacker).
|
| 345 |
|
| 346 | Solution overview
|
| 347 | -----------------
|
| 348 |
|
| 349 | Inline encryption hardware typically has "keyslots" into which software can
|
| 350 | program keys for the hardware to use; the contents of keyslots typically can't
|
| 351 | be read back by software. As such, the above security goals could be achieved
|
| 352 | if the kernel simply erased its copy of the key(s) after programming them into
|
| 353 | keyslot(s) and thereafter only referred to them via keyslot number.
|
| 354 |
|
| 355 | However, 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 |
|
| 372 | Thus, it is important for the kernel to still have a way to "remind" the
|
| 373 | hardware about a key, without actually having the raw key itself.
|
| 374 |
|
| 375 | Somewhat less importantly, it is also desirable that the raw keys are never
|
| 376 | visible to software at all, even while being initially unlocked. This would
|
| 377 | ensure that a read-only compromise of system memory will never allow a key to be
|
| 378 | extracted to be used off-system, even if it occurs when a key is being unlocked.
|
| 379 |
|
| 380 | To solve all these problems, some vendors of inline encryption hardware have
|
| 381 | made their hardware support *hardware-wrapped keys*. Hardware-wrapped keys
|
| 382 | are 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
|
| 384 | block 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"
|
| 387 | to add some clarity in cases where there could be other types of wrapped keys,
|
| 388 | such as in file-based encryption. Key wrapping is a commonly used technique.)
|
| 389 |
|
| 390 | The key which wraps (encrypts) hardware-wrapped keys is a hardware-internal key
|
| 391 | that is never exposed to software; it is either a persistent key (a "long-term
|
| 392 | wrapping key") or a per-boot key (an "ephemeral wrapping key"). The long-term
|
| 393 | wrapped form of the key is what is initially unlocked, but it is erased from
|
| 394 | memory as soon as it is converted into an ephemerally-wrapped key. In-use
|
| 395 | hardware-wrapped keys are always ephemerally-wrapped, not long-term wrapped.
|
| 396 |
|
| 397 | As inline encryption hardware can only be used to encrypt/decrypt data on-disk,
|
| 398 | the hardware also includes a level of indirection; it doesn't use the unwrapped
|
| 399 | key directly for inline encryption, but rather derives both an inline encryption
|
| 400 | key and a "software secret" from it. Software can use the "software secret" for
|
| 401 | tasks that can't use the inline encryption hardware, such as filenames
|
| 402 | encryption. The software secret is not protected from memory compromise.
|
| 403 |
|
| 404 | Key hierarchy
|
| 405 | -------------
|
| 406 |
|
| 407 | Here 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 |
|
| 418 | The 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 |
|
| 447 | Example: in the case of fscrypt, the fscrypt master key (the key that protects a
|
| 448 | particular set of encrypted directories) is made hardware-wrapped. The inline
|
| 449 | encryption key is used as the file contents encryption key, while the software
|
| 450 | secret (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 |
|
| 453 | Note that currently this design assumes a single inline encryption key per
|
| 454 | hardware-wrapped key, without any further key derivation. Thus, in the case of
|
| 455 | fscrypt, currently hardware-wrapped keys are only compatible with the "inline
|
| 456 | encryption optimized" settings, which use one file contents encryption key per
|
| 457 | encryption policy rather than one per file. This design could be extended to
|
| 458 | make the hardware derive per-file keys using per-file nonces passed down the
|
| 459 | storage stack, and in fact some hardware already supports this; future work is
|
| 460 | planned to remove this limitation by adding the corresponding kernel support.
|
| 461 |
|
| 462 | Kernel support
|
| 463 | --------------
|
| 464 |
|
| 465 | The inline encryption support of the kernel's block layer ("blk-crypto") has
|
| 466 | been extended to support hardware-wrapped keys as an alternative to raw keys,
|
| 467 | when 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 |
|
| 489 | blk-crypto-fallback doesn't support hardware-wrapped keys. Therefore,
|
| 490 | hardware-wrapped keys can only be used with actual inline encryption hardware.
|
| 491 |
|
| 492 | All the above deals with hardware-wrapped keys in ephemerally-wrapped form only.
|
| 493 | To get such keys in the first place, new block device ioctls have been added to
|
| 494 | provide 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 |
|
| 523 | Userspace needs to use either ``BLKCRYPTOIMPORTKEY`` or ``BLKCRYPTOGENERATEKEY``
|
| 524 | once to create a key, and then ``BLKCRYPTOPREPAREKEY`` each time the key is
|
| 525 | unlocked and added to the kernel. Note that these ioctls have no relevance for
|
| 526 | raw keys; they are only for hardware-wrapped keys.
|
| 527 |
|
| 528 | Testability
|
| 529 | -----------
|
| 530 |
|
| 531 | Both the hardware KDF and the inline encryption itself are well-defined
|
| 532 | algorithms that don't depend on any secrets other than the unwrapped key.
|
| 533 | Therefore, if the unwrapped key is known to software, these algorithms can be
|
| 534 | reproduced in software in order to verify the ciphertext that is written to disk
|
| 535 | by the inline encryption hardware.
|
| 536 |
|
| 537 | However, 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
|
| 540 | operation of the "generate" mode thus relies on the security and correctness of
|
| 541 | the 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 |
|
| 544 | For 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/>`_.
|