€•     Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ+/translations/zh_CN/block/inline-encryption”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ+/translations/zh_TW/block/inline-encryption”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ+/translations/it_IT/block/inline-encryption”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ+/translations/ja_JP/block/inline-encryption”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ+/translations/ko_KR/block/inline-encryption”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ+/translations/sp_SP/block/inline-encryption”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒE/var/lib/git/docbuild/linux/Documentation/block/inline-encryption.rst”h KubhŒtarget”“”)”}”(hŒ.. _inline_encryption:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œinline-encryption”uh1h´h KhhhžhhŸh³ubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒInline Encryption”h]”hŒInline Encryption”…””}”(hhÉhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhhÄhžhhŸh³h KubhÃ)”}”(hhh]”(hÈ)”}”(hŒ
Background”h]”hŒ
Background”…””}”(hhÚhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhh×hžhhŸh³h K
ubhŒ	paragraph”“”)”}”(hX…  Inline encryption hardware sits logically between memory and disk, and can
en/decrypt data as it goes in/out of the disk.  For each I/O request, software
can control exactly how the inline encryption hardware will en/decrypt the data
in terms of key, algorithm, data unit size (the granularity of en/decryption),
and data unit number (a value that determines the initialization vector(s)).”h]”hX…  Inline encryption hardware sits logically between memory and disk, and can
en/decrypt data as it goes in/out of the disk.  For each I/O request, software
can control exactly how the inline encryption hardware will en/decrypt the data
in terms of key, algorithm, data unit size (the granularity of en/decryption),
and data unit number (a value that determines the initialization vector(s)).”…””}”(hhêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubhé)”}”(hX}  Some inline encryption hardware accepts all encryption parameters including raw
keys directly in low-level I/O requests.  However, most inline encryption
hardware instead has a fixed number of "keyslots" and requires that the key,
algorithm, and data unit size first be programmed into a keyslot.  Each
low-level I/O request then just contains a keyslot index and data unit number.”h]”hX  Some inline encryption hardware accepts all encryption parameters including raw
keys directly in low-level I/O requests.  However, most inline encryption
hardware instead has a fixed number of â€œkeyslotsâ€ and requires that the key,
algorithm, and data unit size first be programmed into a keyslot.  Each
low-level I/O request then just contains a keyslot index and data unit number.”…””}”(hhøhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubhé)”}”(hXm  Note that inline encryption hardware is very different from traditional crypto
accelerators, which are supported through the kernel crypto API.  Traditional
crypto accelerators operate on memory regions, whereas inline encryption
hardware operates on I/O requests.  Thus, inline encryption hardware needs to be
managed by the block layer, not the kernel crypto API.”h]”hXm  Note that inline encryption hardware is very different from traditional crypto
accelerators, which are supported through the kernel crypto API.  Traditional
crypto accelerators operate on memory regions, whereas inline encryption
hardware operates on I/O requests.  Thus, inline encryption hardware needs to be
managed by the block layer, not the kernel crypto API.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubhé)”}”(hXÕ  Inline encryption hardware is also very different from "self-encrypting drives",
such as those based on the TCG Opal or ATA Security standards.  Self-encrypting
drives don't provide fine-grained control of encryption and provide no way to
verify the correctness of the resulting ciphertext.  Inline encryption hardware
provides fine-grained control of encryption, including the choice of key and
initialization vector for each sector, and can be tested for correctness.”h]”hXÛ  Inline encryption hardware is also very different from â€œself-encrypting drivesâ€,
such as those based on the TCG Opal or ATA Security standards.  Self-encrypting
drives donâ€™t provide fine-grained control of encryption and provide no way to
verify the correctness of the resulting ciphertext.  Inline encryption hardware
provides fine-grained control of encryption, including the choice of key and
initialization vector for each sector, and can be tested for correctness.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubeh}”(h]”Œ
background”ah ]”h"]”Œ
background”ah$]”h&]”uh1hÂhhÄhžhhŸh³h K
ubhÃ)”}”(hhh]”(hÈ)”}”(hŒ	Objective”h]”hŒ	Objective”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj*  hžhhŸh³h K&ubhé)”}”(hX¯  We want to support inline encryption in the kernel.  To make testing easier, we
also want support for falling back to the kernel crypto API when actual inline
encryption hardware is absent.  We also want inline encryption to work with
layered devices like device-mapper and loopback (i.e. we want to be able to use
the inline encryption hardware of the underlying devices if present, or else
fall back to crypto API en/decryption).”h]”hX¯  We want to support inline encryption in the kernel.  To make testing easier, we
also want support for falling back to the kernel crypto API when actual inline
encryption hardware is absent.  We also want inline encryption to work with
layered devices like device-mapper and loopback (i.e. we want to be able to use
the inline encryption hardware of the underlying devices if present, or else
fall back to crypto API en/decryption).”…””}”(hj;  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K(hj*  hžhubeh}”(h]”Œ	objective”ah ]”h"]”Œ	objective”ah$]”h&]”uh1hÂhhÄhžhhŸh³h K&ubhÃ)”}”(hhh]”(hÈ)”}”(hŒConstraints and notes”h]”hŒConstraints and notes”…””}”(hjT  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjQ  hžhhŸh³h K0ubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hXY  We need a way for upper layers (e.g. filesystems) to specify an encryption
context to use for en/decrypting a bio, and device drivers (e.g. UFSHCD) need
to be able to use that encryption context when they process the request.
Encryption contexts also introduce constraints on bio merging; the block layer
needs to be aware of these constraints.
”h]”hé)”}”(hXX  We need a way for upper layers (e.g. filesystems) to specify an encryption
context to use for en/decrypting a bio, and device drivers (e.g. UFSHCD) need
to be able to use that encryption context when they process the request.
Encryption contexts also introduce constraints on bio merging; the block layer
needs to be aware of these constraints.”h]”hXX  We need a way for upper layers (e.g. filesystems) to specify an encryption
context to use for en/decrypting a bio, and device drivers (e.g. UFSHCD) need
to be able to use that encryption context when they process the request.
Encryption contexts also introduce constraints on bio merging; the block layer
needs to be aware of these constraints.”…””}”(hjm  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K2hji  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hjd  hžhhŸh³h Nubjh  )”}”(hX  Different inline encryption hardware has different supported algorithms,
supported data unit sizes, maximum data unit numbers, etc.  We call these
properties the "crypto capabilities".  We need a way for device drivers to
advertise crypto capabilities to upper layers in a generic way.
”h]”hé)”}”(hX  Different inline encryption hardware has different supported algorithms,
supported data unit sizes, maximum data unit numbers, etc.  We call these
properties the "crypto capabilities".  We need a way for device drivers to
advertise crypto capabilities to upper layers in a generic way.”h]”hX!  Different inline encryption hardware has different supported algorithms,
supported data unit sizes, maximum data unit numbers, etc.  We call these
properties the â€œcrypto capabilitiesâ€.  We need a way for device drivers to
advertise crypto capabilities to upper layers in a generic way.”…””}”(hj…  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K8hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hjd  hžhhŸh³h Nubjh  )”}”(hXo  Inline encryption hardware usually (but not always) requires that keys be
programmed into keyslots before being used.  Since programming keyslots may be
slow and there may not be very many keyslots, we shouldn't just program the
key for every I/O request, but rather keep track of which keys are in the
keyslots and reuse an already-programmed keyslot when possible.
”h]”hé)”}”(hXn  Inline encryption hardware usually (but not always) requires that keys be
programmed into keyslots before being used.  Since programming keyslots may be
slow and there may not be very many keyslots, we shouldn't just program the
key for every I/O request, but rather keep track of which keys are in the
keyslots and reuse an already-programmed keyslot when possible.”h]”hXp  Inline encryption hardware usually (but not always) requires that keys be
programmed into keyslots before being used.  Since programming keyslots may be
slow and there may not be very many keyslots, we shouldnâ€™t just program the
key for every I/O request, but rather keep track of which keys are in the
keyslots and reuse an already-programmed keyslot when possible.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K=hj™  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hjd  hžhhŸh³h Nubjh  )”}”(hX&  Upper layers typically define a specific end-of-life for crypto keys, e.g.
when an encrypted directory is locked or when a crypto mapping is torn down.
At these times, keys are wiped from memory.  We must provide a way for upper
layers to also evict keys from any keyslots they are present in.
”h]”hé)”}”(hX%  Upper layers typically define a specific end-of-life for crypto keys, e.g.
when an encrypted directory is locked or when a crypto mapping is torn down.
At these times, keys are wiped from memory.  We must provide a way for upper
layers to also evict keys from any keyslots they are present in.”h]”hX%  Upper layers typically define a specific end-of-life for crypto keys, e.g.
when an encrypted directory is locked or when a crypto mapping is torn down.
At these times, keys are wiped from memory.  We must provide a way for upper
layers to also evict keys from any keyslots they are present in.”…””}”(hjµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KChj±  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hjd  hžhhŸh³h Nubjh  )”}”(hŒÔWhen possible, device-mapper devices must be able to pass through the inline
encryption support of their underlying devices.  However, it doesn't make
sense for device-mapper devices to have keyslots themselves.
”h]”hé)”}”(hŒÓWhen possible, device-mapper devices must be able to pass through the inline
encryption support of their underlying devices.  However, it doesn't make
sense for device-mapper devices to have keyslots themselves.”h]”hŒÕWhen possible, device-mapper devices must be able to pass through the inline
encryption support of their underlying devices.  However, it doesnâ€™t make
sense for device-mapper devices to have keyslots themselves.”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KHhjÉ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hjd  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jb  hŸh³h K2hjQ  hžhubeh}”(h]”Œconstraints-and-notes”ah ]”h"]”Œconstraints and notes”ah$]”h&]”uh1hÂhhÄhžhhŸh³h K0ubhÃ)”}”(hhh]”(hÈ)”}”(hŒBasic design”h]”hŒBasic design”…””}”(hjô  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjñ  hžhhŸh³h KMubhé)”}”(hXu  We introduce ``struct blk_crypto_key`` to represent an inline encryption key and
how it will be used.  This includes the type of the key (raw or
hardware-wrapped); the actual bytes of the key; the size of the key; the
algorithm and data unit size the key will be used with; and the number of bytes
needed to represent the maximum data unit number the key will be used with.”h]”(hŒWe introduce ”…””}”(hj  hžhhŸNh NubhŒliteral”“”)”}”(hŒ``struct blk_crypto_key``”h]”hŒstruct blk_crypto_key”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj  ubhXO   to represent an inline encryption key and
how it will be used.  This includes the type of the key (raw or
hardware-wrapped); the actual bytes of the key; the size of the key; the
algorithm and data unit size the key will be used with; and the number of bytes
needed to represent the maximum data unit number the key will be used with.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KOhjñ  hžhubhé)”}”(hXZ  We introduce ``struct bio_crypt_ctx`` to represent an encryption context.  It
contains a data unit number and a pointer to a blk_crypto_key.  We add pointers
to a bio_crypt_ctx to ``struct bio`` and ``struct request``; this allows users
of the block layer (e.g. filesystems) to provide an encryption context when
creating a bio and have it be passed down the stack for processing by the block
layer and device drivers.  Note that the encryption context doesn't explicitly
say whether to encrypt or decrypt, as that is implicit from the direction of the
bio; WRITE means encrypt, and READ means decrypt.”h]”(hŒWe introduce ”…””}”(hj$  hžhhŸNh Nubj  )”}”(hŒ``struct bio_crypt_ctx``”h]”hŒstruct bio_crypt_ctx”…””}”(hj,  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj$  ubhŒ to represent an encryption context.  It
contains a data unit number and a pointer to a blk_crypto_key.  We add pointers
to a bio_crypt_ctx to ”…””}”(hj$  hžhhŸNh Nubj  )”}”(hŒ``struct bio``”h]”hŒ
struct bio”…””}”(hj>  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj$  ubhŒ and ”…””}”(hj$  hžhhŸNh Nubj  )”}”(hŒ``struct request``”h]”hŒstruct request”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj$  ubhXƒ  ; this allows users
of the block layer (e.g. filesystems) to provide an encryption context when
creating a bio and have it be passed down the stack for processing by the block
layer and device drivers.  Note that the encryption context doesnâ€™t explicitly
say whether to encrypt or decrypt, as that is implicit from the direction of the
bio; WRITE means encrypt, and READ means decrypt.”…””}”(hj$  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KUhjñ  hžhubhé)”}”(hXø  We also introduce ``struct blk_crypto_profile`` to contain all generic inline
encryption-related state for a particular inline encryption device.  The
blk_crypto_profile serves as the way that drivers for inline encryption hardware
advertise their crypto capabilities and provide certain functions (e.g.,
functions to program and evict keys) to upper layers.  Each device driver that
wants to support inline encryption will construct a blk_crypto_profile, then
associate it with the disk's request_queue.”h]”(hŒWe also introduce ”…””}”(hjh  hžhhŸNh Nubj  )”}”(hŒ``struct blk_crypto_profile``”h]”hŒstruct blk_crypto_profile”…””}”(hjp  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjh  ubhXË   to contain all generic inline
encryption-related state for a particular inline encryption device.  The
blk_crypto_profile serves as the way that drivers for inline encryption hardware
advertise their crypto capabilities and provide certain functions (e.g.,
functions to program and evict keys) to upper layers.  Each device driver that
wants to support inline encryption will construct a blk_crypto_profile, then
associate it with the diskâ€™s request_queue.”…””}”(hjh  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K^hjñ  hžhubhé)”}”(hX/  The blk_crypto_profile also manages the hardware's keyslots, when applicable.
This happens in the block layer, so that users of the block layer can just
specify encryption contexts and don't need to know about keyslots at all, nor do
device drivers need to care about most details of keyslot management.”h]”hX3  The blk_crypto_profile also manages the hardwareâ€™s keyslots, when applicable.
This happens in the block layer, so that users of the block layer can just
specify encryption contexts and donâ€™t need to know about keyslots at all, nor do
device drivers need to care about most details of keyslot management.”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kfhjñ  hžhubhé)”}”(hX×  Specifically, for each keyslot, the block layer (via the blk_crypto_profile)
keeps track of which blk_crypto_key that keyslot contains (if any), and how many
in-flight I/O requests are using it.  When the block layer creates a
``struct request`` for a bio that has an encryption context, it grabs a keyslot
that already contains the key if possible.  Otherwise it waits for an idle
keyslot (a keyslot that isn't in-use by any I/O), then programs the key into the
least-recently-used idle keyslot using the function the device driver provided.
In both cases, the resulting keyslot is stored in the ``crypt_keyslot`` field of
the request, where it is then accessible to device drivers and is released after
the request completes.”h]”(hŒãSpecifically, for each keyslot, the block layer (via the blk_crypto_profile)
keeps track of which blk_crypto_key that keyslot contains (if any), and how many
in-flight I/O requests are using it.  When the block layer creates a
”…””}”(hj–  hžhhŸNh Nubj  )”}”(hŒ``struct request``”h]”hŒstruct request”…””}”(hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj–  ubhXb   for a bio that has an encryption context, it grabs a keyslot
that already contains the key if possible.  Otherwise it waits for an idle
keyslot (a keyslot that isnâ€™t in-use by any I/O), then programs the key into the
least-recently-used idle keyslot using the function the device driver provided.
In both cases, the resulting keyslot is stored in the ”…””}”(hj–  hžhhŸNh Nubj  )”}”(hŒ``crypt_keyslot``”h]”hŒcrypt_keyslot”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj–  ubhŒq field of
the request, where it is then accessible to device drivers and is released after
the request completes.”…””}”(hj–  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kkhjñ  hžhubhé)”}”(hX)  ``struct request`` also contains a pointer to the original bio_crypt_ctx.
Requests can be built from multiple bios, and the block layer must take the
encryption context into account when trying to merge bios and requests.  For two
bios/requests to be merged, they must have compatible encryption contexts: both
unencrypted, or both encrypted with the same key and contiguous data unit
numbers.  Only the encryption context for the first bio in a request is
retained, since the remaining bios have been verified to be merge-compatible
with the first bio.”h]”(j  )”}”(hŒ``struct request``”h]”hŒstruct request”…””}”(hjÌ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÈ  ubhX   also contains a pointer to the original bio_crypt_ctx.
Requests can be built from multiple bios, and the block layer must take the
encryption context into account when trying to merge bios and requests.  For two
bios/requests to be merged, they must have compatible encryption contexts: both
unencrypted, or both encrypted with the same key and contiguous data unit
numbers.  Only the encryption context for the first bio in a request is
retained, since the remaining bios have been verified to be merge-compatible
with the first bio.”…””}”(hjÈ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kvhjñ  hžhubhé)”}”(hX/  To make it possible for inline encryption to work with request_queue based
layered devices, when a request is cloned, its encryption context is cloned as
well.  When the cloned request is submitted, it is then processed as usual; this
includes getting a keyslot from the clone's target device if needed.”h]”hX1  To make it possible for inline encryption to work with request_queue based
layered devices, when a request is cloned, its encryption context is cloned as
well.  When the cloned request is submitted, it is then processed as usual; this
includes getting a keyslot from the cloneâ€™s target device if needed.”…””}”(hjä  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khjñ  hžhubeh}”(h]”Œbasic-design”ah ]”h"]”Œbasic design”ah$]”h&]”uh1hÂhhÄhžhhŸh³h KMubhÃ)”}”(hhh]”(hÈ)”}”(hŒblk-crypto-fallback”h]”hŒblk-crypto-fallback”…””}”(hjý  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjú  hžhhŸh³h K…ubhé)”}”(hXU  It is desirable for the inline encryption support of upper layers (e.g.
filesystems) to be testable without real inline encryption hardware, and
likewise for the block layer's keyslot management logic.  It is also desirable
to allow upper layers to just always use inline encryption rather than have to
implement encryption in multiple ways.”h]”hXW  It is desirable for the inline encryption support of upper layers (e.g.
filesystems) to be testable without real inline encryption hardware, and
likewise for the block layerâ€™s keyslot management logic.  It is also desirable
to allow upper layers to just always use inline encryption rather than have to
implement encryption in multiple ways.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K‡hjú  hžhubhé)”}”(hX¿  Therefore, we also introduce *blk-crypto-fallback*, which is an implementation
of inline encryption using the kernel crypto API.  blk-crypto-fallback is built
into the block layer, so it works on any block device without any special setup.
Essentially, when a bio with an encryption context is submitted to a
block_device that doesn't support that encryption context, the block layer will
handle en/decryption of the bio using blk-crypto-fallback.”h]”(hŒTherefore, we also introduce ”…””}”(hj  hžhhŸNh NubhŒemphasis”“”)”}”(hŒ*blk-crypto-fallback*”h]”hŒblk-crypto-fallback”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hj  ubhX  , which is an implementation
of inline encryption using the kernel crypto API.  blk-crypto-fallback is built
into the block layer, so it works on any block device without any special setup.
Essentially, when a bio with an encryption context is submitted to a
block_device that doesnâ€™t support that encryption context, the block layer will
handle en/decryption of the bio using blk-crypto-fallback.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khjú  hžhubhé)”}”(hXÂ  For encryption, the data cannot be encrypted in-place, as callers usually rely
on it being unmodified.  Instead, blk-crypto-fallback allocates bounce pages,
fills a new bio with those bounce pages, encrypts the data into those bounce
pages, and submits that "bounce" bio.  When the bounce bio completes,
blk-crypto-fallback completes the original bio.  If the original bio is too
large, multiple bounce bios may be required; see the code for details.”h]”hXÆ  For encryption, the data cannot be encrypted in-place, as callers usually rely
on it being unmodified.  Instead, blk-crypto-fallback allocates bounce pages,
fills a new bio with those bounce pages, encrypts the data into those bounce
pages, and submits that â€œbounceâ€ bio.  When the bounce bio completes,
blk-crypto-fallback completes the original bio.  If the original bio is too
large, multiple bounce bios may be required; see the code for details.”…””}”(hj;  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K”hjú  hžhubhé)”}”(hXî  For decryption, blk-crypto-fallback "wraps" the bio's completion callback
(``bi_complete``) and private data (``bi_private``) with its own, unsets the
bio's encryption context, then submits the bio.  If the read completes
successfully, blk-crypto-fallback restores the bio's original completion
callback and private data, then decrypts the bio's data in-place using the
kernel crypto API.  Decryption happens from a workqueue, as it may sleep.
Afterwards, blk-crypto-fallback completes the bio.”h]”(hŒQFor decryption, blk-crypto-fallback â€œwrapsâ€ the bioâ€™s completion callback
(”…””}”(hjI  hžhhŸNh Nubj  )”}”(hŒ``bi_complete``”h]”hŒbi_complete”…””}”(hjQ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjI  ubhŒ) and private data (”…””}”(hjI  hžhhŸNh Nubj  )”}”(hŒ``bi_private``”h]”hŒ
bi_private”…””}”(hjc  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjI  ubhXx  ) with its own, unsets the
bioâ€™s encryption context, then submits the bio.  If the read completes
successfully, blk-crypto-fallback restores the bioâ€™s original completion
callback and private data, then decrypts the bioâ€™s data in-place using the
kernel crypto API.  Decryption happens from a workqueue, as it may sleep.
Afterwards, blk-crypto-fallback completes the bio.”…””}”(hjI  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K›hjú  hžhubhé)”}”(hŒšIn both cases, the bios that blk-crypto-fallback submits no longer have an
encryption context.  Therefore, lower layers only see standard unencrypted I/O.”h]”hŒšIn both cases, the bios that blk-crypto-fallback submits no longer have an
encryption context.  Therefore, lower layers only see standard unencrypted I/O.”…””}”(hj{  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K£hjú  hžhubhé)”}”(hX“  blk-crypto-fallback also defines its own blk_crypto_profile and has its own
"keyslots"; its keyslots contain ``struct crypto_skcipher`` objects.  The reason
for this is twofold.  First, it allows the keyslot management logic to be tested
without actual inline encryption hardware.  Second, similar to actual inline
encryption hardware, the crypto API doesn't accept keys directly in requests but
rather requires that keys be set ahead of time, and setting keys can be
expensive; moreover, allocating a crypto_skcipher can't happen on the I/O path
at all due to the locks it takes.  Therefore, the concept of keyslots still
makes sense for blk-crypto-fallback.”h]”(hŒqblk-crypto-fallback also defines its own blk_crypto_profile and has its own
â€œkeyslotsâ€; its keyslots contain ”…””}”(hj‰  hžhhŸNh Nubj  )”}”(hŒ``struct crypto_skcipher``”h]”hŒstruct crypto_skcipher”…””}”(hj‘  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj‰  ubhX   objects.  The reason
for this is twofold.  First, it allows the keyslot management logic to be tested
without actual inline encryption hardware.  Second, similar to actual inline
encryption hardware, the crypto API doesnâ€™t accept keys directly in requests but
rather requires that keys be set ahead of time, and setting keys can be
expensive; moreover, allocating a crypto_skcipher canâ€™t happen on the I/O path
at all due to the locks it takes.  Therefore, the concept of keyslots still
makes sense for blk-crypto-fallback.”…””}”(hj‰  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K¦hjú  hžhubhé)”}”(hXi  Note that regardless of whether real inline encryption hardware or
blk-crypto-fallback is used, the ciphertext written to disk (and hence the
on-disk format of data) will be the same (assuming that both the inline
encryption hardware's implementation and the kernel crypto API's implementation
of the algorithm being used adhere to spec and function correctly).”h]”hXm  Note that regardless of whether real inline encryption hardware or
blk-crypto-fallback is used, the ciphertext written to disk (and hence the
on-disk format of data) will be the same (assuming that both the inline
encryption hardwareâ€™s implementation and the kernel crypto APIâ€™s implementation
of the algorithm being used adhere to spec and function correctly).”…””}”(hj©  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K°hjú  hžhubhé)”}”(hŒblk-crypto-fallback is optional and is controlled by the
``CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK`` kernel configuration option.”h]”(hŒ9blk-crypto-fallback is optional and is controlled by the
”…””}”(hj·  hžhhŸNh Nubj  )”}”(hŒ)``CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK``”h]”hŒ%CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK”…””}”(hj¿  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj·  ubhŒ kernel configuration option.”…””}”(hj·  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K¶hjú  hžhubeh}”(h]”Œblk-crypto-fallback”ah ]”h"]”Œblk-crypto-fallback”ah$]”h&]”uh1hÂhhÄhžhhŸh³h K…ubhÃ)”}”(hhh]”(hÈ)”}”(hŒ)API presented to users of the block layer”h]”hŒ)API presented to users of the block layer”…””}”(hjâ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjß  hžhhŸh³h Kºubhé)”}”(hXÓ  ``blk_crypto_config_supported()`` allows users to check ahead of time whether
inline encryption with particular crypto settings will work on a particular
block_device -- either via hardware or via blk-crypto-fallback.  This function
takes in a ``struct blk_crypto_config`` which is like blk_crypto_key, but omits
the actual bytes of the key and instead just contains the algorithm, data unit
size, etc.  This function can be useful if blk-crypto-fallback is disabled.”h]”(j  )”}”(hŒ!``blk_crypto_config_supported()``”h]”hŒblk_crypto_config_supported()”…””}”(hjô  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjð  ubhŒÓ allows users to check ahead of time whether
inline encryption with particular crypto settings will work on a particular
block_device -- either via hardware or via blk-crypto-fallback.  This function
takes in a ”…””}”(hjð  hžhhŸNh Nubj  )”}”(hŒ``struct blk_crypto_config``”h]”hŒstruct blk_crypto_config”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjð  ubhŒÃ which is like blk_crypto_key, but omits
the actual bytes of the key and instead just contains the algorithm, data unit
size, etc.  This function can be useful if blk-crypto-fallback is disabled.”…””}”(hjð  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K¼hjß  hžhubhé)”}”(hŒF``blk_crypto_init_key()`` allows users to initialize a blk_crypto_key.”h]”(j  )”}”(hŒ``blk_crypto_init_key()``”h]”hŒblk_crypto_init_key()”…””}”(hj"  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj  ubhŒ- allows users to initialize a blk_crypto_key.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KÃhjß  hžhubhé)”}”(hXq  Users must call ``blk_crypto_start_using_key()`` before actually starting to use
a blk_crypto_key on a block_device (even if ``blk_crypto_config_supported()``
was called earlier).  This is needed to initialize blk-crypto-fallback if it
will be needed.  This must not be called from the data path, as this may have to
allocate resources, which may deadlock in that case.”h]”(hŒUsers must call ”…””}”(hj:  hžhhŸNh Nubj  )”}”(hŒ ``blk_crypto_start_using_key()``”h]”hŒblk_crypto_start_using_key()”…””}”(hjB  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj:  ubhŒM before actually starting to use
a blk_crypto_key on a block_device (even if ”…””}”(hj:  hžhhŸNh Nubj  )”}”(hŒ!``blk_crypto_config_supported()``”h]”hŒblk_crypto_config_supported()”…””}”(hjT  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj:  ubhŒÓ
was called earlier).  This is needed to initialize blk-crypto-fallback if it
will be needed.  This must not be called from the data path, as this may have to
allocate resources, which may deadlock in that case.”…””}”(hj:  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KÅhjß  hžhubhé)”}”(hXt  Next, to attach an encryption context to a bio, users should call
``bio_crypt_set_ctx()``.  This function allocates a bio_crypt_ctx and attaches
it to a bio, given the blk_crypto_key and the data unit number that will be used
for en/decryption.  Users don't need to worry about freeing the bio_crypt_ctx
later, as that happens automatically when the bio is freed or reset.”h]”(hŒBNext, to attach an encryption context to a bio, users should call
”…””}”(hjl  hžhhŸNh Nubj  )”}”(hŒ``bio_crypt_set_ctx()``”h]”hŒbio_crypt_set_ctx()”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjl  ubhX  .  This function allocates a bio_crypt_ctx and attaches
it to a bio, given the blk_crypto_key and the data unit number that will be used
for en/decryption.  Users donâ€™t need to worry about freeing the bio_crypt_ctx
later, as that happens automatically when the bio is freed or reset.”…””}”(hjl  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KËhjß  hžhubhé)”}”(hX  Finally, when done using inline encryption with a blk_crypto_key on a
block_device, users must call ``blk_crypto_evict_key()``.  This ensures that
the key is evicted from all keyslots it may be programmed into and unlinked from
any kernel data structures it may be linked into.”h]”(hŒdFinally, when done using inline encryption with a blk_crypto_key on a
block_device, users must call ”…””}”(hjŒ  hžhhŸNh Nubj  )”}”(hŒ``blk_crypto_evict_key()``”h]”hŒblk_crypto_evict_key()”…””}”(hj”  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjŒ  ubhŒ—.  This ensures that
the key is evicted from all keyslots it may be programmed into and unlinked from
any kernel data structures it may be linked into.”…””}”(hjŒ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KÑhjß  hžhubhé)”}”(hŒZIn summary, for users of the block layer, the lifecycle of a blk_crypto_key is
as follows:”h]”hŒZIn summary, for users of the block layer, the lifecycle of a blk_crypto_key is
as follows:”…””}”(hj¬  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KÖhjß  hžhubhŒenumerated_list”“”)”}”(hhh]”(jh  )”}”(hŒ,``blk_crypto_config_supported()`` (optional)”h]”hé)”}”(hjÁ  h]”(j  )”}”(hŒ!``blk_crypto_config_supported()``”h]”hŒblk_crypto_config_supported()”…””}”(hjÆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÃ  ubhŒ (optional)”…””}”(hjÃ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KÙhj¿  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¼  hžhhŸh³h Nubjh  )”}”(hŒ``blk_crypto_init_key()``”h]”hé)”}”(hjæ  h]”j  )”}”(hjæ  h]”hŒblk_crypto_init_key()”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjè  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KÚhjä  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¼  hžhhŸh³h Nubjh  )”}”(hŒ ``blk_crypto_start_using_key()``”h]”hé)”}”(hj  h]”j  )”}”(hj  h]”hŒblk_crypto_start_using_key()”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KÛhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¼  hžhhŸh³h Nubjh  )”}”(hŒ0``bio_crypt_set_ctx()`` (potentially many times)”h]”hé)”}”(hj&  h]”(j  )”}”(hŒ``bio_crypt_set_ctx()``”h]”hŒbio_crypt_set_ctx()”…””}”(hj+  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj(  ubhŒ (potentially many times)”…””}”(hj(  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KÜhj$  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¼  hžhhŸh³h Nubjh  )”}”(hŒ8``blk_crypto_evict_key()`` (after all I/O has completed)”h]”hé)”}”(hjK  h]”(j  )”}”(hŒ``blk_crypto_evict_key()``”h]”hŒblk_crypto_evict_key()”…””}”(hjP  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjM  ubhŒ (after all I/O has completed)”…””}”(hjM  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KÝhjI  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¼  hžhhŸh³h Nubjh  )”}”(hŒ<Zeroize the blk_crypto_key (this has no dedicated function)
”h]”hé)”}”(hŒ;Zeroize the blk_crypto_key (this has no dedicated function)”h]”hŒ;Zeroize the blk_crypto_key (this has no dedicated function)”…””}”(hjr  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KÞhjn  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¼  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1jº  hjß  hžhhŸh³h KÙubhé)”}”(hŒÔIf a blk_crypto_key is being used on multiple block_devices, then
``blk_crypto_config_supported()`` (if used), ``blk_crypto_start_using_key()``,
and ``blk_crypto_evict_key()`` must be called on each block_device.”h]”(hŒBIf a blk_crypto_key is being used on multiple block_devices, then
”…””}”(hj‘  hžhhŸNh Nubj  )”}”(hŒ!``blk_crypto_config_supported()``”h]”hŒblk_crypto_config_supported()”…””}”(hj™  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj‘  ubhŒ (if used), ”…””}”(hj‘  hžhhŸNh Nubj  )”}”(hŒ ``blk_crypto_start_using_key()``”h]”hŒblk_crypto_start_using_key()”…””}”(hj«  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj‘  ubhŒ,
and ”…””}”(hj‘  hžhhŸNh Nubj  )”}”(hŒ``blk_crypto_evict_key()``”h]”hŒblk_crypto_evict_key()”…””}”(hj½  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj‘  ubhŒ% must be called on each block_device.”…””}”(hj‘  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kàhjß  hžhubeh}”(h]”Œ)api-presented-to-users-of-the-block-layer”ah ]”h"]”Œ)api presented to users of the block layer”ah$]”h&]”uh1hÂhhÄhžhhŸh³h KºubhÃ)”}”(hhh]”(hÈ)”}”(hŒAPI presented to device drivers”h]”hŒAPI presented to device drivers”…””}”(hjà  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjÝ  hžhhŸh³h Kåubhé)”}”(hX"  A device driver that wants to support inline encryption must set up a
blk_crypto_profile in the request_queue of its device.  To do this, it first
must call ``blk_crypto_profile_init()`` (or its resource-managed variant
``devm_blk_crypto_profile_init()``), providing the number of keyslots.”h]”(hŒA device driver that wants to support inline encryption must set up a
blk_crypto_profile in the request_queue of its device.  To do this, it first
must call ”…””}”(hjî  hžhhŸNh Nubj  )”}”(hŒ``blk_crypto_profile_init()``”h]”hŒblk_crypto_profile_init()”…””}”(hjö  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjî  ubhŒ" (or its resource-managed variant
”…””}”(hjî  hžhhŸNh Nubj  )”}”(hŒ"``devm_blk_crypto_profile_init()``”h]”hŒdevm_blk_crypto_profile_init()”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjî  ubhŒ$), providing the number of keyslots.”…””}”(hjî  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KçhjÝ  hžhubhé)”}”(hŒ–Next, it must advertise its crypto capabilities by setting fields in the
blk_crypto_profile, e.g. ``modes_supported`` and ``max_dun_bytes_supported``.”h]”(hŒbNext, it must advertise its crypto capabilities by setting fields in the
blk_crypto_profile, e.g. ”…””}”(hj   hžhhŸNh Nubj  )”}”(hŒ``modes_supported``”h]”hŒmodes_supported”…””}”(hj(  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj   ubhŒ and ”…””}”(hj   hžhhŸNh Nubj  )”}”(hŒ``max_dun_bytes_supported``”h]”hŒmax_dun_bytes_supported”…””}”(hj:  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj   ubhŒ.”…””}”(hj   hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KìhjÝ  hžhubhé)”}”(hXQ  It then must set function pointers in the ``ll_ops`` field of the
blk_crypto_profile to tell upper layers how to control the inline encryption
hardware, e.g. how to program and evict keyslots.  Most drivers will need to
implement ``keyslot_program`` and ``keyslot_evict``.  For details, see the
comments for ``struct blk_crypto_ll_ops``.”h]”(hŒ*It then must set function pointers in the ”…””}”(hjR  hžhhŸNh Nubj  )”}”(hŒ
``ll_ops``”h]”hŒll_ops”…””}”(hjZ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjR  ubhŒ² field of the
blk_crypto_profile to tell upper layers how to control the inline encryption
hardware, e.g. how to program and evict keyslots.  Most drivers will need to
implement ”…””}”(hjR  hžhhŸNh Nubj  )”}”(hŒ``keyslot_program``”h]”hŒkeyslot_program”…””}”(hjl  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjR  ubhŒ and ”…””}”(hjR  hžhhŸNh Nubj  )”}”(hŒ``keyslot_evict``”h]”hŒkeyslot_evict”…””}”(hj~  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjR  ubhŒ%.  For details, see the
comments for ”…””}”(hjR  hžhhŸNh Nubj  )”}”(hŒ``struct blk_crypto_ll_ops``”h]”hŒstruct blk_crypto_ll_ops”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjR  ubhŒ.”…””}”(hjR  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KïhjÝ  hžhubhé)”}”(hX  Once the driver registers a blk_crypto_profile with a request_queue, I/O
requests the driver receives via that queue may have an encryption context.  All
encryption contexts will be compatible with the crypto capabilities declared in
the blk_crypto_profile, so drivers don't need to worry about handling
unsupported requests.  Also, if a nonzero number of keyslots was declared in the
blk_crypto_profile, then all I/O requests that have an encryption context will
also have a keyslot which was already programmed with the appropriate key.”h]”hX  Once the driver registers a blk_crypto_profile with a request_queue, I/O
requests the driver receives via that queue may have an encryption context.  All
encryption contexts will be compatible with the crypto capabilities declared in
the blk_crypto_profile, so drivers donâ€™t need to worry about handling
unsupported requests.  Also, if a nonzero number of keyslots was declared in the
blk_crypto_profile, then all I/O requests that have an encryption context will
also have a keyslot which was already programmed with the appropriate key.”…””}”(hj¨  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KõhjÝ  hžhubhé)”}”(hX(  If the driver implements runtime suspend and its blk_crypto_ll_ops don't work
while the device is runtime-suspended, then the driver must also set the ``dev``
field of the blk_crypto_profile to point to the ``struct device`` that will be
resumed before any of the low-level operations are called.”h]”(hŒ™If the driver implements runtime suspend and its blk_crypto_ll_ops donâ€™t work
while the device is runtime-suspended, then the driver must also set the ”…””}”(hj¶  hžhhŸNh Nubj  )”}”(hŒ``dev``”h]”hŒdev”…””}”(hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj¶  ubhŒ1
field of the blk_crypto_profile to point to the ”…””}”(hj¶  hžhhŸNh Nubj  )”}”(hŒ``struct device``”h]”hŒstruct device”…””}”(hjÐ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj¶  ubhŒH that will be
resumed before any of the low-level operations are called.”…””}”(hj¶  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KýhjÝ  hžhubhé)”}”(hŒíIf there are situations where the inline encryption hardware loses the contents
of its keyslots, e.g. device resets, the driver must handle reprogramming the
keyslots.  To do this, the driver may call ``blk_crypto_reprogram_all_keys()``.”h]”(hŒÉIf there are situations where the inline encryption hardware loses the contents
of its keyslots, e.g. device resets, the driver must handle reprogramming the
keyslots.  To do this, the driver may call ”…””}”(hjè  hžhhŸNh Nubj  )”}”(hŒ#``blk_crypto_reprogram_all_keys()``”h]”hŒblk_crypto_reprogram_all_keys()”…””}”(hjð  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjè  ubhŒ.”…””}”(hjè  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MhjÝ  hžhubhé)”}”(hŒÙFinally, if the driver used ``blk_crypto_profile_init()`` instead of
``devm_blk_crypto_profile_init()``, then it is responsible for calling
``blk_crypto_profile_destroy()`` when the crypto profile is no longer needed.”h]”(hŒFinally, if the driver used ”…””}”(hj  hžhhŸNh Nubj  )”}”(hŒ``blk_crypto_profile_init()``”h]”hŒblk_crypto_profile_init()”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj  ubhŒ instead of
”…””}”(hj  hžhhŸNh Nubj  )”}”(hŒ"``devm_blk_crypto_profile_init()``”h]”hŒdevm_blk_crypto_profile_init()”…””}”(hj"  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj  ubhŒ%, then it is responsible for calling
”…””}”(hj  hžhhŸNh Nubj  )”}”(hŒ ``blk_crypto_profile_destroy()``”h]”hŒblk_crypto_profile_destroy()”…””}”(hj4  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj  ubhŒ- when the crypto profile is no longer needed.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MhjÝ  hžhubeh}”(h]”Œapi-presented-to-device-drivers”ah ]”h"]”Œapi presented to device drivers”ah$]”h&]”uh1hÂhhÄhžhhŸh³h KåubhÃ)”}”(hhh]”(hÈ)”}”(hŒLayered Devices”h]”hŒLayered Devices”…””}”(hjW  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjT  hžhhŸh³h Mubhé)”}”(hX^  Request queue based layered devices like dm-rq that wish to support inline
encryption need to create their own blk_crypto_profile for their request_queue,
and expose whatever functionality they choose. When a layered device wants to
pass a clone of that request to another request_queue, blk-crypto will
initialize and prepare the clone as necessary.”h]”hX^  Request queue based layered devices like dm-rq that wish to support inline
encryption need to create their own blk_crypto_profile for their request_queue,
and expose whatever functionality they choose. When a layered device wants to
pass a clone of that request to another request_queue, blk-crypto will
initialize and prepare the clone as necessary.”…””}”(hje  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MhjT  hžhubeh}”(h]”Œlayered-devices”ah ]”h"]”Œlayered devices”ah$]”h&]”uh1hÂhhÄhžhhŸh³h MubhÃ)”}”(hhh]”(hÈ)”}”(hŒ7Interaction between inline encryption and blk integrity”h]”hŒ7Interaction between inline encryption and blk integrity”…””}”(hj~  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj{  hžhhŸh³h Mubhé)”}”(hXî  At the time of this patch, there is no real hardware that supports both these
features. However, these features do interact with each other, and it's not
completely trivial to make them both work together properly. In particular,
when a WRITE bio wants to use inline encryption on a device that supports both
features, the bio will have an encryption context specified, after which
its integrity information is calculated (using the plaintext data, since
the encryption will happen while data is being written), and the data and
integrity info is sent to the device. Obviously, the integrity info must be
verified before the data is encrypted. After the data is encrypted, the device
must not store the integrity info that it received with the plaintext data
since that might reveal information about the plaintext data. As such, it must
re-generate the integrity info from the ciphertext data and store that on disk
instead. Another issue with storing the integrity info of the plaintext data is
that it changes the on disk format depending on whether hardware inline
encryption support is present or the kernel crypto API fallback is used (since
if the fallback is used, the device will receive the integrity info of the
ciphertext, not that of the plaintext).”h]”hXð  At the time of this patch, there is no real hardware that supports both these
features. However, these features do interact with each other, and itâ€™s not
completely trivial to make them both work together properly. In particular,
when a WRITE bio wants to use inline encryption on a device that supports both
features, the bio will have an encryption context specified, after which
its integrity information is calculated (using the plaintext data, since
the encryption will happen while data is being written), and the data and
integrity info is sent to the device. Obviously, the integrity info must be
verified before the data is encrypted. After the data is encrypted, the device
must not store the integrity info that it received with the plaintext data
since that might reveal information about the plaintext data. As such, it must
re-generate the integrity info from the ciphertext data and store that on disk
instead. Another issue with storing the integrity info of the plaintext data is
that it changes the on disk format depending on whether hardware inline
encryption support is present or the kernel crypto API fallback is used (since
if the fallback is used, the device will receive the integrity info of the
ciphertext, not that of the plaintext).”…””}”(hjŒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mhj{  hžhubhé)”}”(hXn  Because there isn't any real hardware yet, it seems prudent to assume that
hardware implementations might not implement both features together correctly,
and disallow the combination for now. Whenever a device supports integrity, the
kernel will pretend that the device does not support hardware inline encryption
(by setting the blk_crypto_profile in the request_queue of the device to NULL).
When the crypto API fallback is enabled, this means that all bios with and
encryption context will use the fallback, and IO will complete as usual.  When
the fallback is disabled, a bio with an encryption context will be failed.”h]”hXp  Because there isnâ€™t any real hardware yet, it seems prudent to assume that
hardware implementations might not implement both features together correctly,
and disallow the combination for now. Whenever a device supports integrity, the
kernel will pretend that the device does not support hardware inline encryption
(by setting the blk_crypto_profile in the request_queue of the device to NULL).
When the crypto API fallback is enabled, this means that all bios with and
encryption context will use the fallback, and IO will complete as usual.  When
the fallback is disabled, a bio with an encryption context will be failed.”…””}”(hjš  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M(hj{  hžhubhµ)”}”(hŒ.. _hardware_wrapped_keys:”h]”h}”(h]”h ]”h"]”h$]”h&]”hÀŒhardware-wrapped-keys”uh1h´h M1hj{  hžhhŸh³ubeh}”(h]”Œ7interaction-between-inline-encryption-and-blk-integrity”ah ]”h"]”Œ7interaction between inline encryption and blk integrity”ah$]”h&]”uh1hÂhhÄhžhhŸh³h MubhÃ)”}”(hhh]”(hÈ)”}”(hŒHardware-wrapped keys”h]”hŒHardware-wrapped keys”…””}”(hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj»  hžhhŸh³h M4ubhÃ)”}”(hhh]”(hÈ)”}”(hŒMotivation and threat model”h]”hŒMotivation and threat model”…””}”(hjÏ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjÌ  hžhhŸh³h M7ubhé)”}”(hXv  Linux storage encryption (dm-crypt, fscrypt, eCryptfs, etc.) traditionally
relies on the raw encryption key(s) being present in kernel memory so that the
encryption can be performed.  This traditionally isn't seen as a problem because
the key(s) won't be present during an offline attack, which is the main type of
attack that storage encryption is intended to protect from.”h]”hXz  Linux storage encryption (dm-crypt, fscrypt, eCryptfs, etc.) traditionally
relies on the raw encryption key(s) being present in kernel memory so that the
encryption can be performed.  This traditionally isnâ€™t seen as a problem because
the key(s) wonâ€™t be present during an offline attack, which is the main type of
attack that storage encryption is intended to protect from.”…””}”(hjÝ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M9hjÌ  hžhubhé)”}”(hŒƒHowever, there is an increasing desire to also protect users' data from other
types of attacks (to the extent possible), including:”h]”hŒ…However, there is an increasing desire to also protect usersâ€™ data from other
types of attacks (to the extent possible), including:”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M?hjÌ  hžhubjc  )”}”(hhh]”(jh  )”}”(hŒæCold boot attacks, where an attacker with physical access to a system suddenly
powers it off, then immediately dumps the system memory to extract recently
in-use encryption keys, then uses these keys to decrypt user data on-disk.
”h]”hé)”}”(hŒåCold boot attacks, where an attacker with physical access to a system suddenly
powers it off, then immediately dumps the system memory to extract recently
in-use encryption keys, then uses these keys to decrypt user data on-disk.”h]”hŒåCold boot attacks, where an attacker with physical access to a system suddenly
powers it off, then immediately dumps the system memory to extract recently
in-use encryption keys, then uses these keys to decrypt user data on-disk.”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MBhjü  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hjù  hžhhŸh³h Nubjh  )”}”(hX  Online attacks where the attacker is able to read kernel memory without fully
compromising the system, followed by an offline attack where any extracted
keys can be used to decrypt user data on-disk.  An example of such an online
attack would be if the attacker is able to run some code on the system that
exploits a Meltdown-like vulnerability but is unable to escalate privileges.
”h]”hé)”}”(hX~  Online attacks where the attacker is able to read kernel memory without fully
compromising the system, followed by an offline attack where any extracted
keys can be used to decrypt user data on-disk.  An example of such an online
attack would be if the attacker is able to run some code on the system that
exploits a Meltdown-like vulnerability but is unable to escalate privileges.”h]”hX~  Online attacks where the attacker is able to read kernel memory without fully
compromising the system, followed by an offline attack where any extracted
keys can be used to decrypt user data on-disk.  An example of such an online
attack would be if the attacker is able to run some code on the system that
exploits a Meltdown-like vulnerability but is unable to escalate privileges.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MFhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hjù  hžhhŸh³h Nubjh  )”}”(hX  Online attacks where the attacker fully compromises the system, but their data
exfiltration is significantly time-limited and/or bandwidth-limited, so in
order to completely exfiltrate the data they need to extract the encryption
keys to use in a later offline attack.
”h]”hé)”}”(hX  Online attacks where the attacker fully compromises the system, but their data
exfiltration is significantly time-limited and/or bandwidth-limited, so in
order to completely exfiltrate the data they need to extract the encryption
keys to use in a later offline attack.”h]”hX  Online attacks where the attacker fully compromises the system, but their data
exfiltration is significantly time-limited and/or bandwidth-limited, so in
order to completely exfiltrate the data they need to extract the encryption
keys to use in a later offline attack.”…””}”(hj0  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MLhj,  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hjù  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jç  jè  uh1jb  hŸh³h MBhjÌ  hžhubhé)”}”(hŒÜHardware-wrapped keys are a feature of inline encryption hardware that is
designed to protect users' data from the above attacks (to the extent possible),
without introducing limitations such as a maximum number of keys.”h]”hŒÞHardware-wrapped keys are a feature of inline encryption hardware that is
designed to protect usersâ€™ data from the above attacks (to the extent possible),
without introducing limitations such as a maximum number of keys.”…””}”(hjJ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MQhjÌ  hžhubhé)”}”(hX  Note that it is impossible to **fully** protect users' data from these attacks.
Even in the attacks where the attacker "just" gets read access to kernel memory,
they can still extract any user data that is present in memory, including
plaintext pagecache pages of encrypted files.  The focus here is just on
protecting the encryption keys, as those instantly give access to **all** user
data in any following offline attack, rather than just some of it (where which
data is included in that "some" might not be controlled by the attacker).”h]”(hŒNote that it is impossible to ”…””}”(hjX  hžhhŸNh NubhŒstrong”“”)”}”(hŒ	**fully**”h]”hŒfully”…””}”(hjb  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j`  hjX  ubhXU   protect usersâ€™ data from these attacks.
Even in the attacks where the attacker â€œjustâ€ gets read access to kernel memory,
they can still extract any user data that is present in memory, including
plaintext pagecache pages of encrypted files.  The focus here is just on
protecting the encryption keys, as those instantly give access to ”…””}”(hjX  hžhhŸNh Nubja  )”}”(hŒ**all**”h]”hŒall”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j`  hjX  ubhŒ¢ user
data in any following offline attack, rather than just some of it (where which
data is included in that â€œsomeâ€ might not be controlled by the attacker).”…””}”(hjX  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MUhjÌ  hžhubeh}”(h]”Œmotivation-and-threat-model”ah ]”h"]”Œmotivation and threat model”ah$]”h&]”uh1hÂhj»  hžhhŸh³h M7ubhÃ)”}”(hhh]”(hÈ)”}”(hŒSolution overview”h]”hŒSolution overview”…””}”(hj—  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj”  hžhhŸh³h M^ubhé)”}”(hX|  Inline encryption hardware typically has "keyslots" into which software can
program keys for the hardware to use; the contents of keyslots typically can't
be read back by software.  As such, the above security goals could be achieved
if the kernel simply erased its copy of the key(s) after programming them into
keyslot(s) and thereafter only referred to them via keyslot number.”h]”hX‚  Inline encryption hardware typically has â€œkeyslotsâ€ into which software can
program keys for the hardware to use; the contents of keyslots typically canâ€™t
be read back by software.  As such, the above security goals could be achieved
if the kernel simply erased its copy of the key(s) after programming them into
keyslot(s) and thereafter only referred to them via keyslot number.”…””}”(hj¥  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M`hj”  hžhubhé)”}”(hŒ9However, that naive approach runs into a couple problems:”h]”hŒ9However, that naive approach runs into a couple problems:”…””}”(hj³  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mfhj”  hžhubjc  )”}”(hhh]”(jh  )”}”(hXÐ  It limits the number of unlocked keys to the number of keyslots, which
typically is a small number.  In cases where there is only one encryption key
system-wide (e.g., a full-disk encryption key), that can be tolerable.
However, in general there can be many logged-in users with many different
keys, and/or many running applications with application-specific encrypted
storage areas.  This is especially true if file-based encryption (e.g.
fscrypt) is being used.
”h]”hé)”}”(hXÏ  It limits the number of unlocked keys to the number of keyslots, which
typically is a small number.  In cases where there is only one encryption key
system-wide (e.g., a full-disk encryption key), that can be tolerable.
However, in general there can be many logged-in users with many different
keys, and/or many running applications with application-specific encrypted
storage areas.  This is especially true if file-based encryption (e.g.
fscrypt) is being used.”h]”hXÏ  It limits the number of unlocked keys to the number of keyslots, which
typically is a small number.  In cases where there is only one encryption key
system-wide (e.g., a full-disk encryption key), that can be tolerable.
However, in general there can be many logged-in users with many different
keys, and/or many running applications with application-specific encrypted
storage areas.  This is especially true if file-based encryption (e.g.
fscrypt) is being used.”…””}”(hjÈ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MhhjÄ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hjÁ  hžhhŸh³h Nubjh  )”}”(hXµ  Inline crypto engines typically lose the contents of their keyslots if the
storage controller (usually UFS or eMMC) is reset.  Resetting the storage
controller is a standard error recovery procedure that is executed if certain
types of storage errors occur, and such errors can occur at any time.
Therefore, when inline crypto is being used, the operating system must always
be ready to reprogram the keyslots without user intervention.
”h]”hé)”}”(hX´  Inline crypto engines typically lose the contents of their keyslots if the
storage controller (usually UFS or eMMC) is reset.  Resetting the storage
controller is a standard error recovery procedure that is executed if certain
types of storage errors occur, and such errors can occur at any time.
Therefore, when inline crypto is being used, the operating system must always
be ready to reprogram the keyslots without user intervention.”h]”hX´  Inline crypto engines typically lose the contents of their keyslots if the
storage controller (usually UFS or eMMC) is reset.  Resetting the storage
controller is a standard error recovery procedure that is executed if certain
types of storage errors occur, and such errors can occur at any time.
Therefore, when inline crypto is being used, the operating system must always
be ready to reprogram the keyslots without user intervention.”…””}”(hjà  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MphjÜ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hjÁ  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jç  jè  uh1jb  hŸh³h Mhhj”  hžhubhé)”}”(hŒŠThus, it is important for the kernel to still have a way to "remind" the
hardware about a key, without actually having the raw key itself.”h]”hŒŽThus, it is important for the kernel to still have a way to â€œremindâ€ the
hardware about a key, without actually having the raw key itself.”…””}”(hjú  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mwhj”  hžhubhé)”}”(hX:  Somewhat less importantly, it is also desirable that the raw keys are never
visible to software at all, even while being initially unlocked.  This would
ensure that a read-only compromise of system memory will never allow a key to be
extracted to be used off-system, even if it occurs when a key is being unlocked.”h]”hX:  Somewhat less importantly, it is also desirable that the raw keys are never
visible to software at all, even while being initially unlocked.  This would
ensure that a read-only compromise of system memory will never allow a key to be
extracted to be used off-system, even if it occurs when a key is being unlocked.”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mzhj”  hžhubhé)”}”(hX€  To solve all these problems, some vendors of inline encryption hardware have
made their hardware support *hardware-wrapped keys*.  Hardware-wrapped keys
are encrypted keys that can only be unwrapped (decrypted) and used by hardware
-- either by the inline encryption hardware itself, or by a dedicated hardware
block that can directly provision keys to the inline encryption hardware.”h]”(hŒiTo solve all these problems, some vendors of inline encryption hardware have
made their hardware support ”…””}”(hj	  hžhhŸNh Nubj"  )”}”(hŒ*hardware-wrapped keys*”h]”hŒhardware-wrapped keys”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hj	  ubhX   .  Hardware-wrapped keys
are encrypted keys that can only be unwrapped (decrypted) and used by hardware
-- either by the inline encryption hardware itself, or by a dedicated hardware
block that can directly provision keys to the inline encryption hardware.”…””}”(hj	  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mhj”  hžhubhé)”}”(hŒì(We refer to them as "hardware-wrapped keys" rather than simply "wrapped keys"
to add some clarity in cases where there could be other types of wrapped keys,
such as in file-based encryption.  Key wrapping is a commonly used technique.)”h]”hŒô(We refer to them as â€œhardware-wrapped keysâ€ rather than simply â€œwrapped keysâ€
to add some clarity in cases where there could be other types of wrapped keys,
such as in file-based encryption.  Key wrapping is a commonly used technique.)”…””}”(hj6	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M…hj”  hžhubhé)”}”(hXÒ  The key which wraps (encrypts) hardware-wrapped keys is a hardware-internal key
that is never exposed to software; it is either a persistent key (a "long-term
wrapping key") or a per-boot key (an "ephemeral wrapping key").  The long-term
wrapped form of the key is what is initially unlocked, but it is erased from
memory as soon as it is converted into an ephemerally-wrapped key.  In-use
hardware-wrapped keys are always ephemerally-wrapped, not long-term wrapped.”h]”hXÚ  The key which wraps (encrypts) hardware-wrapped keys is a hardware-internal key
that is never exposed to software; it is either a persistent key (a â€œlong-term
wrapping keyâ€) or a per-boot key (an â€œephemeral wrapping keyâ€).  The long-term
wrapped form of the key is what is initially unlocked, but it is erased from
memory as soon as it is converted into an ephemerally-wrapped key.  In-use
hardware-wrapped keys are always ephemerally-wrapped, not long-term wrapped.”…””•gˆ      }”(hjD	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M‰hj”  hžhubhé)”}”(hXÒ  As inline encryption hardware can only be used to encrypt/decrypt data on-disk,
the hardware also includes a level of indirection; it doesn't use the unwrapped
key directly for inline encryption, but rather derives both an inline encryption
key and a "software secret" from it.  Software can use the "software secret" for
tasks that can't use the inline encryption hardware, such as filenames
encryption.  The software secret is not protected from memory compromise.”h]”hXÞ  As inline encryption hardware can only be used to encrypt/decrypt data on-disk,
the hardware also includes a level of indirection; it doesnâ€™t use the unwrapped
key directly for inline encryption, but rather derives both an inline encryption
key and a â€œsoftware secretâ€ from it.  Software can use the â€œsoftware secretâ€ for
tasks that canâ€™t use the inline encryption hardware, such as filenames
encryption.  The software secret is not protected from memory compromise.”…””}”(hjR	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mhj”  hžhubeh}”(h]”Œsolution-overview”ah ]”h"]”Œsolution overview”ah$]”h&]”uh1hÂhj»  hžhhŸh³h M^ubhÃ)”}”(hhh]”(hÈ)”}”(hŒKey hierarchy”h]”hŒKey hierarchy”…””}”(hjk	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjh	  hžhhŸh³h M˜ubhé)”}”(hŒ6Here is the key hierarchy for a hardware-wrapped key::”h]”hŒ5Here is the key hierarchy for a hardware-wrapped key:”…””}”(hjy	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mšhjh	  hžhubhŒliteral_block”“”)”}”(hX                 Hardware-wrapped key
                        |
                        |
                  <Hardware KDF>
                        |
          -----------------------------
          |                           |
Inline encryption key           Software secret”h]”hX                 Hardware-wrapped key
                        |
                        |
                  <Hardware KDF>
                        |
          -----------------------------
          |                           |
Inline encryption key           Software secret”…””}”hj‰	  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j‡	  hŸh³h Mœhjh	  hžhubhé)”}”(hŒThe components are:”h]”hŒThe components are:”…””}”(hj—	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M¥hjh	  hžhubjc  )”}”(hhh]”(jh  )”}”(hX'  *Hardware-wrapped key*: a key for the hardware's KDF (Key Derivation
Function), in ephemerally-wrapped form.  The key wrapping algorithm is a
hardware implementation detail that doesn't impact kernel operation, but a
strong authenticated encryption algorithm such as AES-256-GCM is recommended.
”h]”hé)”}”(hX&  *Hardware-wrapped key*: a key for the hardware's KDF (Key Derivation
Function), in ephemerally-wrapped form.  The key wrapping algorithm is a
hardware implementation detail that doesn't impact kernel operation, but a
strong authenticated encryption algorithm such as AES-256-GCM is recommended.”h]”(j"  )”}”(hŒ*Hardware-wrapped key*”h]”hŒHardware-wrapped key”…””}”(hj°	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hj¬	  ubhX  : a key for the hardwareâ€™s KDF (Key Derivation
Function), in ephemerally-wrapped form.  The key wrapping algorithm is a
hardware implementation detail that doesnâ€™t impact kernel operation, but a
strong authenticated encryption algorithm such as AES-256-GCM is recommended.”…””}”(hj¬	  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M§hj¨	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¥	  hžhhŸh³h Nubjh  )”}”(hXá  *Hardware KDF*: a KDF (Key Derivation Function) which the hardware uses to
derive subkeys after unwrapping the wrapped key.  The hardware's choice of KDF
doesn't impact kernel operation, but it does need to be known for testing
purposes, and it's also assumed to have at least a 256-bit security strength.
All known hardware uses the SP800-108 KDF in Counter Mode with AES-256-CMAC,
with a particular choice of labels and contexts; new hardware should use this
already-vetted KDF.
”h]”hé)”}”(hXà  *Hardware KDF*: a KDF (Key Derivation Function) which the hardware uses to
derive subkeys after unwrapping the wrapped key.  The hardware's choice of KDF
doesn't impact kernel operation, but it does need to be known for testing
purposes, and it's also assumed to have at least a 256-bit security strength.
All known hardware uses the SP800-108 KDF in Counter Mode with AES-256-CMAC,
with a particular choice of labels and contexts; new hardware should use this
already-vetted KDF.”h]”(j"  )”}”(hŒ*Hardware KDF*”h]”hŒHardware KDF”…””}”(hjÖ	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hjÒ	  ubhXØ  : a KDF (Key Derivation Function) which the hardware uses to
derive subkeys after unwrapping the wrapped key.  The hardwareâ€™s choice of KDF
doesnâ€™t impact kernel operation, but it does need to be known for testing
purposes, and itâ€™s also assumed to have at least a 256-bit security strength.
All known hardware uses the SP800-108 KDF in Counter Mode with AES-256-CMAC,
with a particular choice of labels and contexts; new hardware should use this
already-vetted KDF.”…””}”(hjÒ	  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M¬hjÎ	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¥	  hžhhŸh³h Nubjh  )”}”(hXx  *Inline encryption key*: a derived key which the hardware directly provisions
to a keyslot of the inline encryption hardware, without exposing it to
software.  In all known hardware, this will always be an AES-256-XTS key.
However, in principle other encryption algorithms could be supported too.
Hardware must derive distinct subkeys for each supported encryption algorithm.
”h]”hé)”}”(hXw  *Inline encryption key*: a derived key which the hardware directly provisions
to a keyslot of the inline encryption hardware, without exposing it to
software.  In all known hardware, this will always be an AES-256-XTS key.
However, in principle other encryption algorithms could be supported too.
Hardware must derive distinct subkeys for each supported encryption algorithm.”h]”(j"  )”}”(hŒ*Inline encryption key*”h]”hŒInline encryption key”…””}”(hjü	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hjø	  ubhX`  : a derived key which the hardware directly provisions
to a keyslot of the inline encryption hardware, without exposing it to
software.  In all known hardware, this will always be an AES-256-XTS key.
However, in principle other encryption algorithms could be supported too.
Hardware must derive distinct subkeys for each supported encryption algorithm.”…””}”(hjø	  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M´hjô	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¥	  hžhhŸh³h Nubjh  )”}”(hX  *Software secret*: a derived key which the hardware returns to software so
that software can use it for cryptographic tasks that can't use inline
encryption.  This value is cryptographically isolated from the inline
encryption key, i.e. knowing one doesn't reveal the other.  (The KDF ensures
this.)  Currently, the software secret is always 32 bytes and thus is suitable
for cryptographic applications that require up to a 256-bit security strength.
Some use cases (e.g. full-disk encryption) won't require the software secret.
”h]”hé)”}”(hX  *Software secret*: a derived key which the hardware returns to software so
that software can use it for cryptographic tasks that can't use inline
encryption.  This value is cryptographically isolated from the inline
encryption key, i.e. knowing one doesn't reveal the other.  (The KDF ensures
this.)  Currently, the software secret is always 32 bytes and thus is suitable
for cryptographic applications that require up to a 256-bit security strength.
Some use cases (e.g. full-disk encryption) won't require the software secret.”h]”(j"  )”}”(hŒ*Software secret*”h]”hŒSoftware secret”…””}”(hj"
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j!  hj
  ubhX  : a derived key which the hardware returns to software so
that software can use it for cryptographic tasks that canâ€™t use inline
encryption.  This value is cryptographically isolated from the inline
encryption key, i.e. knowing one doesnâ€™t reveal the other.  (The KDF ensures
this.)  Currently, the software secret is always 32 bytes and thus is suitable
for cryptographic applications that require up to a 256-bit security strength.
Some use cases (e.g. full-disk encryption) wonâ€™t require the software secret.”…””}”(hj
  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mºhj
  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¥	  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jç  jè  uh1jb  hŸh³h M§hjh	  hžhubhé)”}”(hX  Example: in the case of fscrypt, the fscrypt master key (the key that protects a
particular set of encrypted directories) is made hardware-wrapped.  The inline
encryption key is used as the file contents encryption key, while the software
secret (rather than the master key directly) is used to key fscrypt's KDF
(HKDF-SHA512) to derive other subkeys such as filenames encryption keys.”h]”hXƒ  Example: in the case of fscrypt, the fscrypt master key (the key that protects a
particular set of encrypted directories) is made hardware-wrapped.  The inline
encryption key is used as the file contents encryption key, while the software
secret (rather than the master key directly) is used to key fscryptâ€™s KDF
(HKDF-SHA512) to derive other subkeys such as filenames encryption keys.”…””}”(hjF
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MÂhjh	  hžhubhé)”}”(hXo  Note that currently this design assumes a single inline encryption key per
hardware-wrapped key, without any further key derivation.  Thus, in the case of
fscrypt, currently hardware-wrapped keys are only compatible with the "inline
encryption optimized" settings, which use one file contents encryption key per
encryption policy rather than one per file.  This design could be extended to
make the hardware derive per-file keys using per-file nonces passed down the
storage stack, and in fact some hardware already supports this; future work is
planned to remove this limitation by adding the corresponding kernel support.”h]”hXs  Note that currently this design assumes a single inline encryption key per
hardware-wrapped key, without any further key derivation.  Thus, in the case of
fscrypt, currently hardware-wrapped keys are only compatible with the â€œinline
encryption optimizedâ€ settings, which use one file contents encryption key per
encryption policy rather than one per file.  This design could be extended to
make the hardware derive per-file keys using per-file nonces passed down the
storage stack, and in fact some hardware already supports this; future work is
planned to remove this limitation by adding the corresponding kernel support.”…””}”(hjT
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MÈhjh	  hžhubeh}”(h]”Œkey-hierarchy”ah ]”h"]”Œkey hierarchy”ah$]”h&]”uh1hÂhj»  hžhhŸh³h M˜ubhÃ)”}”(hhh]”(hÈ)”}”(hŒKernel support”h]”hŒKernel support”…””}”(hjm
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjj
  hžhhŸh³h MÒubhé)”}”(hŒàThe inline encryption support of the kernel's block layer ("blk-crypto") has
been extended to support hardware-wrapped keys as an alternative to raw keys,
when hardware support is available.  This works in the following way:”h]”hŒæThe inline encryption support of the kernelâ€™s block layer (â€œblk-cryptoâ€) has
been extended to support hardware-wrapped keys as an alternative to raw keys,
when hardware support is available.  This works in the following way:”…””}”(hj{
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MÔhjj
  hžhubjc  )”}”(hhh]”(jh  )”}”(hŒÉA ``key_types_supported`` field is added to the crypto capabilities in
``struct blk_crypto_profile``.  This allows device drivers to declare that
they support raw keys, hardware-wrapped keys, or both.
”h]”hé)”}”(hŒÈA ``key_types_supported`` field is added to the crypto capabilities in
``struct blk_crypto_profile``.  This allows device drivers to declare that
they support raw keys, hardware-wrapped keys, or both.”h]”(hŒA ”…””}”(hj
  hžhhŸNh Nubj  )”}”(hŒ``key_types_supported``”h]”hŒkey_types_supported”…””}”(hj˜
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj
  ubhŒ. field is added to the crypto capabilities in
”…””}”(hj
  hžhhŸNh Nubj  )”}”(hŒ``struct blk_crypto_profile``”h]”hŒstruct blk_crypto_profile”…””}”(hjª
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj
  ubhŒd.  This allows device drivers to declare that
they support raw keys, hardware-wrapped keys, or both.”…””}”(hj
  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MØhjŒ
  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj‰
  hžhhŸh³h Nubjh  )”}”(hXI  ``struct blk_crypto_key`` can now contain a hardware-wrapped key as an
alternative to a raw key; a ``key_type`` field is added to
``struct blk_crypto_config`` to distinguish between the different key types.
This allows users of blk-crypto to en/decrypt data using a hardware-wrapped
key in a way very similar to using a raw key.
”h]”hé)”}”(hXH  ``struct blk_crypto_key`` can now contain a hardware-wrapped key as an
alternative to a raw key; a ``key_type`` field is added to
``struct blk_crypto_config`` to distinguish between the different key types.
This allows users of blk-crypto to en/decrypt data using a hardware-wrapped
key in a way very similar to using a raw key.”h]”(j  )”}”(hŒ``struct blk_crypto_key``”h]”hŒstruct blk_crypto_key”…””}”(hjÐ
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÌ
  ubhŒJ can now contain a hardware-wrapped key as an
alternative to a raw key; a ”…””}”(hjÌ
  hžhhŸNh Nubj  )”}”(hŒ``key_type``”h]”hŒkey_type”…””}”(hjâ
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÌ
  ubhŒ field is added to
”…””}”(hjÌ
  hžhhŸNh Nubj  )”}”(hŒ``struct blk_crypto_config``”h]”hŒstruct blk_crypto_config”…””}”(hjô
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÌ
  ubhŒª to distinguish between the different key types.
This allows users of blk-crypto to en/decrypt data using a hardware-wrapped
key in a way very similar to using a raw key.”…””}”(hjÌ
  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MÜhjÈ
  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj‰
  hžhhŸh³h Nubjh  )”}”(hŒåA new method ``blk_crypto_ll_ops::derive_sw_secret`` is added.  Device drivers
that support hardware-wrapped keys must implement this method.  Users of
blk-crypto can call ``blk_crypto_derive_sw_secret()`` to access this method.
”h]”hé)”}”(hŒäA new method ``blk_crypto_ll_ops::derive_sw_secret`` is added.  Device drivers
that support hardware-wrapped keys must implement this method.  Users of
blk-crypto can call ``blk_crypto_derive_sw_secret()`` to access this method.”h]”(hŒA new method ”…””}”(hj  hžhhŸNh Nubj  )”}”(hŒ'``blk_crypto_ll_ops::derive_sw_secret``”h]”hŒ#blk_crypto_ll_ops::derive_sw_secret”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj  ubhŒx is added.  Device drivers
that support hardware-wrapped keys must implement this method.  Users of
blk-crypto can call ”…””}”(hj  hžhhŸNh Nubj  )”}”(hŒ!``blk_crypto_derive_sw_secret()``”h]”hŒblk_crypto_derive_sw_secret()”…””}”(hj0  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj  ubhŒ to access this method.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mâhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj‰
  hžhhŸh³h Nubjh  )”}”(hX)  The programming and eviction of hardware-wrapped keys happens via
``blk_crypto_ll_ops::keyslot_program`` and
``blk_crypto_ll_ops::keyslot_evict``, just like it does for raw keys.  If a
driver supports hardware-wrapped keys, then it must handle hardware-wrapped
keys being passed to these methods.
”h]”hé)”}”(hX(  The programming and eviction of hardware-wrapped keys happens via
``blk_crypto_ll_ops::keyslot_program`` and
``blk_crypto_ll_ops::keyslot_evict``, just like it does for raw keys.  If a
driver supports hardware-wrapped keys, then it must handle hardware-wrapped
keys being passed to these methods.”h]”(hŒBThe programming and eviction of hardware-wrapped keys happens via
”…””}”(hjR  hžhhŸNh Nubj  )”}”(hŒ&``blk_crypto_ll_ops::keyslot_program``”h]”hŒ"blk_crypto_ll_ops::keyslot_program”…””}”(hjZ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjR  ubhŒ and
”…””}”(hjR  hžhhŸNh Nubj  )”}”(hŒ$``blk_crypto_ll_ops::keyslot_evict``”h]”hŒ blk_crypto_ll_ops::keyslot_evict”…””}”(hjl  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjR  ubhŒ—, just like it does for raw keys.  If a
driver supports hardware-wrapped keys, then it must handle hardware-wrapped
keys being passed to these methods.”…””}”(hjR  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MæhjN  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj‰
  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jç  jè  uh1jb  hŸh³h MØhjj
  hžhubhé)”}”(hŒ•blk-crypto-fallback doesn't support hardware-wrapped keys.  Therefore,
hardware-wrapped keys can only be used with actual inline encryption hardware.”h]”hŒ—blk-crypto-fallback doesnâ€™t support hardware-wrapped keys.  Therefore,
hardware-wrapped keys can only be used with actual inline encryption hardware.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mìhjj
  hžhubhé)”}”(hŒáAll the above deals with hardware-wrapped keys in ephemerally-wrapped form only.
To get such keys in the first place, new block device ioctls have been added to
provide a generic interface to creating and preparing such keys:”h]”hŒáAll the above deals with hardware-wrapped keys in ephemerally-wrapped form only.
To get such keys in the first place, new block device ioctls have been added to
provide a generic interface to creating and preparing such keys:”…””}”(hjž  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mïhjj
  hžhubjc  )”}”(hhh]”(jh  )”}”(hXð  ``BLKCRYPTOIMPORTKEY`` converts a raw key to long-term wrapped form.  It takes
in a pointer to a ``struct blk_crypto_import_key_arg``.  The caller must set
``raw_key_ptr`` and ``raw_key_size`` to the pointer and size (in bytes) of the
raw key to import.  On success, ``BLKCRYPTOIMPORTKEY`` returns 0 and writes
the resulting long-term wrapped key blob to the buffer pointed to by
``lt_key_ptr``, which is of maximum size ``lt_key_size``.  It also updates
``lt_key_size`` to be the actual size of the key.  On failure, it returns -1
and sets errno.  An errno of ``EOPNOTSUPP`` indicates that the block device
does not support hardware-wrapped keys.  An errno of ``EOVERFLOW`` indicates
that the output buffer did not have enough space for the key blob.
”h]”hé)”}”(hXï  ``BLKCRYPTOIMPORTKEY`` converts a raw key to long-term wrapped form.  It takes
in a pointer to a ``struct blk_crypto_import_key_arg``.  The caller must set
``raw_key_ptr`` and ``raw_key_size`` to the pointer and size (in bytes) of the
raw key to import.  On success, ``BLKCRYPTOIMPORTKEY`` returns 0 and writes
the resulting long-term wrapped key blob to the buffer pointed to by
``lt_key_ptr``, which is of maximum size ``lt_key_size``.  It also updates
``lt_key_size`` to be the actual size of the key.  On failure, it returns -1
and sets errno.  An errno of ``EOPNOTSUPP`` indicates that the block device
does not support hardware-wrapped keys.  An errno of ``EOVERFLOW`` indicates
that the output buffer did not have enough space for the key blob.”h]”(j  )”}”(hŒ``BLKCRYPTOIMPORTKEY``”h]”hŒBLKCRYPTOIMPORTKEY”…””}”(hj·  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒK converts a raw key to long-term wrapped form.  It takes
in a pointer to a ”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ$``struct blk_crypto_import_key_arg``”h]”hŒ struct blk_crypto_import_key_arg”…””}”(hjÉ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒ.  The caller must set
”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``raw_key_ptr``”h]”hŒraw_key_ptr”…””}”(hjÛ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒ and ”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``raw_key_size``”h]”hŒraw_key_size”…””}”(hjí  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒK to the pointer and size (in bytes) of the
raw key to import.  On success, ”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``BLKCRYPTOIMPORTKEY``”h]”hŒBLKCRYPTOIMPORTKEY”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒ[ returns 0 and writes
the resulting long-term wrapped key blob to the buffer pointed to by
”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``lt_key_ptr``”h]”hŒ
lt_key_ptr”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒ, which is of maximum size ”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``lt_key_size``”h]”hŒlt_key_size”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒ.  It also updates
”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``lt_key_size``”h]”hŒlt_key_size”…””}”(hj5  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒ[ to be the actual size of the key.  On failure, it returns -1
and sets errno.  An errno of ”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``EOPNOTSUPP``”h]”hŒ
EOPNOTSUPP”…””}”(hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒV indicates that the block device
does not support hardware-wrapped keys.  An errno of ”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``EOVERFLOW``”h]”hŒ	EOVERFLOW”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒM indicates
that the output buffer did not have enough space for the key blob.”…””}”(hj³  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Móhj¯  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¬  hžhhŸh³h Nubjh  )”}”(hŒÀ``BLKCRYPTOGENERATEKEY`` is like ``BLKCRYPTOIMPORTKEY``, but it has the
hardware generate the key instead of importing one.  It takes in a pointer to
a ``struct blk_crypto_generate_key_arg``.
”h]”hé)”}”(hŒ¿``BLKCRYPTOGENERATEKEY`` is like ``BLKCRYPTOIMPORTKEY``, but it has the
hardware generate the key instead of importing one.  It takes in a pointer to
a ``struct blk_crypto_generate_key_arg``.”h]”(j  )”}”(hŒ``BLKCRYPTOGENERATEKEY``”h]”hŒBLKCRYPTOGENERATEKEY”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj{  ubhŒ	 is like ”…””}”(hj{  hžhhŸNh Nubj  )”}”(hŒ``BLKCRYPTOIMPORTKEY``”h]”hŒBLKCRYPTOIMPORTKEY”…””}”(hj‘  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj{  ubhŒa, but it has the
hardware generate the key instead of importing one.  It takes in a pointer to
a ”…””}”(hj{  hžhhŸNh Nubj  )”}”(hŒ&``struct blk_crypto_generate_key_arg``”h]”hŒ"struct blk_crypto_generate_key_arg”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj{  ubhŒ.”…””}”(hj{  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mþhjw  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¬  hžhhŸh³h Nubjh  )”}”(hX  ``BLKCRYPTOPREPAREKEY`` converts a key from long-term wrapped form to
ephemerally-wrapped form.  It takes in a pointer to a ``struct
blk_crypto_prepare_key_arg``.  The caller must set ``lt_key_ptr`` and
``lt_key_size`` to the pointer and size (in bytes) of the long-term wrapped
key blob to convert.  On success, ``BLKCRYPTOPREPAREKEY`` returns 0 and writes
the resulting ephemerally-wrapped key blob to the buffer pointed to by
``eph_key_ptr``, which is of maximum size ``eph_key_size``.  It also updates
``eph_key_size`` to be the actual size of the key.  On failure, it returns -1
and sets errno.  Errno values of ``EOPNOTSUPP`` and ``EOVERFLOW`` mean the
same as they do for ``BLKCRYPTOIMPORTKEY``.  An errno of ``EBADMSG`` indicates
that the long-term wrapped key is invalid.
”h]”hé)”}”(hX  ``BLKCRYPTOPREPAREKEY`` converts a key from long-term wrapped form to
ephemerally-wrapped form.  It takes in a pointer to a ``struct
blk_crypto_prepare_key_arg``.  The caller must set ``lt_key_ptr`` and
``lt_key_size`` to the pointer and size (in bytes) of the long-term wrapped
key blob to convert.  On success, ``BLKCRYPTOPREPAREKEY`` returns 0 and writes
the resulting ephemerally-wrapped key blob to the buffer pointed to by
``eph_key_ptr``, which is of maximum size ``eph_key_size``.  It also updates
``eph_key_size`` to be the actual size of the key.  On failure, it returns -1
and sets errno.  Errno values of ``EOPNOTSUPP`` and ``EOVERFLOW`` mean the
same as they do for ``BLKCRYPTOIMPORTKEY``.  An errno of ``EBADMSG`` indicates
that the long-term wrapped key is invalid.”h]”(j  )”}”(hŒ``BLKCRYPTOPREPAREKEY``”h]”hŒBLKCRYPTOPREPAREKEY”…””}”(hjÉ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒe converts a key from long-term wrapped form to
ephemerally-wrapped form.  It takes in a pointer to a ”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ%``struct
blk_crypto_prepare_key_arg``”h]”hŒ!struct
blk_crypto_prepare_key_arg”…””}”(hjÛ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ.  The caller must set ”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ``lt_key_ptr``”h]”hŒ
lt_key_ptr”…””}”(hjí  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ and
”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ``lt_key_size``”h]”hŒlt_key_size”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ_ to the pointer and size (in bytes) of the long-term wrapped
key blob to convert.  On success, ”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ``BLKCRYPTOPREPAREKEY``”h]”hŒBLKCRYPTOPREPAREKEY”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ] returns 0 and writes
the resulting ephemerally-wrapped key blob to the buffer pointed to by
”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ``eph_key_ptr``”h]”hŒeph_key_ptr”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ, which is of maximum size ”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ``eph_key_size``”h]”hŒeph_key_size”…””}”(hj5  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ.  It also updates
”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ``eph_key_size``”h]”hŒeph_key_size”…””}”(hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ_ to be the actual size of the key.  On failure, it returns -1
and sets errno.  Errno values of ”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ``EOPNOTSUPP``”h]”hŒ
EOPNOTSUPP”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ and ”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ``EOVERFLOW``”h]”hŒ	EOVERFLOW”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ mean the
same as they do for ”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ``BLKCRYPTOIMPORTKEY``”h]”hŒBLKCRYPTOIMPORTKEY”…””}”(hj}  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ.  An errno of ”…””}”(hjÅ  hžhhŸNh Nubj  )”}”(hŒ``EBADMSG``”h]”hŒEBADMSG”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hjÅ  ubhŒ5 indicates
that the long-term wrapped key is invalid.”…””}”(hjÅ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h MhjÁ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jg  hj¬  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”jç  jè  uh1jb  hŸh³h Móhjj
  hžhubhé)”}”(hX  Userspace needs to use either ``BLKCRYPTOIMPORTKEY`` or ``BLKCRYPTOGENERATEKEY``
once to create a key, and then ``BLKCRYPTOPREPAREKEY`` each time the key is
unlocked and added to the kernel.  Note that these ioctls have no relevance for
raw keys; they are only for hardware-wrapped keys.”h]”(hŒUserspace needs to use either ”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``BLKCRYPTOIMPORTKEY``”h]”hŒBLKCRYPTOIMPORTKEY”…””}”(hj»  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒ or ”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``BLKCRYPTOGENERATEKEY``”h]”hŒBLKCRYPTOGENERATEKEY”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒ 
once to create a key, and then ”…””}”(hj³  hžhhŸNh Nubj  )”}”(hŒ``BLKCRYPTOPREPAREKEY``”h]”hŒBLKCRYPTOPREPAREKEY”…””}”(hjß  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j
  hj³  ubhŒ˜ each time the key is
unlocked and added to the kernel.  Note that these ioctls have no relevance for
raw keys; they are only for hardware-wrapped keys.”…””}”(hj³  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mhjj
  hžhubeh}”(h]”Œkernel-support”ah ]”h"]”Œkernel support”ah$]”h&]”uh1hÂhj»  hžhhŸh³h MÒubhÃ)”}”(hhh]”(hÈ)”}”(hŒTestability”h]”hŒTestability”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjÿ  hžhhŸh³h Mubhé)”}”(hXS  Both the hardware KDF and the inline encryption itself are well-defined
algorithms that don't depend on any secrets other than the unwrapped key.
Therefore, if the unwrapped key is known to software, these algorithms can be
reproduced in software in order to verify the ciphertext that is written to disk
by the inline encryption hardware.”h]”hXU  Both the hardware KDF and the inline encryption itself are well-defined
algorithms that donâ€™t depend on any secrets other than the unwrapped key.
Therefore, if the unwrapped key is known to software, these algorithms can be
reproduced in software in order to verify the ciphertext that is written to disk
by the inline encryption hardware.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mhjÿ  hžhubhé)”}”(hXÉ  However, the unwrapped key will only be known to software for testing if the
"import" functionality is used.  Proper testing is not possible in the
"generate" case where the hardware generates the key itself.  The correct
operation of the "generate" mode thus relies on the security and correctness of
the hardware RNG and its use to generate the key, as well as the testing of the
"import" mode as that should cover all parts other than the key generation.”h]”hXÙ  However, the unwrapped key will only be known to software for testing if the
â€œimportâ€ functionality is used.  Proper testing is not possible in the
â€œgenerateâ€ case where the hardware generates the key itself.  The correct
operation of the â€œgenerateâ€ mode thus relies on the security and correctness of
the hardware RNG and its use to generate the key, as well as the testing of the
â€œimportâ€ mode as that should cover all parts other than the key generation.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Mhjÿ  hžhubhé)”}”(hX"  For an example of a test that verifies the ciphertext written to disk in the
"import" mode, see the fscrypt hardware-wrapped key tests in xfstests, or
`Android's vts_kernel_encryption_test
<https://android.googlesource.com/platform/test/vts-testcase/kernel/+/refs/heads/main/encryption/>`_.”h]”(hŒ›For an example of a test that verifies the ciphertext written to disk in the
â€œimportâ€ mode, see the fscrypt hardware-wrapped key tests in xfstests, or
”…””}”(hj,  hžhhŸNh NubhŒ	reference”“”)”}”(hŒŠ`Android's vts_kernel_encryption_test
<https://android.googlesource.com/platform/test/vts-testcase/kernel/+/refs/heads/main/encryption/>`_”h]”hŒ&Androidâ€™s vts_kernel_encryption_test”…””}”(hj6  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”Œ$Android's vts_kernel_encryption_test”Œrefuri”Œ`https://android.googlesource.com/platform/test/vts-testcase/kernel/+/refs/heads/main/encryption/”uh1j4  hj,  ubhµ)”}”(hŒc
<https://android.googlesource.com/platform/test/vts-testcase/kernel/+/refs/heads/main/encryption/>”h]”h}”(h]”Œ$android-s-vts-kernel-encryption-test”ah ]”h"]”Œ$android's vts_kernel_encryption_test”ah$]”h&]”Œrefuri”jG  uh1h´Œ
referenced”Khj,  ubhŒ.”…””}”(hj,  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h M#hjÿ  hžhubeh}”(h]”Œtestability”ah ]”h"]”Œtestability”ah$]”h&]”uh1hÂhj»  hžhhŸh³h Mubeh}”(h]”(j²  Œid2”eh ]”h"]”(Œhardware-wrapped keys”Œhardware_wrapped_keys”eh$]”h&]”uh1hÂhhÄhžhhŸh³h M4Œexpect_referenced_by_name”}”jn  j¨  sŒexpect_referenced_by_id”}”j²  j¨  subeh}”(h]”(hÁŒid1”eh ]”h"]”(Œinline encryption”Œinline_encryption”eh$]”h&]”uh1hÂhhhžhhŸh³h Kjq  }”j{  h¶sjs  }”hÁh¶subeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hÇNŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j£  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”(hÁ]”h¶aj²  ]”j¨  auŒnameids”}”(j{  hÁjz  jw  j'  j$  jN  jK  jî  jë  j÷  jô  jÜ  jÙ  jÚ  j×  jQ  jN  jx  ju  j¸  jµ  jn  j²  jm  jj  j‘  jŽ  je	  jb	  jg
  jd
  jü  jù  je  jb  jQ  jN  uŒ	nametypes”}”(j{  ˆjz  ‰j'  ‰jN  ‰jî  ‰j÷  ‰jÜ  ‰jÚ  ‰jQ  ‰jx  ‰j¸  ‰jn  ˆjm  ‰j‘  ‰je	  ‰jg
  ‰jü  ‰je  ‰jQ  ˆuh}”(hÁhÄjw  hÄj$  h×jK  j*  jë  jQ  jô  jñ  jÙ  jú  j×  jß  jN  jÝ  ju  jT  jµ  j{  j²  j»  jj  j»  jŽ  jÌ  jb	  j”  jd
  jh	  jù  jj
  jb  jÿ  jN  jH  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”j±  Ks…”R”Œparse_messages”]”Œtransform_messages”]”(hŒsystem_message”“”)”}”(hhh]”hé)”}”(hhh]”hŒ7Hyperlink target "inline-encryption" is not referenced.”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”uh1hèhj  ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h³Œline”Kuh1j	  ubj
  )”}”(hhh]”hé)”}”(hhh]”hŒ;Hyperlink target "hardware-wrapped-keys" is not referenced.”…””}”hj)  sbah}”(h]”h ]”h"]”h$]”h&]”uh1hèhj&  ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”j#  Œsource”h³Œline”M1uh1j	  ubeŒtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.