[PATCH v6 0/4] Add inline encryption support

[PATCH v6 0/4] Add inline encryption support

[Linlin Zhang]

This series adds inline encryption support to virtio-blk, for devices
backed by storage with an inline crypto engine, such as UFS or eMMC.

The device reports its capabilities in the configuration space: the
number of keyslots, the maximum Data Unit Number (DUN) size and the
supported key types (raw and hardware-wrapped). Keys are managed, and
the supported crypto modes are discovered, with group administration
commands of the Self group type, so the feature depends on
VIRTIO_F_ADMIN_VQ. Encrypted reads and writes are still submitted on
the request virtqueues; each of them identifies a programmed keyslot
and carries a 256-bit DUN.

Patch summary:
1. Add the feature bit and the configuration fields
2. Add the administration commands to manage the keys and to query the
   supported crypto modes
3. Add the encrypted request types
4. Describe what inline encryption does and does not protect against,
   in particular for confidential guests

This series is independent of, but is intended to be used together
with, the series adding administration virtqueue support to the MMIO
transport:
https://lore.kernel.org/all/20261017114556.1701355-1-parav@nvidia.com/

For background on inline encryption, see:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/block/inline-encryption.rst

The new administration command opcodes are allocated from 0x0013, not
from 0x0012: the group administration commands table in the current
specification lists 0x0013 - 0x7FFF as the range of commands using
struct virtio_admin_cmd, so the new commands start at the first opcode
of that range.

changes in v6:
 - Remove the dedicated control virtqueue and VIRTIO_BLK_F_CTRL_VQ; use
   group administration commands of the Self group type on the
   administration virtqueue instead, with opcodes 0x0013 - 0x0019
 - Change feature bit VIRTIO_BLK_F_INLINE_ENCRYPTION to 20
 - Require VIRTIO_F_ADMIN_VQ to be offered with
   VIRTIO_BLK_F_INLINE_ENCRYPTION
 - Never offer VIRTIO_BLK_F_INLINE_ENCRYPTION together with
   VIRTIO_BLK_F_ZONED, as the zoned write constraints do not guarantee
   that I/O addresses are aligned to the encryption data unit size
 - Widen max_slots to 32 bits, matching the 32-bit slot fields
 - Only report the commands in VIRTIO_ADMIN_CMD_LIST_QUERY if the
   device offers VIRTIO_BLK_F_INLINE_ENCRYPTION, and the
   hardware-wrapped key commands only if the device supports
   hardware-wrapped keys; fail VIRTIO_ADMIN_CMD_LIST_USE enabling them
   if the feature has not been negotiated
 - Define the long-term and ephemerally-wrapped forms of
   hardware-wrapped keys, and which form each command takes and returns
 - Do not program or evict a keyslot while requests using it are
   outstanding
 - Change struct virtio_blk_crypto_key_desc and struct
   virtio_blk_crypto_key_blob to use variable-length arrays; the key
   length is given by key_size, and buffer lengths follow the generic
   administration command rules, except that a command fails if a key
   would be truncated. Remove VIRTIO_BLK_CRYPTO_MAX_KEY_SIZE
 - Empty all keyslots on device reset, and fail requests using an empty
   keyslot with VIRTIO_BLK_S_IOERR
 - Report a failed GENERATE_KEY with any status other than
   VIRTIO_ADMIN_STATUS_OK; require a successful DERIVE_SW_SECRET to
   return the whole software secret; KEYSLOT_EVICT ignores all fields
   other than slot
 - Add a 'Security Considerations' subsection
 - Split the series into four patches

changes in v5:
 - Change feature bit value of VIRTIO_BLK_F_CTRL_VQ and
   VIRTIO_BLK_F_INLINE_ENCRYPTION to 20 and 21 respectively

changes in v4:
 - Add a control virtqueue specific subsection for virtio block
 - Move all control virtqueue request related to this new subsection
 - Add the precise semantics, error codes, etc for the new control
   virtqueue commands
 - Move 'MUST' to the normative section
 - Use c struct to describe control virtqueue request

changes in v3:
 - Add a control virtqueue
 - Move key program/evict/derive_sw_secret/generate/prepare/import to
   the control virtqueue
 - Add the driver and device requirements for the request in the control
   virtqueue
 - Extend DUN in crypto message to a fixed four-element array of 64-bit
   fields

changes in v2:
 - Remove virtualization-specific terminology
 - Move MUST sentence to the device/driver normative section
 - Add explicit rejection for CRYPTO request if IE feature bit
   isn't negotiated
 - Modify the support list of crypto modes and the definition of
   the size of the crypto modes buffer
---

Linlin Zhang (4):
  virtio-blk: Add inline encryption feature bit and configuration
  virtio-blk: Add inline encryption administration commands
  virtio-blk: Add inline encryption request types
  virtio-blk: Add inline encryption security considerations

 admin.tex                               |  16 +-
 device-types/blk/description.tex        | 827 +++++++++++++++++++++++-
 device-types/blk/device-conformance.tex |   1 +
 device-types/blk/driver-conformance.tex |   1 +
 4 files changed, 835 insertions(+), 10 deletions(-)

-- 
2.34.1

[PATCH v6 1/4] virtio-blk: Add inline encryption feature bit and configuration

[Linlin Zhang]

Inline crypto engines, such as those defined by JEDEC UFSHCI and eMMC
CQHCI, encrypt and decrypt data on its way to and from the storage,
using keys that are programmed into keyslots of the engine and selected
per request. Block devices backed by such storage have no way to expose
this capability to the driver so far.

As the first step towards supporting inline encryption in virtio-blk,
add the VIRTIO_BLK_F_INLINE_ENCRYPTION feature bit and the
enc_characteristics device configuration fields, which let the driver
discover the inline encryption capabilities of the device:

max_slots: number of keyslots.
max_dun_bytes: maximum size of the Data Unit Number (DUN) in bytes.
key_types: supported key types, raw and/or hardware-wrapped.

Keys are managed with group administration commands, therefore the
feature depends on VIRTIO_F_ADMIN_VQ.

max_slots is 32 bits wide, matching the 32-bit slot fields used in the
administration commands and in the requests.

Inline encryption cannot necessarily be supported on a zoned block
device, as the zoned write constraints do not guarantee that I/O
addresses are aligned to the encryption data unit size. Therefore the
feature is never offered together with VIRTIO_BLK_F_ZONED.

Driver requirements:
- VIRTIO_BLK_F_INLINE_ENCRYPTION is not negotiated without
  VIRTIO_F_ADMIN_VQ.
- The reserved field unused3 is ignored.

Device requirements:
- VIRTIO_BLK_F_INLINE_ENCRYPTION is only offered together with
  VIRTIO_F_ADMIN_VQ, and never together with VIRTIO_BLK_F_ZONED.
- FEATURES_OK is not acknowledged if VIRTIO_BLK_F_INLINE_ENCRYPTION is
  negotiated without VIRTIO_F_ADMIN_VQ.
- max_slots, max_dun_bytes and key_types report valid values.

Subsequent patches add the administration commands to manage the keys
and the request types which use them.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/238
Signed-off-by: Linlin Zhang <linlin.zhang@oss.qualcomm.com>
---
 device-types/blk/description.tex | 102 +++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)

diff --git a/device-types/blk/description.tex b/device-types/blk/description.tex
index 3b3a4e7..b347140 100644
--- a/device-types/blk/description.tex
+++ b/device-types/blk/description.tex
@@ -73,6 +73,17 @@ \subsection{Feature bits}\label{sec:Device Types / Block Device / Feature bits}
     VIRTIO_BLK_REQ_FLAG_OUT_FUA flag in the \field{flags} bitfield of the
     \field{virtio_blk_req} structure for VIRTIO_BLK_T_OUT requests.
 
+\item[VIRTIO_BLK_F_INLINE_ENCRYPTION (20)] Device supports inline
+    encryption: data written to or read from the device can be encrypted
+    or decrypted by an inline crypto engine in the device backend storage.
+    Keys are programmed into keyslots of the device, and each encrypted
+    request selects, by keyslot index, the key programmed into that
+    keyslot. The number of keyslots, the maximum size of the Data Unit
+    Number (DUN) and the supported key types are reported in
+    \field{enc_characteristics}. The keys are managed using group
+    administration commands sent on the administration virtqueue, so this
+    feature requires VIRTIO_F_ADMIN_VQ.
+
 \end{description}
 
 \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Block Device / Feature bits / Legacy Interface: Feature bits}
@@ -135,6 +146,12 @@ \subsection{Device configuration layout}\label{sec:Device Types / Block Device /
                 u8 model;
                 u8 unused2[3];
         } zoned;
+        struct virtio_blk_enc_characteristics {
+                le32 max_slots;
+                u8 max_dun_bytes;
+                u8 key_types;
+                u8 unused3[2];
+        } enc_characteristics;
 };
 \end{lstlisting}
 
@@ -222,6 +239,39 @@ \subsection{Device configuration layout}\label{sec:Device Types / Block Device /
 terminated by the device with a "zone resources exceeded" error as defined for
 specific commands later.
 
+If the VIRTIO_BLK_F_INLINE_ENCRYPTION feature is negotiated, then in
+\field{enc_characteristics},
+\begin{itemize}
+\item \field{max_slots} is the number of available keyslots. Keyslots are
+    indexed from 0 to \field{max_slots} - 1.
+
+\item \field{max_dun_bytes} is the maximum number of bytes of the Data Unit
+    Number (DUN) that the device supports for any of its supported crypto
+    modes.
+
+\item \field{key_types} is a bitmask of the key types the device supports,
+    using the following values:
+    \begin{lstlisting}
+#define VIRTIO_BLK_CRYPTO_KEY_TYPE_RAW         (1 << 0)
+#define VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED  (1 << 1)
+    \end{lstlisting}
+    VIRTIO_BLK_CRYPTO_KEY_TYPE_RAW indicates that keys are programmed into
+    keyslots in raw (plaintext) form. VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED
+    indicates that keys are programmed into keyslots in ephemerally-wrapped
+    form, and can only be unwrapped by dedicated hardware (e.g. a hardware
+    key manager), so that the plaintext key is never passed to the device
+    for keyslot programming. Outside of the device, such a key is stored in
+    a long-term wrapped form.
+
+\item \field{unused3} is reserved for future use.
+\end{itemize}
+
+\begin{note}
+For example, known inline crypto engines report a \field{max_dun_bytes} of
+4 (JEDEC eMMC Command Queue Host Controller Interface, CQHCI) or 8 (JEDEC
+UFS Host Controller Interface, UFSHCI).
+\end{note}
+
 \subsubsection{Legacy Interface: Device configuration layout}\label{sec:Device Types / Block Device / Device configuration layout / Legacy Interface: Device configuration layout}
 When using the legacy interface, transitional devices and drivers
 MUST format the fields in struct virtio_blk_config
@@ -285,6 +335,11 @@ \subsection{Device Initialization}\label{sec:Device Types / Block Device / Devic
     \field{zoned} can be read by the driver to determine the zone
     characteristics of the device. All \field{zoned} fields are read-only.
 
+\item If the VIRTIO_BLK_F_INLINE_ENCRYPTION feature is negotiated, the fields in
+    \field{enc_characteristics} can be read by the driver to determine the
+    inline encryption capabilities of the device. All
+    \field{enc_characteristics} fields are read-only.
+
 \end{enumerate}
 
 \drivernormative{\subsubsection}{Device Initialization}{Device Types / Block Device / Device Initialization}
@@ -327,6 +382,23 @@ \subsection{Device Initialization}\label{sec:Device Types / Block Device / Devic
 The driver MUST NOT negotiate VIRTIO_BLK_F_REQ_FLAGS_OUT_FUA without
 VIRTIO_BLK_F_REQ_FLAGS.
 
+Drivers MUST NOT negotiate the VIRTIO_BLK_F_INLINE_ENCRYPTION feature
+unless they are capable of:
+\begin{itemize}
+\item retrieving the inline encryption characteristics from the device
+    configuration space.
+\item programming and evicting keys in the block device's keyslots
+    through the administration virtqueue.
+\item submitting the keyslot index and Data Unit Number (DUN) per crypto
+    request to the device.
+\end{itemize}
+
+The driver MUST NOT negotiate VIRTIO_BLK_F_INLINE_ENCRYPTION without
+VIRTIO_F_ADMIN_VQ.
+
+If the VIRTIO_BLK_F_INLINE_ENCRYPTION feature is negotiated, the driver
+MUST ignore \field{unused3} in \field{enc_characteristics}.
+
 \devicenormative{\subsubsection}{Device Initialization}{Device Types / Block Device / Device Initialization}
 
 Devices SHOULD always offer VIRTIO_BLK_F_FLUSH, and MUST offer it
@@ -341,6 +413,9 @@ \subsection{Device Initialization}\label{sec:Device Types / Block Device / Devic
 If the device that is being initialized is a not a zoned device, the device
 SHOULD NOT offer the VIRTIO_BLK_F_ZONED feature.
 
+The device MUST NOT offer both the VIRTIO_BLK_F_ZONED and the
+VIRTIO_BLK_F_INLINE_ENCRYPTION features.
+
 The VIRTIO_BLK_F_ZONED feature cannot be properly negotiated without
 FEATURES_OK bit. Legacy devices MUST NOT offer VIRTIO_BLK_F_ZONED feature bit.
 
@@ -415,6 +490,33 @@ \subsection{Device Initialization}\label{sec:Device Types / Block Device / Devic
 The device MUST NOT acknowledge FEATURES_OK if the driver sets
 VIRTIO_BLK_F_REQ_FLAGS_OUT_FUA without VIRTIO_BLK_F_REQ_FLAGS.
 
+The VIRTIO_BLK_F_INLINE_ENCRYPTION feature cannot be properly negotiated
+without FEATURES_OK bit. Legacy devices MUST NOT offer the
+VIRTIO_BLK_F_INLINE_ENCRYPTION feature bit.
+
+The device MUST NOT offer VIRTIO_BLK_F_INLINE_ENCRYPTION unless it also
+offers VIRTIO_F_ADMIN_VQ.
+
+The device MUST NOT acknowledge FEATURES_OK if the driver negotiates
+VIRTIO_BLK_F_INLINE_ENCRYPTION without VIRTIO_F_ADMIN_VQ.
+
+If the VIRTIO_BLK_F_INLINE_ENCRYPTION feature is negotiated, the device
+MUST set \field{max_slots} in \field{enc_characteristics} to a value
+greater than 0. The value SHOULD reflect the number of keyslots that
+are available for use by this virtio-blk device.
+
+If the VIRTIO_BLK_F_INLINE_ENCRYPTION feature is negotiated, the device
+MUST set \field{key_types} in \field{enc_characteristics} to have at
+least one of VIRTIO_BLK_CRYPTO_KEY_TYPE_RAW or
+VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED set, and MUST NOT set any bit in
+\field{key_types} other than VIRTIO_BLK_CRYPTO_KEY_TYPE_RAW and
+VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED. The device MUST initialize padding
+bytes \field{unused3} to 0.
+
+If the VIRTIO_BLK_F_INLINE_ENCRYPTION feature is negotiated, the device
+MUST NOT set \field{max_dun_bytes} in \field{enc_characteristics} to 0 or
+to a value greater than 32.
+
 \subsubsection{Legacy Interface: Device Initialization}\label{sec:Device Types / Block Device / Device Initialization / Legacy Interface: Device Initialization}
 
 Because legacy devices do not have FEATURES_OK, transitional devices
-- 
2.34.1

[PATCH v6 2/4] virtio-blk: Add inline encryption administration commands

[Linlin Zhang]

With VIRTIO_BLK_F_INLINE_ENCRYPTION the driver can discover the inline
encryption capabilities of the device, but it has no way yet to query
the supported crypto modes or to manage the keys in the keyslots.

Add group administration commands for this. They operate on the device
itself, so they use the Self group type, and therefore work with any
transport which provides an administration virtqueue:

VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES (0x0013): query the supported
crypto modes and data unit sizes.
VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM (0x0014): program a key
into a keyslot.
VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT (0x0015): empty a keyslot.
VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET (0x0016): derive the
software secret of a hardware-wrapped key.
VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY (0x0017): generate a new
hardware-wrapped key.
VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY (0x0018): import a raw key as a
hardware-wrapped key.
VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY (0x0019): convert a long-term
wrapped key to its ephemerally-wrapped form.

The opcodes are allocated from the range of commands using struct
virtio_admin_cmd, and are listed in the group administration commands
table.

A hardware-wrapped key exists in a long-term wrapped form, returned by
GENERATE_KEY and IMPORT_KEY, and in an ephemerally-wrapped form,
returned by PREPARE_KEY, which is the form used by KEYSLOT_PROGRAM and
DERIVE_SW_SECRET. A device reset does not invalidate either form.

The length of a key is given by its key_size field. The buffer lengths
otherwise follow the generic rules for administration commands, except
that a command fails if a key does not fit in the buffer provided, as a
truncated key is unusable.

Driver requirements:
- The commands are only enabled and used if
  VIRTIO_BLK_F_INLINE_ENCRYPTION has been negotiated, and the
  hardware-wrapped key commands only if the device supports
  hardware-wrapped keys.
- The command specific data hold the whole key, in the wrapped form
  expected by the command, and the command specific result is large
  enough for the result. A returned key which was not written
  completely is treated as a failure.

Device requirements:
- The commands are reported by VIRTIO_ADMIN_CMD_LIST_QUERY if the
  device offers VIRTIO_BLK_F_INLINE_ENCRYPTION, so that the list of
  supported commands does not depend on feature negotiation; the
  hardware-wrapped key commands only if the device supports
  hardware-wrapped keys. VIRTIO_ADMIN_CMD_LIST_USE fails if it enables
  them and VIRTIO_BLK_F_INLINE_ENCRYPTION has not been negotiated.
- GET_CRYPTO_MODES reports 0 for unsupported crypto modes and no data
  unit size smaller than 512 bytes, and only writes whole entries into
  a result buffer which is too short.
- Invalid or inconsistent parameters fail the command with
  VIRTIO_ADMIN_STATUS_EINVAL and VIRTIO_ADMIN_STATUS_Q_INVALID_FIELD,
  and a result buffer too short for the returned key with
  VIRTIO_ADMIN_STATUS_EINVAL and VIRTIO_ADMIN_STATUS_Q_INVALID_COMMAND.
  A failed command neither changes the keyslot nor returns key
  material. A GENERATE_KEY which cannot generate a key fails with a
  status other than VIRTIO_ADMIN_STATUS_OK, without having to report
  the cause.
- On success, the command specific result holds the whole returned key
  or software secret. KEYSLOT_EVICT ignores all fields other than slot.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/238
Signed-off-by: Linlin Zhang <linlin.zhang@oss.qualcomm.com>
---
 admin.tex                               |  16 +-
 device-types/blk/description.tex        | 505 +++++++++++++++++++++++-
 device-types/blk/device-conformance.tex |   1 +
 device-types/blk/driver-conformance.tex |   1 +
 4 files changed, 521 insertions(+), 2 deletions(-)

diff --git a/admin.tex b/admin.tex
index cfca5e3..9d63aa5 100644
--- a/admin.tex
+++ b/admin.tex
@@ -158,8 +158,22 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti
 \hline
 0x0011 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-MODE-SET]{VIRTIO_ADMIN_CMD_DEV_MODE_SET} & Stop or resume the device \\
 \hline
+0x0013 & \hyperref[sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands]{VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES} & Get the inline encryption crypto modes supported by a block device \\
 \hline
-0x0013 - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd}    \\
+0x0014 & \hyperref[sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands]{VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM} & Program a key into a block device keyslot \\
+\hline
+0x0015 & \hyperref[sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands]{VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT} & Evict a key from a block device keyslot \\
+\hline
+0x0016 & \hyperref[sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands]{VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET} & Derive the software secret from a hardware-wrapped key of a block device \\
+\hline
+0x0017 & \hyperref[sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands]{VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY} & Generate a hardware-wrapped key in a block device \\
+\hline
+0x0018 & \hyperref[sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands]{VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY} & Import a raw key as a hardware-wrapped key in a block device \\
+\hline
+0x0019 & \hyperref[sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands]{VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY} & Convert a long-term wrapped key of a block device to its ephemerally-wrapped form \\
+\hline
+\hline
+0x001A - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd}    \\
 \hline
 0x8000 - 0xFFFF & - & Reserved for future commands (possibly using a different structure)    \\
 \hline
diff --git a/device-types/blk/description.tex b/device-types/blk/description.tex
index b347140..b85db2e 100644
--- a/device-types/blk/description.tex
+++ b/device-types/blk/description.tex
@@ -337,7 +337,10 @@ \subsection{Device Initialization}\label{sec:Device Types / Block Device / Devic
 
 \item If the VIRTIO_BLK_F_INLINE_ENCRYPTION feature is negotiated, the fields in
     \field{enc_characteristics} can be read by the driver to determine the
-    inline encryption capabilities of the device. All
+    inline encryption capabilities of the device, and a
+    VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES administration command (see
+    \ref{sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands})
+    can be sent to retrieve the set of supported crypto modes. All
     \field{enc_characteristics} fields are read-only.
 
 \end{enumerate}
@@ -1327,6 +1330,506 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 handles VIRTIO_BLK_T_ZONE_RESET request for the zone range specified in the
 VIRTIO_BLK_T_SECURE_ERASE request.
 
+\subsubsection{Inline Encryption Administration Commands}\label{sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands}
+If the VIRTIO_BLK_F_INLINE_ENCRYPTION and VIRTIO_F_ADMIN_VQ features are
+negotiated, the driver uses the administration virtqueue (see
+\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands})
+to send inline encryption key management commands to the device. These commands
+operate on the device itself, so they use the Self group type (0x0) with
+\field{group_member_id} set to 0. As a result they do not depend on the
+transport used by the device; any transport that provides an administration
+virtqueue for the Self group type can carry them.
+
+The following group administration commands are defined for use with the
+VIRTIO_BLK_F_INLINE_ENCRYPTION feature, with these \field{opcode} values:
+
+\begin{lstlisting}
+/* Get inline crypto modes */
+#define VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES          0x0013
+
+/* Program a key into the keyslot */
+#define VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM    0x0014
+
+/* Evict a key */
+#define VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT      0x0015
+
+/* Derive the software secret from a hardware-wrapped key */
+#define VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET   0x0016
+
+/* Generate a new hardware-wrapped key */
+#define VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY       0x0017
+
+/* Import a raw key as a hardware-wrapped key */
+#define VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY         0x0018
+
+/* Convert a long-term wrapped key to its ephemerally-wrapped form */
+#define VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY        0x0019
+\end{lstlisting}
+
+Each command uses the common structure of a group administration command.
+The result of a command is reported in \field{status} of that structure
+(VIRTIO_ADMIN_STATUS_OK on success), and the command-specific data are carried
+in \field{command_specific_data} and \field{command_specific_result} as
+follows:
+
+\begin{itemize}
+\item For VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES,
+    \field{command_specific_result} is struct virtio_blk_crypto_modes.
+    There is no \field{command_specific_data}.
+\item For VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM and
+    VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT, \field{command_specific_data}
+    is struct virtio_blk_crypto_key_desc. There is no
+    \field{command_specific_result}.
+\item For VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY,
+    \field{command_specific_result} is struct virtio_blk_crypto_key_blob.
+    There is no \field{command_specific_data}.
+\item For VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY and
+    VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY, both
+    \field{command_specific_data} and \field{command_specific_result} are
+    struct virtio_blk_crypto_key_blob.
+\item For VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET,
+    \field{command_specific_data} is struct virtio_blk_crypto_key_blob and
+    \field{command_specific_result} is struct virtio_blk_crypto_sw_secret.
+\end{itemize}
+
+\begin{lstlisting}
+struct virtio_blk_crypto_modes {
+        /*
+         * modes[N], for crypto mode number N <= VIRTIO_BLK_CRYPTO_MODE_MAX,
+         * is a bitmask of the data unit sizes with which crypto mode N can
+         * be used: bit i is set if a data unit size of (1 << i) bytes is
+         * supported. modes[0] is reserved and always 0.
+         */
+        le32 modes[VIRTIO_BLK_CRYPTO_MODE_MAX + 1];
+};
+\end{lstlisting}
+
+Crypto mode numbers are used as indices into \field{modes} in struct
+virtio_blk_crypto_modes above, and in \field{crypto_mode} in struct
+virtio_blk_crypto_key_desc. These numbers are assigned by this
+specification and are stable: a number is never reused for a different
+crypto mode, and additional crypto modes are assigned new, higher numbers.
+
+The crypto mode numbers currently defined by this specification are:
+
+\begin{lstlisting}
+#define VIRTIO_BLK_CRYPTO_MODE_INVALID          0
+#define VIRTIO_BLK_CRYPTO_MODE_AES_256_XTS      1
+
+/* Highest crypto mode number defined by this specification. */
+#define VIRTIO_BLK_CRYPTO_MODE_MAX              1
+\end{lstlisting}
+
+Crypto mode number 0 (VIRTIO_BLK_CRYPTO_MODE_INVALID) is reserved and is
+not used to reference an actual crypto mode.
+
+\begin{note}
+When a future version of this specification defines additional crypto
+modes, VIRTIO_BLK_CRYPTO_MODE_MAX and thus the size of struct
+virtio_blk_crypto_modes increase. A driver and a device implementing
+different versions of this specification remain compatible through the
+generic buffer length rules for administration commands: a device does
+not write the entries for crypto modes beyond the buffer provided by an
+older driver, and a newer driver interprets the entries which an older
+device does not write as 0, that is as not supported.
+\end{note}
+
+For VIRTIO_BLK_CRYPTO_MODE_AES_256_XTS, a raw key is 64 bytes long, that is
+two 256-bit AES keys. The size of a hardware-wrapped key is determined by
+the device, and is reported in \field{key_size} of the struct
+virtio_blk_crypto_key_blob returned by the command which produced the key.
+
+The VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES command queries which crypto modes
+and data unit sizes the device supports for inline encryption. The command
+has no \field{command_specific_data}. On success,
+\field{command_specific_result} is a struct virtio_blk_crypto_modes
+describing the supported (crypto mode, data unit size) combinations.
+
+\begin{lstlisting}
+/* Inline crypto key descriptor. */
+struct virtio_blk_crypto_key_desc {
+        le32  slot;
+        le32  key_size;
+        le32  crypto_mode;
+        le32  key_type;
+        le32  data_unit_size_bits;
+        le32  dun_bytes;
+        u8    bytes[];
+};
+\end{lstlisting}
+
+\field{slot} is the target keyslot in the device where the key is programmed.
+\field{crypto_mode} is the crypto mode number, used as an index into the
+\field{modes} array returned by a VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES request.
+\field{key_type} is either VIRTIO_BLK_CRYPTO_KEY_TYPE_RAW or
+VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED.
+\field{data_unit_size_bits} is the base-2 logarithm of the
+data unit size in bytes used by \field{crypto_mode}.
+\field{dun_bytes} is the number of bytes that will be used to specify the Data
+Unit Number when this key is used.
+\field{key_size} is the length of the key material in bytes, and the key
+material is the first \field{key_size} bytes of \field{bytes}.
+
+The VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM command programs a key into
+a keyslot, or overwrites the key already in that keyslot, for later use by
+VIRTIO_BLK_T_CRYPTO_IN and VIRTIO_BLK_T_CRYPTO_OUT requests. The keyslot
+index, key material, key size, crypto mode, key type, data unit size and
+DUN size are specified by the \field{slot}, \field{bytes}, \field{key_size},
+\field{crypto_mode}, \field{key_type}, \field{data_unit_size_bits} and
+\field{dun_bytes} in struct virtio_blk_crypto_key_desc respectively. These
+fields have to be valid and consistent with each other and with the values
+reported in \field{enc_characteristics}, otherwise the command fails and
+the keyslot is left unchanged.
+
+The VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT command empties a keyslot so
+that key information is removed and the keyslot cannot be used until it is
+programmed again. The keyslot index is specified by the \field{slot} in
+struct virtio_blk_crypto_key_desc and all other fields in the struct are
+ignored. Evicting a keyslot which is already empty succeeds.
+
+\begin{lstlisting}
+/* A raw or hardware-wrapped key. */
+struct virtio_blk_crypto_key_blob {
+        le32 key_size;
+        u8 key[];
+};
+\end{lstlisting}
+
+For struct virtio_blk_crypto_key_blob, \field{key_size} is the length of
+the key material in bytes, and the key material is the first
+\field{key_size} bytes of \field{key}.
+
+For struct virtio_blk_crypto_key_desc and struct
+virtio_blk_crypto_key_blob, the length of the key material is given by
+\field{key_size} and not by the length of the buffer. Any data following
+the first \field{key_size} bytes of \field{bytes} or \field{key} is not
+part of the key. The length of the buffers otherwise follows the general
+rules in \ref{sec:Basic Facilities of a Virtio Device / Administration Virtqueues},
+except that a key is never silently truncated: a buffer which is too
+short to hold the whole key causes the command to fail, as described
+below.
+
+When struct virtio_blk_crypto_key_blob is used as
+\field{command_specific_result}, the driver does not know the size of the
+returned key in advance, so it provides a buffer large enough for the
+largest key it is able to handle. The device knows from \field{opcode} that
+the result is struct virtio_blk_crypto_key_blob, and compares the length
+of the device-writeable buffer with the size of that struct including the
+key it returns. If the buffer is longer, the device writes only the struct
+and the key, and the driver ignores the rest of the buffer. If the buffer
+is too short to hold the whole key, the command fails.
+
+A hardware-wrapped key exists in two forms:
+\begin{itemize}
+\item The long-term wrapped form, returned by
+    VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY and
+    VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY, which the driver can store
+    persistently, for example on the storage.
+\item The ephemerally-wrapped form, returned by
+    VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY, which is the form used in
+    \field{bytes} of a VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM command
+    with \field{key_type} VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED and in
+    \field{command_specific_data} of a
+    VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET command.
+\end{itemize}
+A device reset (see
+\ref{sec:Basic Facilities of a Virtio Device / Device Reset}) only empties
+the keyslots, and does not affect the validity of the long-term wrapped and
+ephemerally-wrapped keys produced by the device before the reset.
+
+The VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY command asks the device to
+generate a new hardware-wrapped key. The command has no
+\field{command_specific_data}. On success, \field{command_specific_result}
+is a struct virtio_blk_crypto_key_blob containing the generated key, in
+long-term wrapped form, and its \field{key_size}.
+
+The VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY command asks the device to import
+a raw key and return its hardware-wrapped key. The raw key and its
+\field{key_size} are given in the \field{command_specific_data}, a
+struct virtio_blk_crypto_key_blob. On success,
+\field{command_specific_result} is a struct virtio_blk_crypto_key_blob
+containing the wrapped key, in long-term wrapped form, and its
+\field{key_size}.
+
+The VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY command converts a long-term
+hardware-wrapped key into its ephemerally-wrapped form, suitable for
+programming into a keyslot with VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM.
+The long-term wrapped key and its \field{key_size} are given in the
+\field{command_specific_data}, a struct virtio_blk_crypto_key_blob. On
+success, \field{command_specific_result} is a
+struct virtio_blk_crypto_key_blob containing the ephemerally-wrapped key
+and its \field{key_size}.
+
+\begin{lstlisting}
+#define VIRTIO_BLK_CRYPTO_SW_SECRET_SIZE        32
+
+struct virtio_blk_crypto_sw_secret {
+        u8 secret[VIRTIO_BLK_CRYPTO_SW_SECRET_SIZE];
+};
+\end{lstlisting}
+
+The VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET command derives the software
+secret associated with a hardware-wrapped key, for use by software that
+needs to operate on the key material outside of the device, for example
+for file system metadata encryption. The ephemerally-wrapped key and its
+\field{key_size} are given in the \field{command_specific_data}, a
+struct virtio_blk_crypto_key_blob. On success,
+\field{command_specific_result} is a struct virtio_blk_crypto_sw_secret
+containing the derived \field{secret}.
+
+\drivernormative{\paragraph}{Inline Encryption Administration Commands}{Device Types / Block Device / Device Operation / Inline Encryption Administration Commands}
+
+The driver MUST NOT send any of the commands above unless it has enabled
+the corresponding opcode for the Self group type with
+VIRTIO_ADMIN_CMD_LIST_USE, after querying the supported opcodes with
+VIRTIO_ADMIN_CMD_LIST_QUERY, and the VIRTIO_BLK_F_INLINE_ENCRYPTION and
+VIRTIO_F_ADMIN_VQ features have been negotiated.
+
+If the VIRTIO_BLK_F_INLINE_ENCRYPTION feature has not been negotiated, the
+driver MUST NOT enable the opcodes of the commands above with
+VIRTIO_ADMIN_CMD_LIST_USE.
+
+The driver MUST set \field{group_type} to 0x0 (Self group type) and
+\field{group_member_id} to 0 for these commands.
+
+When \field{command_specific_data} is struct virtio_blk_crypto_key_blob,
+or is struct virtio_blk_crypto_key_desc of a
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM command, the driver MUST provide
+a \field{command_specific_data} that contains the whole struct up to and
+including the first \field{key_size} bytes of \field{bytes} or \field{key}.
+The driver MAY append padding after the key material.
+\begin{note}
+Padding allows the driver to make the device-readable part of
+\field{struct virtio_admin_cmd}, including the key material, a multiple
+of 64 bit in length, as required by
+\ref{drivernormative:Basic Facilities of a Virtio Device / Administration virtqueues}.
+\end{note}
+
+The driver MUST provide a \field{command_specific_result} of at least the
+size of struct virtio_blk_crypto_modes, as defined by the version of this
+specification the driver implements, for
+VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES, and large enough to hold struct
+virtio_blk_crypto_sw_secret for
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET. For
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY and
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY, the driver SHOULD provide a
+\field{command_specific_result} large enough to hold struct
+virtio_blk_crypto_key_blob with the largest key the driver is able to
+handle.
+
+The driver MUST NOT set \field{crypto_mode} in struct
+virtio_blk_crypto_key_desc of a VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM
+command to a value greater than VIRTIO_BLK_CRYPTO_MODE_MAX, or to a crypto
+mode number that the device did not report as supported in reply to a
+VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES request.
+
+The driver MUST NOT set \field{opcode} to
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY or
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET unless the device reported
+VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED as set in \field{key_types}.
+
+For VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM and
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT commands, the driver MUST set
+\field{slot} in struct virtio_blk_crypto_key_desc to a value less than
+\field{max_slots} in \field{enc_characteristics}.
+\begin{note}
+As the device ignores all fields of struct virtio_blk_crypto_key_desc
+other than \field{slot} for a VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT
+command, the driver can, for example, set \field{key_size} to 0 and
+provide no key material for this command.
+\end{note}
+
+For a VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM command, the driver MUST
+\begin{itemize}
+\item set \field{key_size} to a value greater than 0.
+\item set \field{key_type} to either VIRTIO_BLK_CRYPTO_KEY_TYPE_RAW or
+    VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED, and MUST NOT set \field{key_type}
+    to VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED unless the device reported
+    VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED as set in \field{key_types}.
+\item set \field{data_unit_size_bits} to the base-2 logarithm of a data
+    unit size that the device reported as supported for \field{crypto_mode}
+    in reply to a VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES request.
+\item set \field{dun_bytes} to a value greater than 0 and not greater than
+    \field{max_dun_bytes} in \field{enc_characteristics}.
+\end{itemize}
+
+For VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY and
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET commands, the driver MUST set
+\field{key_size} in \field{command_specific_data} to a value greater than 0.
+
+If \field{key_type} is VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED, the driver
+MUST provide the key in \field{bytes} of a
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM command in ephemerally-wrapped
+form, as returned by VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY. The driver
+MUST provide the key in \field{command_specific_data} in
+ephemerally-wrapped form for a VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET
+command, and in long-term wrapped form for a
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY command.
+
+For VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY and
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY commands, the driver MUST treat the
+command as failed if \field{key_size} in \field{command_specific_result}
+is 0, or if the used buffer length shows that the device did not write
+the whole struct up to and including the first \field{key_size} bytes of
+\field{key}, and MUST ignore any data in \field{command_specific_result}
+following the first \field{key_size} bytes of \field{key}.
+
+\devicenormative{\paragraph}{Inline Encryption Administration Commands}{Device Types / Block Device / Device Operation / Inline Encryption Administration Commands}
+
+If the device offers the VIRTIO_BLK_F_INLINE_ENCRYPTION feature, the device
+MUST support the Self group type and MUST include the opcodes of the commands
+above in the list returned by VIRTIO_ADMIN_CMD_LIST_QUERY for the Self group
+type, except that the device MUST NOT include the opcodes of
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY and
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY in that list if it does not set
+VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED in \field{key_types}.
+
+If the VIRTIO_BLK_F_INLINE_ENCRYPTION feature has not been negotiated, the
+device MUST fail a VIRTIO_ADMIN_CMD_LIST_USE command which includes the
+opcode of any of the commands above with \field{status} set to
+VIRTIO_ADMIN_STATUS_EINVAL and \field{status_qualifier} set to
+VIRTIO_ADMIN_STATUS_Q_INVALID_FIELD.
+\begin{note}
+Which commands are reported by VIRTIO_ADMIN_CMD_LIST_QUERY depends on the
+features offered by the device, and not on the features negotiated, since
+\ref{devicenormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands}
+does not allow the list of supported commands to shrink.
+\end{note}
+
+When \field{command_specific_data} is struct virtio_blk_crypto_key_desc or
+struct virtio_blk_crypto_key_blob, the device MUST use only the first
+\field{key_size} bytes of \field{bytes} or \field{key} as the key material,
+and MUST ignore any data following them.
+
+For VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY and
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET commands, the device MUST
+complete the command with \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL
+and \field{status_qualifier} set to VIRTIO_ADMIN_STATUS_Q_INVALID_FIELD if
+\field{command_specific_data} does not contain the whole struct up to and
+including the first \field{key_size} bytes of \field{bytes} or \field{key}.
+\begin{note}
+Treating the missing key bytes as zero would silently produce a different
+key. This is therefore an intentional exception to the rule in
+\ref{devicenormative:Basic Facilities of a Virtio Device / Administration virtqueues}
+that the device does not fail a command solely because the buffers
+provided are shorter than described in this specification.
+\end{note}
+
+For VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY and
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY commands, the device MUST complete
+the command with \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL and
+\field{status_qualifier} set to VIRTIO_ADMIN_STATUS_Q_INVALID_COMMAND if
+\field{command_specific_result} is too short to hold struct
+virtio_blk_crypto_key_blob with the whole returned key, since a truncated
+key cannot be used.
+\begin{note}
+This is an intentional exception to the rule in
+\ref{devicenormative:Basic Facilities of a Virtio Device / Administration virtqueues}
+that the device does not fail a command solely because the buffers
+provided are shorter than described in this specification: a returned key
+which is truncated to the length of the buffer is unusable, so the device
+reports the failure instead of silently returning part of the key.
+\end{note}
+
+For VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY and
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY commands, on success the device
+MUST set \field{key_size} in \field{command_specific_result} to the size of
+the returned key, which MUST be greater than 0, MUST write the returned key
+to the first \field{key_size} bytes of \field{key}, and MUST report the
+length of data written as the used buffer length.
+
+For a VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET command, on success the
+device MUST write the whole struct virtio_blk_crypto_sw_secret, that is
+VIRTIO_BLK_CRYPTO_SW_SECRET_SIZE bytes, to \field{command_specific_result},
+and MUST report the length of data written as the used buffer length.
+
+For a VIRTIO_BLK_ADMIN_CMD_GET_CRYPTO_MODES command, the device MUST set
+\field{modes[N]} for each crypto mode number N that it supports to a
+bitmask of the data unit sizes it supports for that crypto mode, MUST set
+\field{modes[N]} to 0 for each crypto mode number N from 1 to
+VIRTIO_BLK_CRYPTO_MODE_MAX that it does not support, MUST set
+\field{modes[0]} to 0, and MUST NOT set bits 0 to 8 in any
+\field{modes[N]}, that is data unit sizes smaller than 512 bytes. If
+\field{command_specific_result} is shorter than struct
+virtio_blk_crypto_modes, the device MUST write only the entries of
+\field{modes} which fit entirely in \field{command_specific_result}, and
+MUST NOT write part of an entry.
+
+For a VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM command, the device MUST
+complete the command with \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL
+and \field{status_qualifier} set to VIRTIO_ADMIN_STATUS_Q_INVALID_FIELD if
+any of the following is true:
+\begin{itemize}
+\item \field{slot} is not less than \field{max_slots}.
+\item \field{key_size} is 0, or is not a key size that the device supports
+    for \field{crypto_mode} and \field{key_type}.
+\item \field{crypto_mode} is greater than VIRTIO_BLK_CRYPTO_MODE_MAX, or is
+    a crypto mode that the device does not support.
+\item \field{key_type} is neither VIRTIO_BLK_CRYPTO_KEY_TYPE_RAW nor
+    VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED, or is
+    VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED but the device does not support
+    VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED keys.
+\item \field{data_unit_size_bits} does not correspond to a data unit size
+    that the device supports for \field{crypto_mode}.
+\item \field{dun_bytes} is 0, or is greater than \field{max_dun_bytes}.
+\end{itemize}
+
+For a VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT command, the device MUST
+complete the command with \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL
+and \field{status_qualifier} set to VIRTIO_ADMIN_STATUS_Q_INVALID_FIELD if
+\field{slot} is not less than \field{max_slots}, and otherwise MUST
+complete the command with VIRTIO_ADMIN_STATUS_OK, regardless of whether the
+keyslot was already empty. The device MUST ignore all other fields of
+struct virtio_blk_crypto_key_desc for this command.
+
+For VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM and
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT commands, the device MUST leave
+the target keyslot unchanged if the command fails, and MUST apply the
+requested change to the keyslot before completing the command with
+VIRTIO_ADMIN_STATUS_OK.
+
+For a VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY command, the device MUST
+complete the command with a \field{status} other than
+VIRTIO_ADMIN_STATUS_OK if it is unable to generate a key.
+\begin{note}
+The device is not required to report the cause of the failure, which might
+not be known to it. For example, it can use VIRTIO_ADMIN_STATUS_ENOSPC if it
+knows that it lacks the necessary hardware resources.
+\end{note}
+
+For VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY and
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET commands, the device MUST
+complete the command with \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL
+and \field{status_qualifier} set to VIRTIO_ADMIN_STATUS_Q_INVALID_FIELD if
+\field{key_size} in \field{command_specific_data} is 0, or is not a key
+size that the device supports for the command.
+\begin{note}
+The device is not required to check in which form a wrapped key in
+\field{command_specific_data} is. It processes the command with the key
+supplied, and reports failures, for example if it is unable to wrap,
+rewrap or unwrap the key, with a \field{status} other than
+VIRTIO_ADMIN_STATUS_OK.
+\end{note}
+
+If a VIRTIO_BLK_ADMIN_CMD_CRYPTO_GENERATE_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY,
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY or
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET command fails, the device MUST
+NOT write key material or the derived software secret to the
+\field{command_specific_result}.
+
 \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation}
 When using the legacy interface, transitional devices and drivers
 MUST format the fields in struct virtio_blk_req
diff --git a/device-types/blk/device-conformance.tex b/device-types/blk/device-conformance.tex
index b4fbc8b..6b07de4 100644
--- a/device-types/blk/device-conformance.tex
+++ b/device-types/blk/device-conformance.tex
@@ -5,4 +5,5 @@
 \begin{itemize}
 \item \ref{devicenormative:Device Types / Block Device / Device Initialization}
 \item \ref{devicenormative:Device Types / Block Device / Device Operation}
+\item \ref{devicenormative:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands}
 \end{itemize}
diff --git a/device-types/blk/driver-conformance.tex b/device-types/blk/driver-conformance.tex
index 0f69866..0e583cb 100644
--- a/device-types/blk/driver-conformance.tex
+++ b/device-types/blk/driver-conformance.tex
@@ -5,4 +5,5 @@
 \begin{itemize}
 \item \ref{drivernormative:Device Types / Block Device / Device Initialization}
 \item \ref{drivernormative:Device Types / Block Device / Device Operation}
+\item \ref{drivernormative:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands}
 \end{itemize}
-- 
2.34.1

[PATCH v6 3/4] virtio-blk: Add inline encryption request types

[Linlin Zhang]

Keys can now be programmed into keyslots, but the driver has no way
yet to request that the data of a read or write is decrypted or
encrypted with one of them.

Add the VIRTIO_BLK_T_CRYPTO_IN and VIRTIO_BLK_T_CRYPTO_OUT request
types. They behave like VIRTIO_BLK_T_IN and VIRTIO_BLK_T_OUT, except
that the request header is followed by struct virtio_blk_crypto_msg,
which selects the keyslot and gives the 256-bit Data Unit Number (DUN)
of the first data unit of the request. The DUN is incremented by one
for each subsequent data unit.

As struct virtio_blk_crypto_msg is 40 bytes long, the data of these
requests start at offset 56 instead of 16.

Also allow VIRTIO_BLK_REQ_FLAG_OUT_FUA for VIRTIO_BLK_T_CRYPTO_OUT, as
for VIRTIO_BLK_T_OUT.

Driver requirements:
- Requests use a keyslot programmed by a successful KEYSLOT_PROGRAM,
  with no device reset and no other KEYSLOT_PROGRAM or KEYSLOT_EVICT
  for that keyslot made available since it completed, are aligned to
  the data unit size of its key, and use DUNs which fit in the DUN size
  of the key.
- A keyslot is not programmed or evicted while requests using it have
  been made available and not yet used by the device.

Device requirements:
- Requests which do not satisfy the above fail with VIRTIO_BLK_S_IOERR
  without accessing the storage or writing to the data.
- The DUN is incremented by one for each data unit, and a split request
  keeps the data unit alignment and the DUN sequence.
- All keyslots are emptied on device reset, while hardware-wrapped keys
  remain valid.
- The request types are rejected with VIRTIO_BLK_S_UNSUPP unless
  VIRTIO_BLK_F_INLINE_ENCRYPTION has been negotiated.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/238
Signed-off-by: Linlin Zhang <linlin.zhang@oss.qualcomm.com>
---
 device-types/blk/description.tex | 184 +++++++++++++++++++++++++++++--
 1 file changed, 174 insertions(+), 10 deletions(-)

diff --git a/device-types/blk/description.tex b/device-types/blk/description.tex
index b85db2e..bbae9af 100644
--- a/device-types/blk/description.tex
+++ b/device-types/blk/description.tex
@@ -71,7 +71,8 @@ \subsection{Feature bits}\label{sec:Device Types / Block Device / Feature bits}
 
 \item[VIRTIO_BLK_F_REQ_FLAGS_OUT_FUA (19)] Device supports the
     VIRTIO_BLK_REQ_FLAG_OUT_FUA flag in the \field{flags} bitfield of the
-    \field{virtio_blk_req} structure for VIRTIO_BLK_T_OUT requests.
+    \field{virtio_blk_req} structure for VIRTIO_BLK_T_OUT and
+    VIRTIO_BLK_T_CRYPTO_OUT requests.
 
 \item[VIRTIO_BLK_F_INLINE_ENCRYPTION (20)] Device supports inline
     encryption: data written to or read from the device can be encrypted
@@ -393,7 +394,7 @@ \subsection{Device Initialization}\label{sec:Device Types / Block Device / Devic
 \item programming and evicting keys in the block device's keyslots
     through the administration virtqueue.
 \item submitting the keyslot index and Data Unit Number (DUN) per crypto
-    request to the device.
+    request to the device using struct virtio_blk_crypto_msg.
 \end{itemize}
 
 The driver MUST NOT negotiate VIRTIO_BLK_F_INLINE_ENCRYPTION without
@@ -583,8 +584,8 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 value is the bit index in the \field{flags} bitfield):
 
 \begin{description}
-\item[VIRTIO_BLK_REQ_FLAG_OUT_FUA (0) for VIRTIO_BLK_T_OUT requests] Force Unit
-    Access (FUA) flag.
+\item[VIRTIO_BLK_REQ_FLAG_OUT_FUA (0) for VIRTIO_BLK_T_OUT and
+    VIRTIO_BLK_T_CRYPTO_OUT requests] Force Unit Access (FUA) flag.
 \end{description}
 
 The \field{sector} number indicates the offset (multiplied by 512) where
@@ -991,6 +992,71 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 operation by setting the VIRTIO_BLK_S_ZONE_INVALID_CMD value in
 \field{status} of \field{virtio_blk_req} structure.
 
+The following requirements only apply if the VIRTIO_BLK_F_INLINE_ENCRYPTION
+feature is negotiated.
+
+In addition to the request types defined for devices without inline
+encryption support, the type of a request on a request virtqueue can be an
+inline-encrypted read (VIRTIO_BLK_T_CRYPTO_IN) or an inline-encrypted write
+(VIRTIO_BLK_T_CRYPTO_OUT):
+
+\begin{lstlisting}
+#define VIRTIO_BLK_T_CRYPTO_OUT   27
+#define VIRTIO_BLK_T_CRYPTO_IN    28
+\end{lstlisting}
+
+VIRTIO_BLK_T_CRYPTO_IN and VIRTIO_BLK_T_CRYPTO_OUT requests behave the same
+as VIRTIO_BLK_T_IN and VIRTIO_BLK_T_OUT requests respectively, except that
+the data in \field{data} is decrypted (for VIRTIO_BLK_T_CRYPTO_IN) or is to
+be encrypted (for VIRTIO_BLK_T_CRYPTO_OUT) by the inline crypto engine in
+the device backend storage using the key already programmed in the keyslot
+identified by the request, combined with the request's Data Unit
+Number (DUN). For this reason, VIRTIO_BLK_T_CRYPTO_IN and
+VIRTIO_BLK_T_CRYPTO_OUT requests use the following layout, which adds
+\field{crypto_msg} to carry this information:
+
+\begin{lstlisting}
+struct virtio_blk_req_crypto {
+        le32 type;
+        le32 flags;
+        le64 sector;
+        struct virtio_blk_crypto_msg crypto_msg;
+        u8 data[];
+        u8 status;
+};
+\end{lstlisting}
+
+\field{crypto_msg} has the following structure:
+
+\begin{lstlisting}
+struct virtio_blk_crypto_msg {
+        le32 slot;
+        u8 unused4[4];
+        le64 dun[4];
+};
+\end{lstlisting}
+
+\field{slot} is the keyslot index, in the range from 0 to
+\field{max_slots} - 1 of \field{enc_characteristics}. The device backend
+uses the key programmed into this slot together with \field{dun[4]}.
+\field{dun[4]} is a 256-bit unsigned Data Unit Number represented as four
+little-endian 64-bit elements, with \field{dun[0]} as the least-significant
+element. The device increments this 256-bit value by one for each successive
+data unit of the size specified by \field{data_unit_size_bits} in the
+struct virtio_blk_crypto_key_desc, propagating carries from each element to
+the next, while encrypting or decrypting the data of the request. Since
+\field{dun[4]} holds 256 bits, \field{max_dun_bytes} is at most 32.
+\field{unused4} is reserved.
+
+The size of \field{crypto_msg} is 40 bytes, so \field{data} of a
+VIRTIO_BLK_T_CRYPTO_IN or VIRTIO_BLK_T_CRYPTO_OUT request starts at offset
+56 of struct virtio_blk_req_crypto, instead of offset 16 for other request
+types.
+
+The remaining inline-encryption-related operations are group administration
+commands, sent on the administration virtqueue; see
+\ref{sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands}.
+
 \drivernormative{\subsubsection}{Device Operation}{Device Types / Block Device / Device Operation}
 
 The driver SHOULD check if the content of the \field{capacity} field has
@@ -1009,8 +1075,8 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 A driver MUST set \field{sector} to 0 for a VIRTIO_BLK_T_FLUSH request.
 A driver SHOULD NOT include any data in a VIRTIO_BLK_T_FLUSH request.
 
-The length of \field{data} MUST be a multiple of 512 bytes for VIRTIO_BLK_T_IN
-and VIRTIO_BLK_T_OUT requests.
+The length of \field{data} MUST be a multiple of 512 bytes for VIRTIO_BLK_T_IN,
+VIRTIO_BLK_T_OUT, VIRTIO_BLK_T_CRYPTO_IN and VIRTIO_BLK_T_CRYPTO_OUT requests.
 
 The length of \field{data} MUST be a multiple of the size of struct
 virtio_blk_discard_write_zeroes for VIRTIO_BLK_T_DISCARD,
@@ -1089,6 +1155,51 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 
 \end{enumerate}
 
+The following requirements only apply if the VIRTIO_BLK_F_INLINE_ENCRYPTION
+feature is negotiated.
+
+A driver MUST NOT submit a VIRTIO_BLK_T_CRYPTO_IN or VIRTIO_BLK_T_CRYPTO_OUT
+request unless all of the following conditions are satisfied:
+
+\begin{itemize}
+\item \field{slot} identifies a valid keyslot in the range
+    [0, \field{max_slots} - 1].
+
+\item the keyslot identified by \field{slot} has been programmed with the
+    key to use by a VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM command
+    which the device completed with VIRTIO_ADMIN_STATUS_OK, and since
+    that command completed, the device has not been reset and no other
+    VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM or
+    VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT command for that keyslot has
+    been made available.
+
+\item \field{data} is non-empty.
+
+\item (\field{sector} * 512) is aligned to the data unit size of the key
+    programmed in the keyslot identified by \field{slot}.
+
+\item the length of \field{data} is a multiple of the data unit size of
+    the key programmed in the keyslot identified by \field{slot}.
+
+\item the Data Unit Number (DUN) of every data unit covered by the
+    request is representable with the \field{dun_bytes} bytes in
+    struct virtio_blk_crypto_key_desc specified when the key in the
+    keyslot identified by \field{slot} was programmed.
+\end{itemize}
+
+The driver MUST NOT make a VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM or
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_EVICT command available for a keyslot
+while any VIRTIO_BLK_T_CRYPTO_IN or VIRTIO_BLK_T_CRYPTO_OUT request whose
+\field{slot} identifies that keyslot has been made available and not yet
+used by the device.
+
+For a VIRTIO_BLK_T_CRYPTO_IN or VIRTIO_BLK_T_CRYPTO_OUT request,
+\field{dun[4]} MUST specify the 256-bit DUN of the first data unit covered
+by the request.
+
+The driver MUST initialize \field{unused4} in struct virtio_blk_crypto_msg
+to zero.
+
 \devicenormative{\subsubsection}{Device Operation}{Device Types / Block Device / Device Operation}
 
 The device MAY change the content of the \field{capacity} field during
@@ -1135,10 +1246,10 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 
 \item\label{item:flush3} the VIRTIO_BLK_F_REQ_FLAGS_OUT_FUA feature was
   negotiated and the VIRTIO_BLK_REQ_FLAG_OUT_FUA bit in \field{flags} was set in
-  the write request (regardless of whether the VIRTIO_BLK_F_FLUSH or
-  VIRTIO_BLK_F_CONFIG_WCE features were negotiated, and regardless of the
-  current cache mode as expressed by the value of the \field{writeback} field in
-  configuration space).
+  the write request (VIRTIO_BLK_T_OUT or VIRTIO_BLK_T_CRYPTO_OUT, regardless of
+  whether the VIRTIO_BLK_F_FLUSH or VIRTIO_BLK_F_CONFIG_WCE features were
+  negotiated, and regardless of the current cache mode as expressed by the value
+  of the \field{writeback} field in configuration space).
 
 \item\label{item:flush4} a VIRTIO_BLK_T_FLUSH request is sent \textbf{after the write is
   completed} and is completed itself.
@@ -1330,6 +1441,59 @@ \subsection{Device Operation}\label{sec:Device Types / Block Device / Device Ope
 handles VIRTIO_BLK_T_ZONE_RESET request for the zone range specified in the
 VIRTIO_BLK_T_SECURE_ERASE request.
 
+If the VIRTIO_BLK_F_INLINE_ENCRYPTION feature is not negotiated, the device
+MUST reject VIRTIO_BLK_T_CRYPTO_IN and VIRTIO_BLK_T_CRYPTO_OUT requests
+with VIRTIO_BLK_S_UNSUPP status.
+
+The following requirements only apply if the VIRTIO_BLK_F_INLINE_ENCRYPTION
+feature is negotiated.
+
+If a VIRTIO_BLK_T_CRYPTO_IN or VIRTIO_BLK_T_CRYPTO_OUT request satisfies any
+of the following conditions, the device MUST set \field{status} to
+VIRTIO_BLK_S_IOERR, MUST NOT read from or write to the storage, and MUST NOT
+write to \field{data}:
+
+\begin{itemize}
+\item \field{slot} does not identify a valid keyslot.
+
+\item no key is programmed into the keyslot identified by \field{slot}.
+
+\item \field{data} is empty.
+
+\item (\field{sector} * 512) is not aligned to the data unit size of the
+    key programmed in the keyslot identified by \field{slot}.
+
+\item the length of \field{data} is not a multiple of the data unit size
+    of the key programmed in the keyslot identified by \field{slot}.
+
+\item the Data Unit Number (DUN) of any data unit covered by the request
+    is not representable with the \field{dun_bytes} bytes specified when
+    the key in the keyslot identified by \field{slot} was programmed.
+
+\end{itemize}
+
+For encrypted reads and writes, the device MUST use the key programmed in
+the keyslot identified by \field{slot} and the request's \field{dun[4]} as
+the DUN of the first data unit covered by the request, and MUST obtain the
+DUN of each subsequent data unit by incrementing the 256-bit value by one,
+propagating carries from \field{dun[0]} through \field{dun[3]}. If the
+device splits the request, each sub-request MUST preserve data-unit-size
+alignment and use the 256-bit DUN obtained by incrementing the request DUN
+by the number of preceding data units.
+
+On a device reset, the device MUST empty all keyslots, so that no key
+programmed before the reset can be used after it, and MUST NOT invalidate
+the long-term wrapped and ephemerally-wrapped keys it has produced before
+the reset.
+\begin{note}
+The driver therefore has to program the keys again after a device reset
+before submitting VIRTIO_BLK_T_CRYPTO_IN or VIRTIO_BLK_T_CRYPTO_OUT
+requests that use them, but it can reuse the hardware-wrapped keys
+obtained before the reset to do so.
+\end{note}
+
+The device MUST ignore \field{unused4} in struct virtio_blk_crypto_msg.
+
 \subsubsection{Inline Encryption Administration Commands}\label{sec:Device Types / Block Device / Device Operation / Inline Encryption Administration Commands}
 If the VIRTIO_BLK_F_INLINE_ENCRYPTION and VIRTIO_F_ADMIN_VQ features are
 negotiated, the driver uses the administration virtqueue (see
-- 
2.34.1

[PATCH v6 4/4] virtio-blk: Add inline encryption security considerations

[Linlin Zhang]

Inline encryption protects the data stored on the backend storage, but
the device, and therefore the host, is able to read the buffers of both
the request virtqueues and the administration virtqueue.

Describe the resulting exposure. The data of the requests is transferred
in plaintext, so inline encryption is not a means of keeping data
confidential from the host, whichever key type is used, and confidential
guests cannot rely on it for that.

A raw key programmed into a keyslot is visible to the host. A
hardware-wrapped key prevents the raw key from being extracted, so that
the key can only be used through the device which wrapped it, but does
not prevent the host, which is able to send administration commands
itself, from using the key through the device.
The raw key imported by VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY and the
software secret returned by VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET
are also visible to the host.

This patch adds no normative requirements.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/238
Signed-off-by: Linlin Zhang <linlin.zhang@oss.qualcomm.com>
---
 device-types/blk/description.tex | 40 ++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/device-types/blk/description.tex b/device-types/blk/description.tex
index bbae9af..ca54e50 100644
--- a/device-types/blk/description.tex
+++ b/device-types/blk/description.tex
@@ -1994,6 +1994,46 @@ \subsubsection{Inline Encryption Administration Commands}\label{sec:Device Types
 NOT write key material or the derived software secret to the
 \field{command_specific_result}.
 
+\subsubsection{Inline Encryption Security Considerations}\label{sec:Device Types / Block Device / Device Operation / Inline Encryption Security Considerations}
+
+Inline encryption protects the data stored on the backend storage, for
+example against an attacker who obtains the storage medium on its own. It
+is not a means of keeping data confidential from the host: the device, and
+therefore the host, is able to read the buffers of both the request
+virtqueues and the administration virtqueue. A confidential guest, for
+example a guest whose memory is protected from the host by a confidential
+computing technology, cannot rely on inline encryption to keep its data
+confidential from the host, whichever key type it uses.
+
+\begin{note}
+Inline encryption does not protect the data of VIRTIO_BLK_T_CRYPTO_OUT and
+VIRTIO_BLK_T_CRYPTO_IN requests from the host: that data is transferred in
+plaintext in buffers of the request virtqueues.
+\end{note}
+
+When \field{key_type} is VIRTIO_BLK_CRYPTO_KEY_TYPE_RAW, the key material in
+the \field{bytes} of struct virtio_blk_crypto_key_desc of a
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM command is the plaintext key.
+Any software able to access the buffers of the administration virtqueue,
+such as the hypervisor, the device implementation or other software on the
+host, can therefore obtain the key, and decrypt the data encrypted with it
+at any time, including after the key is no longer in use.
+
+When \field{key_type} is VIRTIO_BLK_CRYPTO_KEY_TYPE_HW_WRAPPED, a
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_KEYSLOT_PROGRAM command only transfers a key
+wrapped by the device, and the raw key material is not exposed in its
+buffers. This prevents the raw key from being extracted, so that the key
+can only be used through the device which wrapped it. It does not prevent
+the host, which is able to send administration commands itself, from using
+the key through the device, for example by converting a long-term wrapped
+key it has observed with VIRTIO_BLK_ADMIN_CMD_CRYPTO_PREPARE_KEY and
+programming the result into a keyslot. Moreover, a
+VIRTIO_BLK_ADMIN_CMD_CRYPTO_IMPORT_KEY command carries the raw key in its
+\field{command_specific_data}, and the struct virtio_blk_crypto_sw_secret
+returned by a VIRTIO_BLK_ADMIN_CMD_CRYPTO_DERIVE_SW_SECRET command is
+visible in its \field{command_specific_result}, so these commands expose
+secrets to the host in the same way as raw keys.
+
 \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation}
 When using the legacy interface, transitional devices and drivers
 MUST format the fields in struct virtio_blk_req
-- 
2.34.1