Documentation/block/inline-encryption.rst

6 Inline Encryption
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
24 Note that inline encryption hardware is very different from traditional crypto
26 crypto accelerators operate on memory regions, whereas inline encryption
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",
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
40 We want to support inline encryption in the kernel.  To make testing easier, we
42 encryption hardware is absent.  We also want inline encryption to work with
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
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
56 - Different inline encryption hardware has different supported algorithms,
61 - Inline encryption hardware usually (but not always) requires that keys be
73   encryption support of their underlying devices.  However, it doesn't make
79 We introduce ``struct blk_crypto_key`` to represent an inline encryption key and
85 We introduce ``struct bio_crypt_ctx`` to represent an encryption context.  It
88 of the block layer (e.g. filesystems) to provide an encryption context when
90 layer and device drivers.  Note that the encryption context doesn't explicitly
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
99 wants to support inline encryption will construct a blk_crypto_profile, then
104 specify encryption contexts and don't need to know about keyslots at all, nor do
110 ``struct request`` for a bio that has an encryption context, it grabs a keyslot
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
123 numbers.  Only the encryption context for the first bio in a request is
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
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
138 to allow upper layers to just always use inline encryption rather than have to
139 implement encryption in multiple ways.
142 of inline encryption using the kernel crypto API.  blk-crypto-fallback is built
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
148 For encryption, the data cannot be encrypted in-place, as callers usually rely
157 bio's encryption context, then submits the bio.  If the read completes
164 encryption context.  Therefore, lower layers only see standard unencrypted I/O.
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
176 Note that regardless of whether real inline encryption hardware or
179 encryption hardware's implementation and the kernel crypto API's implementation
189 inline encryption with particular crypto settings will work on a particular
203 Next, to attach an encryption context to a bio, users should call
209 Finally, when done using inline encryption with a blk_crypto_key on a
231 A device driver that wants to support inline encryption must set up a
240 blk_crypto_profile to tell upper layers how to control the inline encryption
246 requests the driver receives via that queue may have an encryption context.  All
247 encryption contexts will be compatible with the crypto capabilities declared in
250 blk_crypto_profile, then all I/O requests that have an encryption context will
258 If there are situations where the inline encryption hardware loses the contents
270 encryption need to create their own blk_crypto_profile for their request_queue,
275 Interaction between inline encryption and blk integrity
281 when a WRITE bio wants to use inline encryption on a device that supports both
282 features, the bio will have an encryption context specified, after which
284 the encryption will happen while data is being written), and the data and
292 encryption support is present or the kernel crypto API fallback is used (since
299 kernel will pretend that the device does not support hardware inline encryption
302 encryption context will use the fallback, and IO will complete as usual.  When
303 the fallback is disabled, a bio with an encryption context will be failed.