| inline-encryption.rst (03ab8e6297acd1bc0eedaa050e2a1635c576fd11) | inline-encryption.rst (fce3caea0f241f5d34855c82c399d5e0e2d91f07) |
|---|---|
| 1.. SPDX-License-Identifier: GPL-2.0 2 3.. _inline_encryption: 4 5================= 6Inline Encryption 7================= 8 --- 128 unchanged lines hidden (view full) --- 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 | 1.. SPDX-License-Identifier: GPL-2.0 2 3.. _inline_encryption: 4 5================= 6Inline Encryption 7================= 8 --- 128 unchanged lines hidden (view full) --- 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 |
| 145request_queue that doesn't support that encryption context, the block layer will | 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. --- 28 unchanged lines hidden (view full) --- 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_config_supported()`` allows users to check ahead of time whether 189inline encryption with particular crypto settings will work on a particular | 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. --- 28 unchanged lines hidden (view full) --- 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_config_supported()`` allows users to check ahead of time whether 189inline encryption with particular crypto settings will work on a particular |
| 190request_queue -- either via hardware or via blk-crypto-fallback. This function | 190block_device -- either via hardware or via blk-crypto-fallback. This function |
| 191takes in a ``struct blk_crypto_config`` which is like blk_crypto_key, but omits 192the actual bytes of the key and instead just contains the algorithm, data unit 193size, etc. This function can be useful if blk-crypto-fallback is disabled. 194 195``blk_crypto_init_key()`` allows users to initialize a blk_crypto_key. 196 197Users must call ``blk_crypto_start_using_key()`` before actually starting to use | 191takes in a ``struct blk_crypto_config`` which is like blk_crypto_key, but omits 192the actual bytes of the key and instead just contains the algorithm, data unit 193size, etc. This function can be useful if blk-crypto-fallback is disabled. 194 195``blk_crypto_init_key()`` allows users to initialize a blk_crypto_key. 196 197Users must call ``blk_crypto_start_using_key()`` before actually starting to use |
| 198a blk_crypto_key on a request_queue (even if ``blk_crypto_config_supported()`` | 198a blk_crypto_key on a block_device (even if ``blk_crypto_config_supported()`` |
| 199was called earlier). This is needed to initialize blk-crypto-fallback if it 200will be needed. This must not be called from the data path, as this may have to 201allocate resources, which may deadlock in that case. 202 203Next, to attach an encryption context to a bio, users should call 204``bio_crypt_set_ctx()``. This function allocates a bio_crypt_ctx and attaches 205it to a bio, given the blk_crypto_key and the data unit number that will be used 206for en/decryption. Users don't need to worry about freeing the bio_crypt_ctx 207later, as that happens automatically when the bio is freed or reset. 208 209Finally, when done using inline encryption with a blk_crypto_key on a | 199was called earlier). This is needed to initialize blk-crypto-fallback if it 200will be needed. This must not be called from the data path, as this may have to 201allocate resources, which may deadlock in that case. 202 203Next, to attach an encryption context to a bio, users should call 204``bio_crypt_set_ctx()``. This function allocates a bio_crypt_ctx and attaches 205it to a bio, given the blk_crypto_key and the data unit number that will be used 206for en/decryption. Users don't need to worry about freeing the bio_crypt_ctx 207later, as that happens automatically when the bio is freed or reset. 208 209Finally, when done using inline encryption with a blk_crypto_key on a |
| 210request_queue, users must call ``blk_crypto_evict_key()``. This ensures that | 210block_device, users must call ``blk_crypto_evict_key()``. This ensures that |
| 211the key is evicted from all keyslots it may be programmed into and unlinked from 212any kernel data structures it may be linked into. 213 214In summary, for users of the block layer, the lifecycle of a blk_crypto_key is 215as follows: 216 2171. ``blk_crypto_config_supported()`` (optional) 2182. ``blk_crypto_init_key()`` 2193. ``blk_crypto_start_using_key()`` 2204. ``bio_crypt_set_ctx()`` (potentially many times) 2215. ``blk_crypto_evict_key()`` (after all I/O has completed) 2226. Zeroize the blk_crypto_key (this has no dedicated function) 223 | 211the key is evicted from all keyslots it may be programmed into and unlinked from 212any kernel data structures it may be linked into. 213 214In summary, for users of the block layer, the lifecycle of a blk_crypto_key is 215as follows: 216 2171. ``blk_crypto_config_supported()`` (optional) 2182. ``blk_crypto_init_key()`` 2193. ``blk_crypto_start_using_key()`` 2204. ``bio_crypt_set_ctx()`` (potentially many times) 2215. ``blk_crypto_evict_key()`` (after all I/O has completed) 2226. Zeroize the blk_crypto_key (this has no dedicated function) 223 |
| 224If a blk_crypto_key is being used on multiple request_queues, then | 224If a blk_crypto_key is being used on multiple block_devices, then |
| 225``blk_crypto_config_supported()`` (if used), ``blk_crypto_start_using_key()``, | 225``blk_crypto_config_supported()`` (if used), ``blk_crypto_start_using_key()``, |
| 226and ``blk_crypto_evict_key()`` must be called on each request_queue. | 226and ``blk_crypto_evict_key()`` must be called on each block_device. |
| 227 228API presented to device drivers 229=============================== 230 231A device driver that wants to support inline encryption must set up a 232blk_crypto_profile in the request_queue of its device. To do this, it first 233must call ``blk_crypto_profile_init()`` (or its resource-managed variant 234``devm_blk_crypto_profile_init()``), providing the number of keyslots. --- 70 unchanged lines hidden --- | 227 228API presented to device drivers 229=============================== 230 231A device driver that wants to support inline encryption must set up a 232blk_crypto_profile in the request_queue of its device. To do this, it first 233must call ``blk_crypto_profile_init()`` (or its resource-managed variant 234``devm_blk_crypto_profile_init()``), providing the number of keyslots. --- 70 unchanged lines hidden --- |