1 .. SPDX-License-Identifier: GPL-2.0
2
3 .. _inline_encryption:
4
5 =================
6 Inline Encryption
7 =================
8
9 Background
10 ==========
11
12 Inline encryption hardware sits logically betw
13 en/decrypt data as it goes in/out of the disk.
14 can control exactly how the inline encryption
15 in terms of key, algorithm, data unit size (th
16 and data unit number (a value that determines
17
18 Some inline encryption hardware accepts all en
19 keys directly in low-level I/O requests. Howe
20 hardware instead has a fixed number of "keyslo
21 algorithm, and data unit size first be program
22 low-level I/O request then just contains a key
23
24 Note that inline encryption hardware is very d
25 accelerators, which are supported through the
26 crypto accelerators operate on memory regions,
27 hardware operates on I/O requests. Thus, inli
28 managed by the block layer, not the kernel cry
29
30 Inline encryption hardware is also very differ
31 such as those based on the TCG Opal or ATA Sec
32 drives don't provide fine-grained control of e
33 verify the correctness of the resulting cipher
34 provides fine-grained control of encryption, i
35 initialization vector for each sector, and can
36
37 Objective
38 =========
39
40 We want to support inline encryption in the ke
41 also want support for falling back to the kern
42 encryption hardware is absent. We also want i
43 layered devices like device-mapper and loopbac
44 the inline encryption hardware of the underlyi
45 fall back to crypto API en/decryption).
46
47 Constraints and notes
48 =====================
49
50 - We need a way for upper layers (e.g. filesys
51 context to use for en/decrypting a bio, and
52 to be able to use that encryption context wh
53 Encryption contexts also introduce constrain
54 needs to be aware of these constraints.
55
56 - Different inline encryption hardware has dif
57 supported data unit sizes, maximum data unit
58 properties the "crypto capabilities". We ne
59 advertise crypto capabilities to upper layer
60
61 - Inline encryption hardware usually (but not
62 programmed into keyslots before being used.
63 slow and there may not be very many keyslots
64 key for every I/O request, but rather keep t
65 keyslots and reuse an already-programmed key
66
67 - Upper layers typically define a specific end
68 when an encrypted directory is locked or whe
69 At these times, keys are wiped from memory.
70 layers to also evict keys from any keyslots
71
72 - When possible, device-mapper devices must be
73 encryption support of their underlying devic
74 sense for device-mapper devices to have keys
75
76 Basic design
77 ============
78
79 We introduce ``struct blk_crypto_key`` to repr
80 how it will be used. This includes the actual
81 key; the algorithm and data unit size the key
82 of bytes needed to represent the maximum data
83 with.
84
85 We introduce ``struct bio_crypt_ctx`` to repre
86 contains a data unit number and a pointer to a
87 to a bio_crypt_ctx to ``struct bio`` and ``str
88 of the block layer (e.g. filesystems) to provi
89 creating a bio and have it be passed down the
90 layer and device drivers. Note that the encry
91 say whether to encrypt or decrypt, as that is
92 bio; WRITE means encrypt, and READ means decry
93
94 We also introduce ``struct blk_crypto_profile`
95 encryption-related state for a particular inli
96 blk_crypto_profile serves as the way that driv
97 advertise their crypto capabilities and provid
98 functions to program and evict keys) to upper
99 wants to support inline encryption will constr
100 associate it with the disk's request_queue.
101
102 The blk_crypto_profile also manages the hardwa
103 This happens in the block layer, so that users
104 specify encryption contexts and don't need to
105 device drivers need to care about most details
106
107 Specifically, for each keyslot, the block laye
108 keeps track of which blk_crypto_key that keysl
109 in-flight I/O requests are using it. When the
110 ``struct request`` for a bio that has an encry
111 that already contains the key if possible. Ot
112 keyslot (a keyslot that isn't in-use by any I/
113 least-recently-used idle keyslot using the fun
114 In both cases, the resulting keyslot is stored
115 the request, where it is then accessible to de
116 the request completes.
117
118 ``struct request`` also contains a pointer to
119 Requests can be built from multiple bios, and
120 encryption context into account when trying to
121 bios/requests to be merged, they must have com
122 unencrypted, or both encrypted with the same k
123 numbers. Only the encryption context for the
124 retained, since the remaining bios have been v
125 with the first bio.
126
127 To make it possible for inline encryption to w
128 layered devices, when a request is cloned, its
129 well. When the cloned request is submitted, i
130 includes getting a keyslot from the clone's ta
131
132 blk-crypto-fallback
133 ===================
134
135 It is desirable for the inline encryption supp
136 filesystems) to be testable without real inlin
137 likewise for the block layer's keyslot managem
138 to allow upper layers to just always use inlin
139 implement encryption in multiple ways.
140
141 Therefore, we also introduce *blk-crypto-fallb
142 of inline encryption using the kernel crypto A
143 into the block layer, so it works on any block
144 Essentially, when a bio with an encryption con
145 block_device that doesn't support that encrypt
146 handle en/decryption of the bio using blk-cryp
147
148 For encryption, the data cannot be encrypted i
149 on it being unmodified. Instead, blk-crypto-f
150 fills a new bio with those bounce pages, encry
151 pages, and submits that "bounce" bio. When th
152 blk-crypto-fallback completes the original bio
153 large, multiple bounce bios may be required; s
154
155 For decryption, blk-crypto-fallback "wraps" th
156 (``bi_complete``) and private data (``bi_priva
157 bio's encryption context, then submits the bio
158 successfully, blk-crypto-fallback restores the
159 callback and private data, then decrypts the b
160 kernel crypto API. Decryption happens from a
161 Afterwards, blk-crypto-fallback completes the
162
163 In both cases, the bios that blk-crypto-fallba
164 encryption context. Therefore, lower layers o
165
166 blk-crypto-fallback also defines its own blk_c
167 "keyslots"; its keyslots contain ``struct cryp
168 for this is twofold. First, it allows the key
169 without actual inline encryption hardware. Se
170 encryption hardware, the crypto API doesn't ac
171 rather requires that keys be set ahead of time
172 expensive; moreover, allocating a crypto_skcip
173 at all due to the locks it takes. Therefore,
174 makes sense for blk-crypto-fallback.
175
176 Note that regardless of whether real inline en
177 blk-crypto-fallback is used, the ciphertext wr
178 on-disk format of data) will be the same (assu
179 encryption hardware's implementation and the k
180 of the algorithm being used adhere to spec and
181
182 blk-crypto-fallback is optional and is control
183 ``CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK`` kern
184
185 API presented to users of the block layer
186 =========================================
187
188 ``blk_crypto_config_supported()`` allows users
189 inline encryption with particular crypto setti
190 block_device -- either via hardware or via blk
191 takes in a ``struct blk_crypto_config`` which
192 the actual bytes of the key and instead just c
193 size, etc. This function can be useful if blk
194
195 ``blk_crypto_init_key()`` allows users to init
196
197 Users must call ``blk_crypto_start_using_key()
198 a blk_crypto_key on a block_device (even if ``
199 was called earlier). This is needed to initia
200 will be needed. This must not be called from
201 allocate resources, which may deadlock in that
202
203 Next, to attach an encryption context to a bio
204 ``bio_crypt_set_ctx()``. This function alloca
205 it to a bio, given the blk_crypto_key and the
206 for en/decryption. Users don't need to worry
207 later, as that happens automatically when the
208
209 Finally, when done using inline encryption wit
210 block_device, users must call ``blk_crypto_evi
211 the key is evicted from all keyslots it may be
212 any kernel data structures it may be linked in
213
214 In summary, for users of the block layer, the
215 as follows:
216
217 1. ``blk_crypto_config_supported()`` (optional
218 2. ``blk_crypto_init_key()``
219 3. ``blk_crypto_start_using_key()``
220 4. ``bio_crypt_set_ctx()`` (potentially many t
221 5. ``blk_crypto_evict_key()`` (after all I/O h
222 6. Zeroize the blk_crypto_key (this has no ded
223
224 If a blk_crypto_key is being used on multiple
225 ``blk_crypto_config_supported()`` (if used), `
226 and ``blk_crypto_evict_key()`` must be called
227
228 API presented to device drivers
229 ===============================
230
231 A device driver that wants to support inline e
232 blk_crypto_profile in the request_queue of its
233 must call ``blk_crypto_profile_init()`` (or it
234 ``devm_blk_crypto_profile_init()``), providing
235
236 Next, it must advertise its crypto capabilitie
237 blk_crypto_profile, e.g. ``modes_supported`` a
238
239 It then must set function pointers in the ``ll
240 blk_crypto_profile to tell upper layers how to
241 hardware, e.g. how to program and evict keyslo
242 implement ``keyslot_program`` and ``keyslot_ev
243 comments for ``struct blk_crypto_ll_ops``.
244
245 Once the driver registers a blk_crypto_profile
246 requests the driver receives via that queue ma
247 encryption contexts will be compatible with th
248 the blk_crypto_profile, so drivers don't need
249 unsupported requests. Also, if a nonzero numb
250 blk_crypto_profile, then all I/O requests that
251 also have a keyslot which was already programm
252
253 If the driver implements runtime suspend and i
254 while the device is runtime-suspended, then th
255 field of the blk_crypto_profile to point to th
256 resumed before any of the low-level operations
257
258 If there are situations where the inline encry
259 of its keyslots, e.g. device resets, the drive
260 keyslots. To do this, the driver may call ``b
261
262 Finally, if the driver used ``blk_crypto_profi
263 ``devm_blk_crypto_profile_init()``, then it is
264 ``blk_crypto_profile_destroy()`` when the cryp
265
266 Layered Devices
267 ===============
268
269 Request queue based layered devices like dm-rq
270 encryption need to create their own blk_crypto
271 and expose whatever functionality they choose.
272 pass a clone of that request to another reques
273 initialize and prepare the clone as necessary.
274
275 Interaction between inline encryption and blk
276 ==============================================
277
278 At the time of this patch, there is no real ha
279 features. However, these features do interact
280 completely trivial to make them both work toge
281 when a WRITE bio wants to use inline encryptio
282 features, the bio will have an encryption cont
283 its integrity information is calculated (using
284 the encryption will happen while data is being
285 integrity info is sent to the device. Obviousl
286 verified before the data is encrypted. After t
287 must not store the integrity info that it rece
288 since that might reveal information about the
289 re-generate the integrity info from the cipher
290 instead. Another issue with storing the integr
291 that it changes the on disk format depending o
292 encryption support is present or the kernel cr
293 if the fallback is used, the device will recei
294 ciphertext, not that of the plaintext).
295
296 Because there isn't any real hardware yet, it
297 hardware implementations might not implement b
298 and disallow the combination for now. Whenever
299 kernel will pretend that the device does not s
300 (by setting the blk_crypto_profile in the requ
301 When the crypto API fallback is enabled, this
302 encryption context will use the fallback, and
303 the fallback is disabled, a bio with an encryp
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.