~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/block/inline-encryption.rst

Version: ~ [ linux-6.11.5 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.58 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.114 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.169 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.228 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.284 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.322 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.9 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/block/inline-encryption.rst (Version linux-6.11.5) and /Documentation/block/inline-encryption.rst (Version linux-5.14.21)


  1 .. SPDX-License-Identifier: GPL-2.0                 1 .. SPDX-License-Identifier: GPL-2.0
  2                                                     2 
  3 .. _inline_encryption:                         << 
  4                                                << 
  5 =================                                   3 =================
  6 Inline Encryption                                   4 Inline Encryption
  7 =================                                   5 =================
  8                                                     6 
  9 Background                                          7 Background
 10 ==========                                          8 ==========
 11                                                     9 
 12 Inline encryption hardware sits logically betw !!  10 Inline encryption hardware sits logically between memory and the disk, and can
 13 en/decrypt data as it goes in/out of the disk. !!  11 en/decrypt data as it goes in/out of the disk. Inline encryption hardware has a
 14 can control exactly how the inline encryption  !!  12 fixed number of "keyslots" - slots into which encryption contexts (i.e. the
 15 in terms of key, algorithm, data unit size (th !!  13 encryption key, encryption algorithm, data unit size) can be programmed by the
 16 and data unit number (a value that determines  !!  14 kernel at any time. Each request sent to the disk can be tagged with the index
 17                                                !!  15 of a keyslot (and also a data unit number to act as an encryption tweak), and
 18 Some inline encryption hardware accepts all en !!  16 the inline encryption hardware will en/decrypt the data in the request with the
 19 keys directly in low-level I/O requests.  Howe !!  17 encryption context programmed into that keyslot. This is very different from
 20 hardware instead has a fixed number of "keyslo !!  18 full disk encryption solutions like self encrypting drives/TCG OPAL/ATA
 21 algorithm, and data unit size first be program !!  19 Security standards, since with inline encryption, any block on disk could be
 22 low-level I/O request then just contains a key !!  20 encrypted with any encryption context the kernel chooses.
 23                                                !!  21 
 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                                                    22 
 37 Objective                                          23 Objective
 38 =========                                          24 =========
 39                                                    25 
 40 We want to support inline encryption in the ke !!  26 We want to support inline encryption (IE) in the kernel.
 41 also want support for falling back to the kern !!  27 To allow for testing, we also want a crypto API fallback when actual
 42 encryption hardware is absent.  We also want i !!  28 IE hardware is absent. We also want IE to work with layered devices
 43 layered devices like device-mapper and loopbac !!  29 like dm and loopback (i.e. we want to be able to use the IE hardware
 44 the inline encryption hardware of the underlyi !!  30 of the underlying devices if present, or else fall back to crypto API
 45 fall back to crypto API en/decryption).        !!  31 en/decryption).
                                                   >>  32 
 46                                                    33 
 47 Constraints and notes                              34 Constraints and notes
 48 =====================                              35 =====================
 49                                                    36 
 50 - We need a way for upper layers (e.g. filesys !!  37 - IE hardware has a limited number of "keyslots" that can be programmed
 51   context to use for en/decrypting a bio, and  !!  38   with an encryption context (key, algorithm, data unit size, etc.) at any time.
 52   to be able to use that encryption context wh !!  39   One can specify a keyslot in a data request made to the device, and the
 53   Encryption contexts also introduce constrain !!  40   device will en/decrypt the data using the encryption context programmed into
 54   needs to be aware of these constraints.      !!  41   that specified keyslot. When possible, we want to make multiple requests with
 55                                                !!  42   the same encryption context share the same keyslot.
 56 - Different inline encryption hardware has dif !!  43 
 57   supported data unit sizes, maximum data unit !!  44 - We need a way for upper layers like filesystems to specify an encryption
 58   properties the "crypto capabilities".  We ne !!  45   context to use for en/decrypting a struct bio, and a device driver (like UFS)
 59   advertise crypto capabilities to upper layer !!  46   needs to be able to use that encryption context when it processes the bio.
 60                                                !!  47 
 61 - Inline encryption hardware usually (but not  !!  48 - We need a way for device drivers to expose their inline encryption
 62   programmed into keyslots before being used.  !!  49   capabilities in a unified way to the upper layers.
 63   slow and there may not be very many keyslots !!  50 
 64   key for every I/O request, but rather keep t !!  51 
 65   keyslots and reuse an already-programmed key !!  52 Design
 66                                                !!  53 ======
 67 - Upper layers typically define a specific end !!  54 
 68   when an encrypted directory is locked or whe !!  55 We add a struct bio_crypt_ctx to struct bio that can
 69   At these times, keys are wiped from memory.  !!  56 represent an encryption context, because we need to be able to pass this
 70   layers to also evict keys from any keyslots  !!  57 encryption context from the upper layers (like the fs layer) to the
 71                                                !!  58 device driver to act upon.
 72 - When possible, device-mapper devices must be !!  59 
 73   encryption support of their underlying devic !!  60 While IE hardware works on the notion of keyslots, the FS layer has no
 74   sense for device-mapper devices to have keys !!  61 knowledge of keyslots - it simply wants to specify an encryption context to
 75                                                !!  62 use while en/decrypting a bio.
 76 Basic design                                   !!  63 
 77 ============                                   !!  64 We introduce a keyslot manager (KSM) that handles the translation from
 78                                                !!  65 encryption contexts specified by the FS to keyslots on the IE hardware.
 79 We introduce ``struct blk_crypto_key`` to repr !!  66 This KSM also serves as the way IE hardware can expose its capabilities to
 80 how it will be used.  This includes the actual !!  67 upper layers. The generic mode of operation is: each device driver that wants
 81 key; the algorithm and data unit size the key  !!  68 to support IE will construct a KSM and set it up in its struct request_queue.
 82 of bytes needed to represent the maximum data  !!  69 Upper layers that want to use IE on this device can then use this KSM in
 83 with.                                          !!  70 the device's struct request_queue to translate an encryption context into
 84                                                !!  71 a keyslot. The presence of the KSM in the request queue shall be used to mean
 85 We introduce ``struct bio_crypt_ctx`` to repre !!  72 that the device supports IE.
 86 contains a data unit number and a pointer to a !!  73 
 87 to a bio_crypt_ctx to ``struct bio`` and ``str !!  74 The KSM uses refcounts to track which keyslots are idle (either they have no
 88 of the block layer (e.g. filesystems) to provi !!  75 encryption context programmed, or there are no in-flight struct bios
 89 creating a bio and have it be passed down the  !!  76 referencing that keyslot). When a new encryption context needs a keyslot, it
 90 layer and device drivers.  Note that the encry !!  77 tries to find a keyslot that has already been programmed with the same
 91 say whether to encrypt or decrypt, as that is  !!  78 encryption context, and if there is no such keyslot, it evicts the least
 92 bio; WRITE means encrypt, and READ means decry !!  79 recently used idle keyslot and programs the new encryption context into that
 93                                                !!  80 one. If no idle keyslots are available, then the caller will sleep until there
 94 We also introduce ``struct blk_crypto_profile` !!  81 is at least one.
 95 encryption-related state for a particular inli !!  82 
 96 blk_crypto_profile serves as the way that driv !!  83 
 97 advertise their crypto capabilities and provid !!  84 blk-mq changes, other block layer changes and blk-crypto-fallback
 98 functions to program and evict keys) to upper  !!  85 =================================================================
 99 wants to support inline encryption will constr !!  86 
100 associate it with the disk's request_queue.    !!  87 We add a pointer to a ``bi_crypt_context`` and ``keyslot`` to
101                                                !!  88 struct request. These will be referred to as the ``crypto fields``
102 The blk_crypto_profile also manages the hardwa !!  89 for the request. This ``keyslot`` is the keyslot into which the
103 This happens in the block layer, so that users !!  90 ``bi_crypt_context`` has been programmed in the KSM of the ``request_queue``
104 specify encryption contexts and don't need to  !!  91 that this request is being sent to.
105 device drivers need to care about most details !!  92 
106                                                !!  93 We introduce ``block/blk-crypto-fallback.c``, which allows upper layers to remain
107 Specifically, for each keyslot, the block laye !!  94 blissfully unaware of whether or not real inline encryption hardware is present
108 keeps track of which blk_crypto_key that keysl !!  95 underneath. When a bio is submitted with a target ``request_queue`` that doesn't
109 in-flight I/O requests are using it.  When the !!  96 support the encryption context specified with the bio, the block layer will
110 ``struct request`` for a bio that has an encry !!  97 en/decrypt the bio with the blk-crypto-fallback.
111 that already contains the key if possible.  Ot !!  98 
112 keyslot (a keyslot that isn't in-use by any I/ !!  99 If the bio is a ``WRITE`` bio, a bounce bio is allocated, and the data in the bio
113 least-recently-used idle keyslot using the fun !! 100 is encrypted stored in the bounce bio - blk-mq will then proceed to process the
114 In both cases, the resulting keyslot is stored !! 101 bounce bio as if it were not encrypted at all (except when blk-integrity is
115 the request, where it is then accessible to de !! 102 concerned). ``blk-crypto-fallback`` sets the bounce bio's ``bi_end_io`` to an
116 the request completes.                         !! 103 internal function that cleans up the bounce bio and ends the original bio.
117                                                !! 104 
118 ``struct request`` also contains a pointer to  !! 105 If the bio is a ``READ`` bio, the bio's ``bi_end_io`` (and also ``bi_private``)
119 Requests can be built from multiple bios, and  !! 106 is saved and overwritten by ``blk-crypto-fallback`` to
120 encryption context into account when trying to !! 107 ``bio_crypto_fallback_decrypt_bio``.  The bio's ``bi_crypt_context`` is also
121 bios/requests to be merged, they must have com !! 108 overwritten with ``NULL``, so that to the rest of the stack, the bio looks
122 unencrypted, or both encrypted with the same k !! 109 as if it was a regular bio that never had an encryption context specified.
123 numbers.  Only the encryption context for the  !! 110 ``bio_crypto_fallback_decrypt_bio`` will decrypt the bio, restore the original
124 retained, since the remaining bios have been v !! 111 ``bi_end_io`` (and also ``bi_private``) and end the bio again.
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                                                   112 
176 Note that regardless of whether real inline en !! 113 Regardless of whether real inline encryption hardware is used or the
177 blk-crypto-fallback is used, the ciphertext wr    114 blk-crypto-fallback is used, the ciphertext written to disk (and hence the
178 on-disk format of data) will be the same (assu !! 115 on-disk format of data) will be the same (assuming the hardware's implementation
179 encryption hardware's implementation and the k !! 116 of the algorithm being used adheres to spec and functions correctly).
180 of the algorithm being used adhere to spec and !! 117 
                                                   >> 118 If a ``request queue``'s inline encryption hardware claimed to support the
                                                   >> 119 encryption context specified with a bio, then it will not be handled by the
                                                   >> 120 ``blk-crypto-fallback``. We will eventually reach a point in blk-mq when a
                                                   >> 121 struct request needs to be allocated for that bio. At that point,
                                                   >> 122 blk-mq tries to program the encryption context into the ``request_queue``'s
                                                   >> 123 keyslot_manager, and obtain a keyslot, which it stores in its newly added
                                                   >> 124 ``keyslot`` field. This keyslot is released when the request is completed.
                                                   >> 125 
                                                   >> 126 When the first bio is added to a request, ``blk_crypto_rq_bio_prep`` is called,
                                                   >> 127 which sets the request's ``crypt_ctx`` to a copy of the bio's
                                                   >> 128 ``bi_crypt_context``. bio_crypt_do_front_merge is called whenever a subsequent
                                                   >> 129 bio is merged to the front of the request, which updates the ``crypt_ctx`` of
                                                   >> 130 the request so that it matches the newly merged bio's ``bi_crypt_context``. In particular, the request keeps a copy of the ``bi_crypt_context`` of the first
                                                   >> 131 bio in its bio-list (blk-mq needs to be careful to maintain this invariant
                                                   >> 132 during bio and request merges).
                                                   >> 133 
                                                   >> 134 To make it possible for inline encryption to work with request queue based
                                                   >> 135 layered devices, when a request is cloned, its ``crypto fields`` are cloned as
                                                   >> 136 well. When the cloned request is submitted, blk-mq programs the
                                                   >> 137 ``bi_crypt_context`` of the request into the clone's request_queue's keyslot
                                                   >> 138 manager, and stores the returned keyslot in the clone's ``keyslot``.
181                                                   139 
182 blk-crypto-fallback is optional and is control << 
183 ``CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK`` kern << 
184                                                   140 
185 API presented to users of the block layer         141 API presented to users of the block layer
186 =========================================         142 =========================================
187                                                   143 
188 ``blk_crypto_config_supported()`` allows users !! 144 ``struct blk_crypto_key`` represents a crypto key (the raw key, size of the
189 inline encryption with particular crypto setti !! 145 key, the crypto algorithm to use, the data unit size to use, and the number of
190 block_device -- either via hardware or via blk !! 146 bytes required to represent data unit numbers that will be specified with the
191 takes in a ``struct blk_crypto_config`` which  !! 147 ``bi_crypt_context``).
192 the actual bytes of the key and instead just c !! 148 
193 size, etc.  This function can be useful if blk !! 149 ``blk_crypto_init_key`` allows upper layers to initialize such a
194                                                !! 150 ``blk_crypto_key``.
195 ``blk_crypto_init_key()`` allows users to init !! 151 
196                                                !! 152 ``bio_crypt_set_ctx`` should be called on any bio that a user of
197 Users must call ``blk_crypto_start_using_key() !! 153 the block layer wants en/decrypted via inline encryption (or the
198 a blk_crypto_key on a block_device (even if `` !! 154 blk-crypto-fallback, if hardware support isn't available for the desired
199 was called earlier).  This is needed to initia !! 155 crypto configuration). This function takes the ``blk_crypto_key`` and the
200 will be needed.  This must not be called from  !! 156 data unit number (DUN) to use when en/decrypting the bio.
201 allocate resources, which may deadlock in that !! 157 
202                                                !! 158 ``blk_crypto_config_supported`` allows upper layers to query whether or not the
203 Next, to attach an encryption context to a bio !! 159 an encryption context passed to request queue can be handled by blk-crypto
204 ``bio_crypt_set_ctx()``.  This function alloca !! 160 (either by real inline encryption hardware, or by the blk-crypto-fallback).
205 it to a bio, given the blk_crypto_key and the  !! 161 This is useful e.g. when blk-crypto-fallback is disabled, and the upper layer
206 for en/decryption.  Users don't need to worry  !! 162 wants to use an algorithm that may not supported by hardware - this function
207 later, as that happens automatically when the  !! 163 lets the upper layer know ahead of time that the algorithm isn't supported,
208                                                !! 164 and the upper layer can fallback to something else if appropriate.
209 Finally, when done using inline encryption wit !! 165 
210 block_device, users must call ``blk_crypto_evi !! 166 ``blk_crypto_start_using_key`` - Upper layers must call this function on
211 the key is evicted from all keyslots it may be !! 167 ``blk_crypto_key`` and a ``request_queue`` before using the key with any bio
212 any kernel data structures it may be linked in !! 168 headed for that ``request_queue``. This function ensures that either the
213                                                !! 169 hardware supports the key's crypto settings, or the crypto API fallback has
214 In summary, for users of the block layer, the  !! 170 transforms for the needed mode allocated and ready to go. Note that this
215 as follows:                                    !! 171 function may allocate an ``skcipher``, and must not be called from the data
216                                                !! 172 path, since allocating ``skciphers`` from the data path can deadlock.
217 1. ``blk_crypto_config_supported()`` (optional !! 173 
218 2. ``blk_crypto_init_key()``                   !! 174 ``blk_crypto_evict_key`` *must* be called by upper layers before a
219 3. ``blk_crypto_start_using_key()``            !! 175 ``blk_crypto_key`` is freed. Further, it *must* only be called only once
220 4. ``bio_crypt_set_ctx()`` (potentially many t !! 176 there are no more in-flight requests that use that ``blk_crypto_key``.
221 5. ``blk_crypto_evict_key()`` (after all I/O h !! 177 ``blk_crypto_evict_key`` will ensure that a key is removed from any keyslots in
222 6. Zeroize the blk_crypto_key (this has no ded !! 178 inline encryption hardware that the key might have been programmed into (or the blk-crypto-fallback).
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                                                   179 
228 API presented to device drivers                   180 API presented to device drivers
229 ===============================                   181 ===============================
230                                                   182 
231 A device driver that wants to support inline e !! 183 A :c:type:``struct blk_keyslot_manager`` should be set up by device drivers in
232 blk_crypto_profile in the request_queue of its !! 184 the ``request_queue`` of the device. The device driver needs to call
233 must call ``blk_crypto_profile_init()`` (or it !! 185 ``blk_ksm_init`` (or its resource-managed variant ``devm_blk_ksm_init``) on the
234 ``devm_blk_crypto_profile_init()``), providing !! 186 ``blk_keyslot_manager``, while specifying the number of keyslots supported by
235                                                !! 187 the hardware.
236 Next, it must advertise its crypto capabilitie !! 188 
237 blk_crypto_profile, e.g. ``modes_supported`` a !! 189 The device driver also needs to tell the KSM how to actually manipulate the
238                                                !! 190 IE hardware in the device to do things like programming the crypto key into
239 It then must set function pointers in the ``ll !! 191 the IE hardware into a particular keyslot. All this is achieved through the
240 blk_crypto_profile to tell upper layers how to !! 192 struct blk_ksm_ll_ops field in the KSM that the device driver
241 hardware, e.g. how to program and evict keyslo !! 193 must fill up after initing the ``blk_keyslot_manager``.
242 implement ``keyslot_program`` and ``keyslot_ev !! 194 
243 comments for ``struct blk_crypto_ll_ops``.     !! 195 The KSM also handles runtime power management for the device when applicable
244                                                !! 196 (e.g. when it wants to program a crypto key into the IE hardware, the device
245 Once the driver registers a blk_crypto_profile !! 197 must be runtime powered on) - so the device driver must also set the ``dev``
246 requests the driver receives via that queue ma !! 198 field in the ksm to point to the `struct device` for the KSM to use for runtime
247 encryption contexts will be compatible with th !! 199 power management.
248 the blk_crypto_profile, so drivers don't need  !! 200 
249 unsupported requests.  Also, if a nonzero numb !! 201 ``blk_ksm_reprogram_all_keys`` can be called by device drivers if the device
250 blk_crypto_profile, then all I/O requests that !! 202 needs each and every of its keyslots to be reprogrammed with the key it
251 also have a keyslot which was already programm !! 203 "should have" at the point in time when the function is called. This is useful
252                                                !! 204 e.g. if a device loses all its keys on runtime power down/up.
253 If the driver implements runtime suspend and i !! 205 
254 while the device is runtime-suspended, then th !! 206 If the driver used ``blk_ksm_init`` instead of ``devm_blk_ksm_init``, then
255 field of the blk_crypto_profile to point to th !! 207 ``blk_ksm_destroy`` should be called to free up all resources used by a
256 resumed before any of the low-level operations !! 208 ``blk_keyslot_manager`` once it is no longer needed.
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                                                   209 
266 Layered Devices                                   210 Layered Devices
267 ===============                                   211 ===============
268                                                   212 
269 Request queue based layered devices like dm-rq !! 213 Request queue based layered devices like dm-rq that wish to support IE need to
270 encryption need to create their own blk_crypto !! 214 create their own keyslot manager for their request queue, and expose whatever
271 and expose whatever functionality they choose. !! 215 functionality they choose. When a layered device wants to pass a clone of that
272 pass a clone of that request to another reques !! 216 request to another ``request_queue``, blk-crypto will initialize and prepare the
273 initialize and prepare the clone as necessary. !! 217 clone as necessary - see ``blk_crypto_insert_cloned_request`` in
                                                   >> 218 ``blk-crypto.c``.
                                                   >> 219 
                                                   >> 220 
                                                   >> 221 Future Optimizations for layered devices
                                                   >> 222 ========================================
                                                   >> 223 
                                                   >> 224 Creating a keyslot manager for a layered device uses up memory for each
                                                   >> 225 keyslot, and in general, a layered device merely passes the request on to a
                                                   >> 226 "child" device, so the keyslots in the layered device itself are completely
                                                   >> 227 unused, and don't need any refcounting or keyslot programming. We can instead
                                                   >> 228 define a new type of KSM; the "passthrough KSM", that layered devices can use
                                                   >> 229 to advertise an unlimited number of keyslots, and support for any encryption
                                                   >> 230 algorithms they choose, while not actually using any memory for each keyslot.
                                                   >> 231 Another use case for the "passthrough KSM" is for IE devices that do not have a
                                                   >> 232 limited number of keyslots.
                                                   >> 233 
274                                                   234 
275 Interaction between inline encryption and blk     235 Interaction between inline encryption and blk integrity
276 ==============================================    236 =======================================================
277                                                   237 
278 At the time of this patch, there is no real ha    238 At the time of this patch, there is no real hardware that supports both these
279 features. However, these features do interact     239 features. However, these features do interact with each other, and it's not
280 completely trivial to make them both work toge    240 completely trivial to make them both work together properly. In particular,
281 when a WRITE bio wants to use inline encryptio    241 when a WRITE bio wants to use inline encryption on a device that supports both
282 features, the bio will have an encryption cont    242 features, the bio will have an encryption context specified, after which
283 its integrity information is calculated (using    243 its integrity information is calculated (using the plaintext data, since
284 the encryption will happen while data is being    244 the encryption will happen while data is being written), and the data and
285 integrity info is sent to the device. Obviousl    245 integrity info is sent to the device. Obviously, the integrity info must be
286 verified before the data is encrypted. After t    246 verified before the data is encrypted. After the data is encrypted, the device
287 must not store the integrity info that it rece    247 must not store the integrity info that it received with the plaintext data
288 since that might reveal information about the     248 since that might reveal information about the plaintext data. As such, it must
289 re-generate the integrity info from the cipher    249 re-generate the integrity info from the ciphertext data and store that on disk
290 instead. Another issue with storing the integr    250 instead. Another issue with storing the integrity info of the plaintext data is
291 that it changes the on disk format depending o    251 that it changes the on disk format depending on whether hardware inline
292 encryption support is present or the kernel cr    252 encryption support is present or the kernel crypto API fallback is used (since
293 if the fallback is used, the device will recei    253 if the fallback is used, the device will receive the integrity info of the
294 ciphertext, not that of the plaintext).           254 ciphertext, not that of the plaintext).
295                                                   255 
296 Because there isn't any real hardware yet, it     256 Because there isn't any real hardware yet, it seems prudent to assume that
297 hardware implementations might not implement b    257 hardware implementations might not implement both features together correctly,
298 and disallow the combination for now. Whenever    258 and disallow the combination for now. Whenever a device supports integrity, the
299 kernel will pretend that the device does not s    259 kernel will pretend that the device does not support hardware inline encryption
300 (by setting the blk_crypto_profile in the requ !! 260 (by essentially setting the keyslot manager in the request_queue of the device
301 When the crypto API fallback is enabled, this  !! 261 to NULL). When the crypto API fallback is enabled, this means that all bios with
302 encryption context will use the fallback, and  !! 262 and encryption context will use the fallback, and IO will complete as usual.
303 the fallback is disabled, a bio with an encryp !! 263 When the fallback is disabled, a bio with an encryption context will be failed.
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php