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

[Linlin Zhang <linlin.zhang@oss.qualcomm.com>]

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