[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH v18 1/2] virtio-crypto: Add virtio crypto device spe
|
From: |
Gonglei |
|
Subject: |
[Qemu-devel] [PATCH v18 1/2] virtio-crypto: Add virtio crypto device specification |
|
Date: |
Sat, 22 Apr 2017 14:23:50 +0800 |
The virtio crypto device is a virtual crypto device (ie. hardware
crypto accelerator card). Currently, the virtio crypto device provides
the following crypto services: CIPHER, MAC, HASH, and AEAD.
In this patch, CIPHER, MAC, HASH, AEAD services are introduced.
VIRTIO-153
Signed-off-by: Gonglei <address@hidden>
CC: Michael S. Tsirkin <address@hidden>
CC: Cornelia Huck <address@hidden>
CC: Stefan Hajnoczi <address@hidden>
CC: Lingli Deng <address@hidden>
CC: Jani Kokkonen <address@hidden>
CC: Ola Liljedahl <address@hidden>
CC: Varun Sethi <address@hidden>
CC: Zeng Xin <address@hidden>
CC: Keating Brian <address@hidden>
CC: Ma Liang J <address@hidden>
CC: Griffin John <address@hidden>
CC: Mihai Claudiu Caraman <address@hidden>
CC: Halil Pasic <address@hidden>
---
acknowledgements.tex | 2 +
content.tex | 2 +
virtio-crypto.tex | 1309 ++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 1313 insertions(+)
create mode 100644 virtio-crypto.tex
diff --git a/acknowledgements.tex b/acknowledgements.tex
index 53942b0..43b8a9b 100644
--- a/acknowledgements.tex
+++ b/acknowledgements.tex
@@ -26,6 +26,7 @@ Sasha Levin, Oracle \newline
Sergey Tverdyshev, Thales e-Security \newline
Stefan Hajnoczi, Red Hat \newline
Tom Lyon, Samya Systems, Inc. \newline
+Lei Gong, Huawei \newline
\end{oasistitlesection}
The following non-members have provided valuable feedback on this
@@ -44,4 +45,5 @@ Patrick Durusau, Technical Advisory Board, OASIS \newline
Thomas Huth, Red Hat \newline
Yan Vugenfirer, Red Hat / Daynix \newline
Kevin Lo, MSI \newline
+Halil Pasic, IBM \newline
\end{oasistitlesection}
diff --git a/content.tex b/content.tex
index 4b45678..ab75f78 100644
--- a/content.tex
+++ b/content.tex
@@ -5750,6 +5750,8 @@ descriptor for the \field{sense_len}, \field{residual},
\field{status_qualifier}, \field{status}, \field{response} and
\field{sense} fields.
+\input{virtio-crypto.tex}
+
\chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
Currently there are three device-independent feature bits defined:
diff --git a/virtio-crypto.tex b/virtio-crypto.tex
new file mode 100644
index 0000000..2708023
--- /dev/null
+++ b/virtio-crypto.tex
@@ -0,0 +1,1309 @@
+\section{Crypto Device}\label{sec:Device Types / Crypto Device}
+
+The virtio crypto device is a virtual cryptography device as well as a kind of
+virtual hardware accelerator for virtual machines. The encryption and
+decryption requests are placed in any of the data queues and are ultimately
handled by the
+backend crypto accelerators. The second kind of queue is the control queue
used to create
+or destroy sessions for symmetric algorithms and will control some advanced
+features in the future. The virtio crypto device provides the following crypto
+services: CIPHER, MAC, HASH, and AEAD.
+
+
+\subsection{Device ID}\label{sec:Device Types / Crypto Device / Device ID}
+
+20
+
+\subsection{Virtqueues}\label{sec:Device Types / Crypto Device / Virtqueues}
+
+\begin{description}
+\item[0] dataq1
+\item[\ldots]
+\item[N-1] dataqN
+\item[N] controlq
+\end{description}
+
+N is set by \field{max_dataqueues}.
+
+\subsection{Feature bits}\label{sec:Device Types / Crypto Device / Feature
bits}
+
+VIRTIO_CRYPTO_F_STATELESS_MODE (0) stateless mode is available.
+VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE (1) stateless mode is available for
CIPHER service.
+VIRTIO_CRYPTO_F_HASH_STATELESS_MODE (2) stateless mode is available for HASH
service.
+VIRTIO_CRYPTO_F_MAC_STATELESS_MODE (3) stateless mode is available for MAC
service.
+VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE (4) stateless mode is available for AEAD
service.
+
+\subsubsection{Feature bit requirements}\label{sec:Device Types / Crypto
Device / Feature bits}
+
+Some crypto feature bits require other crypto feature bits
+(see \ref{drivernormative:Basic Facilities of a Virtio Device / Feature Bits}):
+
+\begin{description}
+\item[VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE] Requires
VIRTIO_CRYPTO_F_STATELESS_MODE.
+\item[VIRTIO_CRYPTO_F_HASH_STATELESS_MODE] Requires
VIRTIO_CRYPTO_F_STATELESS_MODE.
+\item[VIRTIO_CRYPTO_F_MAC_STATELESS_MODE] Requires
VIRTIO_CRYPTO_F_STATELESS_MODE.
+\item[VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE] Requires
VIRTIO_CRYPTO_F_STATELESS_MODE.
+\end{description}
+
+\subsection{Supported crypto services}\label{sec:Device Types / Crypto Device
/ Supported crypto services}
+
+The virtio crypto device provides the following crypto services: CIPHER, MAC,
HASH, and AEAD.
+
+\begin{lstlisting}
+/* CIPHER service */
+#define VIRTIO_CRYPTO_SERVICE_CIPHER 0
+/* HASH service */
+#define VIRTIO_CRYPTO_SERVICE_HASH 1
+/* MAC (Message Authentication Codes) service */
+#define VIRTIO_CRYPTO_SERVICE_MAC 2
+/* AEAD (Authenticated Encryption with Associated Data) service */
+#define VIRTIO_CRYPTO_SERVICE_AEAD 3
+\end{lstlisting}
+
+The above constants are bit numbers, which tell the driver which crypto
services
+are supported by the device, see \ref{sec:Device Types / Crypto Device /
Device configuration layout}.
+
+\subsubsection{CIPHER services}\label{sec:Device Types / Crypto Device /
Supported crypto services / CIPHER services}
+
+The following CIPHER algorithms are defined:
+
+\begin{lstlisting}
+#define VIRTIO_CRYPTO_NO_CIPHER 0
+#define VIRTIO_CRYPTO_CIPHER_ARC4 1
+#define VIRTIO_CRYPTO_CIPHER_AES_ECB 2
+#define VIRTIO_CRYPTO_CIPHER_AES_CBC 3
+#define VIRTIO_CRYPTO_CIPHER_AES_CTR 4
+#define VIRTIO_CRYPTO_CIPHER_DES_ECB 5
+#define VIRTIO_CRYPTO_CIPHER_DES_CBC 6
+#define VIRTIO_CRYPTO_CIPHER_3DES_ECB 7
+#define VIRTIO_CRYPTO_CIPHER_3DES_CBC 8
+#define VIRTIO_CRYPTO_CIPHER_3DES_CTR 9
+#define VIRTIO_CRYPTO_CIPHER_KASUMI_F8 10
+#define VIRTIO_CRYPTO_CIPHER_SNOW3G_UEA2 11
+#define VIRTIO_CRYPTO_CIPHER_AES_F8 12
+#define VIRTIO_CRYPTO_CIPHER_AES_XTS 13
+#define VIRTIO_CRYPTO_CIPHER_ZUC_EEA3 14
+\end{lstlisting}
+
+The above constants have two usages:
+\begin{enumerate}
+\item As bit numbers, used to tell the driver which CIPHER algorithms
+are supported by the device, see \ref{sec:Device Types / Crypto Device /
Device configuration layout}.
+\item As values, used to tell the device which CIPHER algorithm
+a crypto request from the driver requires, see \ref{sec:Device Types / Crypto
Device / Device Operation / Control Virtqueue / Session operation}.
+\end{enumerate}
+
+\subsubsection{HASH services}\label{sec:Device Types / Crypto Device /
Supported crypto services / HASH services}
+
+The following HASH algorithms are defined:
+
+\begin{lstlisting}
+#define VIRTIO_CRYPTO_NO_HASH 0
+#define VIRTIO_CRYPTO_HASH_MD5 1
+#define VIRTIO_CRYPTO_HASH_SHA1 2
+#define VIRTIO_CRYPTO_HASH_SHA_224 3
+#define VIRTIO_CRYPTO_HASH_SHA_256 4
+#define VIRTIO_CRYPTO_HASH_SHA_384 5
+#define VIRTIO_CRYPTO_HASH_SHA_512 6
+#define VIRTIO_CRYPTO_HASH_SHA3_224 7
+#define VIRTIO_CRYPTO_HASH_SHA3_256 8
+#define VIRTIO_CRYPTO_HASH_SHA3_384 9
+#define VIRTIO_CRYPTO_HASH_SHA3_512 10
+#define VIRTIO_CRYPTO_HASH_SHA3_SHAKE128 11
+#define VIRTIO_CRYPTO_HASH_SHA3_SHAKE256 12
+\end{lstlisting}
+
+The above constants have two usages:
+\begin{enumerate}
+\item As bit numbers, used to tell the driver which HASH algorithms
+are supported by the device, see \ref{sec:Device Types / Crypto Device /
Device configuration layout}.
+\item As values, used to tell the device which HASH algorithm
+a crypto request from the driver requires, see \ref{sec:Device Types / Crypto
Device / Device Operation / Control Virtqueue / Session operation}.
+\end{enumerate}
+
+\subsubsection{MAC services}\label{sec:Device Types / Crypto Device /
Supported crypto services / MAC services}
+
+The following MAC algorithms are defined:
+
+\begin{lstlisting}
+#define VIRTIO_CRYPTO_NO_MAC 0
+#define VIRTIO_CRYPTO_MAC_HMAC_MD5 1
+#define VIRTIO_CRYPTO_MAC_HMAC_SHA1 2
+#define VIRTIO_CRYPTO_MAC_HMAC_SHA_224 3
+#define VIRTIO_CRYPTO_MAC_HMAC_SHA_256 4
+#define VIRTIO_CRYPTO_MAC_HMAC_SHA_384 5
+#define VIRTIO_CRYPTO_MAC_HMAC_SHA_512 6
+#define VIRTIO_CRYPTO_MAC_CMAC_3DES 25
+#define VIRTIO_CRYPTO_MAC_CMAC_AES 26
+#define VIRTIO_CRYPTO_MAC_KASUMI_F9 27
+#define VIRTIO_CRYPTO_MAC_SNOW3G_UIA2 28
+#define VIRTIO_CRYPTO_MAC_GMAC_AES 41
+#define VIRTIO_CRYPTO_MAC_GMAC_TWOFISH 42
+#define VIRTIO_CRYPTO_MAC_CBCMAC_AES 49
+#define VIRTIO_CRYPTO_MAC_CBCMAC_KASUMI_F9 50
+#define VIRTIO_CRYPTO_MAC_XCBC_AES 53
+#define VIRTIO_CRYPTO_MAC_ZUC_EIA3 54
+\end{lstlisting}
+
+The above constants have two usages:
+\begin{enumerate}
+\item As bit numbers, used to tell the driver which MAC algorithms
+are supported by the device, see \ref{sec:Device Types / Crypto Device /
Device configuration layout}.
+\item As values, used to tell the device which MAC algorithm
+a crypto request from the driver requires, see \ref{sec:Device Types / Crypto
Device / Device Operation / Control Virtqueue / Session operation}.
+\end{enumerate}
+
+\subsubsection{AEAD services}\label{sec:Device Types / Crypto Device /
Supported crypto services / AEAD services}
+
+The following AEAD algorithms are defined:
+
+\begin{lstlisting}
+#define VIRTIO_CRYPTO_NO_AEAD 0
+#define VIRTIO_CRYPTO_AEAD_GCM 1
+#define VIRTIO_CRYPTO_AEAD_CCM 2
+#define VIRTIO_CRYPTO_AEAD_CHACHA20_POLY1305 3
+\end{lstlisting}
+
+The above constants have two usages:
+\begin{enumerate}
+\item As bit numbers, used to tell the driver which AEAD algorithms
+are supported by the device, see \ref{sec:Device Types / Crypto Device /
Device configuration layout}.
+\item As values, used to tell the device what AEAD algorithm
+a crypto request from the driver requires, see \ref{sec:Device Types / Crypto
Device / Device Operation / Control Virtqueue / Session operation}.
+\end{enumerate}
+
+\subsection{Device configuration layout}\label{sec:Device Types / Crypto
Device / Device configuration layout}
+
+\begin{lstlisting}
+struct virtio_crypto_config {
+ le32 status;
+ le32 max_dataqueues;
+ le32 crypto_services;
+ /* Detailed algorithms mask */
+ le32 cipher_algo_l;
+ le32 cipher_algo_h;
+ le32 hash_algo;
+ le32 mac_algo_l;
+ le32 mac_algo_h;
+ le32 aead_algo;
+ /* Maximum length of cipher key in bytes */
+ le32 max_cipher_key_len;
+ /* Maximum length of authenticated key in bytes */
+ le32 max_auth_key_len;
+ le32 reserved;
+ /* Maximum size of each crypto request's content in bytes */
+ le64 max_size;
+};
+\end{lstlisting}
+
+\begin{description}
+\item[\field{status}] is used to show whether the device is ready to work or
not, it can be either zero or have one or more flags
+ Only one read-only bit (for the driver) is currently defined for the
\field{status} field: VIRTIO_CRYPTO_S_HW_READY:
+\begin{lstlisting}
+#define VIRTIO_CRYPTO_S_HW_READY (1 << 0)
+\end{lstlisting}
+
+\item[\field{max_dataqueues}] is the maximum number of data virtqueues exposed
by
+ the device. The driver MAY use only one data queue,
+ or it can use more to achieve better performance.
+
+\item[\field{crypto_services}] is a 32-bit mask which indicates the crypto
services supported by
+ the device, see \ref{sec:Device Types / Crypto Device / Supported crypto
services}.
+
+\item[\field{cipher_algo_l}] is the low 32-bit mask which indicates the CIPHER
algorithms supported by
+ the device, see \ref{sec:Device Types / Crypto Device / Supported crypto
services / CIPHER services}.
+
+\item[\field{cipher_algo_h}] is the high 32-bit mask which indicates the
CIPHER algorithms supported by
+ the device, see \ref{sec:Device Types / Crypto Device / Supported crypto
services / CIPHER services}.
+
+\item[\field{hash_algo}] is a 32-bit mask which indicates the HASH algorithms
supported by
+ the device, see \ref{sec:Device Types / Crypto Device / Supported crypto
services / HASH services}.
+
+\item[\field{mac_algo_l}] is the low 32-bit mask which indicates the MAC
algorithms supported by
+ the device, see \ref{sec:Device Types / Crypto Device / Supported crypto
services / MAC services}.
+
+\item[\field{mac_algo_h}] is the high 32-bit mask which indicates the MAC
algorithms supported by
+ the device, see \ref{sec:Device Types / Crypto Device / Supported crypto
services / MAC services}.
+
+\item[\field{aead_algo}] is a 32-bit mask which indicates the AEAD algorithms
supported by
+ the device, see \ref{sec:Device Types / Crypto Device / Supported crypto
services / AEAD services}.
+
+\item[\field{max_cipher_key_len}] is the maximum length of cipher key
supported by the device.
+
+\item[\field{max_auth_key_len}] is the maximum length of authenticated key
supported by the device.
+
+\item[\field{reserved}] is reserved for future use.
+
+\item[\field{max_size}] is the maximum size of each crypto request's content
supported by the device
+\end{description}
+
+\begin{note}
+Unless explicitly stated otherwise all lengths and sizes are in bytes.
+\end{note}
+
+\devicenormative{\subsubsection}{Device configuration layout}{Device Types /
Crypto Device / Device configuration layout}
+
+\begin{itemize*}
+\item The device MUST set \field{max_dataqueues} to between 1 and 65535
inclusive.
+\item The device MUST set \field{status} based on the status of the backend
crypto accelerator.
+\item The device MUST accept and handle requests after \field{status} is set
to VIRTIO_CRYPTO_S_HW_READY.
+\item The device MUST set \field{crypto_services} based on the crypto services
the device offers.
+\item The device MUST set detailed algorithms masks based on the
\field{crypto_services} field.
+\item The device MUST set \field{max_size} to show the maximum size of crypto
request the device supports.
+\item The device MUST set \field{max_cipher_key_len} to show the maximum
length of cipher key if the device supports CIPHER service.
+\item The device MUST set \field{max_auth_key_len} to show the maximum length
of authenticated key if the device supports MAC service.
+\end{itemize*}
+
+\drivernormative{\subsubsection}{Device configuration layout}{Device Types /
Crypto Device / Device configuration layout}
+
+\begin{itemize*}
+\item The driver MUST read the ready \field{status} from the bottom bit of
status to check whether the backend crypto accelerator
+ is ready or not, and the driver MUST reread it after device reset.
+\item The driver MUST NOT transmit any requests to the device if the ready
\field{status} is not set.
+\item The driver MUST read \field{max_dataqueues} field to discover the number
of data queues the device supports.
+\item The driver MUST read \field{crypto_services} field to discover which
services the device is able to offer.
+\item The driver MUST read the detailed algorithms fields based on
\field{crypto_services} field.
+\item The driver SHOULD read \field{max_size} to discover the maximum size of
crypto request the device supports.
+\item The driver SHOULD read \field{max_cipher_key_len} to discover the
maximum length of cipher key the device supports.
+\item The driver SHOULD read \field{max_auth_key_len} to discover the maximum
length of authenticated key the device supports.
+\end{itemize*}
+
+\subsection{Device Initialization}\label{sec:Device Types / Crypto Device /
Device Initialization}
+
+\drivernormative{\subsubsection}{Device Initialization}{Device Types / Crypto
Device / Device Initialization}
+
+\begin{itemize*}
+\item The driver MUST identify and initialize all virtqueues.
+\item The driver MUST read the supported crypto services from bits of
\field{crypto_services}.
+\item The driver MUST read the supported algorithms based on
\field{crypto_services} field.
+\end{itemize*}
+
+\subsection{Device Operation}\label{sec:Device Types / Crypto Device / Device
Operation}
+
+Requests can be transmitted by placing them in the controlq or dataq.
+Requests consist of a queue-type specific header specifying among
+others the operation, and an operation specific payload.
+The payload is generally composed of operation parameters, output data, and
input data.
+Operation parameters are algorithm-specific parameters, output data is the
+data that should be utilized in operations, and input data is equal to
+"operation result + result data".
+
+The device can support both session mode (See \ref{sec:Device Types / Crypto
Device / Device Operation / Control Virtqueue / Session operation}) and
stateless mode.
+If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is negotiated, the driver can use
stateless mode for CIPHER service, otherwise it can only use session mode.
+
+The header for controlq is as follows:
+
+\begin{lstlisting}
+#define VIRTIO_CRYPTO_OPCODE(service, op) (((service) << 8) | (op))
+
+struct virtio_crypto_ctrl_header {
+#define VIRTIO_CRYPTO_CIPHER_CREATE_SESSION \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_CIPHER, 0x02)
+#define VIRTIO_CRYPTO_CIPHER_DESTROY_SESSION \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_CIPHER, 0x03)
+#define VIRTIO_CRYPTO_HASH_CREATE_SESSION \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_HASH, 0x02)
+#define VIRTIO_CRYPTO_HASH_DESTROY_SESSION \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_HASH, 0x03)
+#define VIRTIO_CRYPTO_MAC_CREATE_SESSION \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_MAC, 0x02)
+#define VIRTIO_CRYPTO_MAC_DESTROY_SESSION \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_MAC, 0x03)
+#define VIRTIO_CRYPTO_AEAD_CREATE_SESSION \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_AEAD, 0x02)
+#define VIRTIO_CRYPTO_AEAD_DESTROY_SESSION \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_AEAD, 0x03)
+ le32 opcode;
+ /* algo should be service-specific algorithms */
+ le32 algo;
+ le32 flag;
+ /* data virtqueue id */
+ le32 queue_id;
+};
+\end{lstlisting}
+
+The header for dataq is as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_op_header {
+#define VIRTIO_CRYPTO_CIPHER_ENCRYPT \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_CIPHER, 0x00)
+#define VIRTIO_CRYPTO_CIPHER_DECRYPT \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_CIPHER, 0x01)
+#define VIRTIO_CRYPTO_HASH \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_HASH, 0x00)
+#define VIRTIO_CRYPTO_MAC \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_MAC, 0x00)
+#define VIRTIO_CRYPTO_AEAD_ENCRYPT \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_AEAD, 0x00)
+#define VIRTIO_CRYPTO_AEAD_DECRYPT \
+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_AEAD, 0x01)
+ le32 opcode;
+ /* algo should be service-specific algorithms */
+ le32 algo;
+ le64 session_id;
+#define VIRTIO_CRYPTO_FLAG_STATE_MODE 1
+#define VIRTIO_CRYPTO_FLAG_STATELESS_MODE 2
+ /* control flag to control the request */
+ le32 flag;
+ le32 padding;
+};
+\end{lstlisting}
+
+The device can set the operation status as follows: VIRTIO_CRYPTO_OK: success;
+VIRTIO_CRYPTO_ERR: failure or device error; VIRTIO_CRYPTO_NOTSUPP: not
supported;
+VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto operations.
+
+\begin{lstlisting}
+enum VIRTIO_CRYPTO_STATUS {
+ VIRTIO_CRYPTO_OK = 0,
+ VIRTIO_CRYPTO_ERR = 1,
+ VIRTIO_CRYPTO_BADMSG = 2,
+ VIRTIO_CRYPTO_NOTSUPP = 3,
+ VIRTIO_CRYPTO_INVSESS = 4,
+ VIRTIO_CRYPTO_MAX
+};
+\end{lstlisting}
+
+\subsubsection{Control Virtqueue}\label{sec:Device Types / Crypto Device /
Device Operation / Control Virtqueue}
+
+The driver uses the control virtqueue to send control commands to the
+device, such as session operations (See \ref{sec:Device Types / Crypto Device
/ Device Operation / Control Virtqueue / Session operation}).
+
+Controlq requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_op_ctrl_req {
+ struct virtio_crypto_ctrl_header header;
+
+ union {
+ struct virtio_crypto_sym_create_session_req sym_create_session;
+ struct virtio_crypto_hash_create_session_req hash_create_session;
+ struct virtio_crypto_mac_create_session_req mac_create_session;
+ struct virtio_crypto_aead_create_session_req aead_create_session;
+ struct virtio_crypto_destroy_session_req destroy_session;
+ } u;
+};
+\end{lstlisting}
+
+struct virtio_crypto_op_ctrl_req is the only allowed control request.
+The header is the general header, and the union is of the algorithm-specific
type,
+which is set by the driver. All the properties in the union are shown as
follows.
+
+\paragraph{Session operation}\label{sec:Device Types / Crypto Device / Device
Operation / Control Virtqueue / Session operation}
+
+The symmetric algorithms involve the concept of sessions. A session is a
+handle which describes the cryptographic parameters to be applied to
+a number of buffers. The data within a session handle includes:
+
+\begin{enumerate}
+\item The operation (CIPHER, HASH/MAC or both, and if both, the order in
+ which the algorithms should be applied).
+\item The CIPHER set data, including the CIPHER algorithm and mode,
+ the key and its length, and the direction (encryption or decryption).
+\item The HASH/MAC set data, including the HASH algorithm or MAC algorithm,
+ and hash result length (to allow for truncation).
+\begin{itemize*}
+\item Authenticated mode can refer to MAC, which requires that the key and
+ its length are also specified.
+\item For nested mode, the inner and outer prefix data and length are
specified,
+ as well as the outer HASH algorithm.
+\end{itemize*}
+\end{enumerate}
+
+The following structure stores the result of session creation set by the
device:
+
+\begin{lstlisting}
+struct virtio_crypto_session_input {
+ /* Device-writable part */
+ le64 session_id;
+ le32 status;
+ le32 padding;
+};
+\end{lstlisting}
+
+A request to destroy a session includes the following information:
+
+\begin{lstlisting}
+struct virtio_crypto_destroy_session_req {
+ /* Device-readable part */
+ le64 session_id;
+ /* Device-writable part */
+ le32 status;
+ le32 padding;
+};
+\end{lstlisting}
+
+\subparagraph{Session operation: HASH session}\label{sec:Device Types / Crypto
Device / Device
+Operation / Control Virtqueue / Session operation / Session operation: HASH
session}
+
+HASH session requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_hash_session_para {
+ /* See VIRTIO_CRYPTO_HASH_* above */
+ le32 algo;
+ /* hash result length */
+ le32 hash_result_len;
+};
+struct virtio_crypto_hash_create_session_req {
+ /* Device-readable part */
+ struct virtio_crypto_hash_session_para para;
+ /* Device-writable part */
+ struct virtio_crypto_session_input input;
+};
+\end{lstlisting}
+
+\subparagraph{Session operation: MAC session}\label{sec:Device Types / Crypto
Device / Device
+Operation / Control Virtqueue / Session operation / Session operation: MAC
session}
+
+MAC session requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_mac_session_para {
+ /* See VIRTIO_CRYPTO_MAC_* above */
+ le32 algo;
+ /* hash result length */
+ le32 hash_result_len;
+ /* length of authenticated key */
+ le32 auth_key_len;
+ le32 padding;
+};
+
+struct virtio_crypto_mac_create_session_req {
+ /* Device-readable part */
+ struct virtio_crypto_mac_session_para para;
+ /* The authenticated key */
+ u8 auth_key[auth_key_len];
+
+ /* Device-writable part */
+ struct virtio_crypto_session_input input;
+};
+\end{lstlisting}
+
+\subparagraph{Session operation: Symmetric algorithms
session}\label{sec:Device Types / Crypto Device / Device
+Operation / Control Virtqueue / Session operation / Session operation:
Symmetric algorithms session}
+
+The request of symmetric session includes two parts, CIPHER algorithms and
chain
+algorithms (chaining CIPHER and HASH/MAC).
+
+CIPHER session requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_cipher_session_para {
+ /* See VIRTIO_CRYPTO_CIPHER* above */
+ le32 algo;
+ /* length of key */
+ le32 keylen;
+#define VIRTIO_CRYPTO_OP_ENCRYPT 1
+#define VIRTIO_CRYPTO_OP_DECRYPT 2
+ /* encryption or decryption */
+ le32 op;
+ le32 padding;
+};
+
+struct virtio_crypto_cipher_session_req {
+ /* Device-readable part */
+ struct virtio_crypto_cipher_session_para para;
+ /* The cipher key */
+ u8 cipher_key[keylen];
+
+ /* Device-writable part */
+ struct virtio_crypto_session_input input;
+};
+\end{lstlisting}
+
+Algorithm chaining requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_alg_chain_session_para {
+#define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_HASH_THEN_CIPHER 1
+#define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_CIPHER_THEN_HASH 2
+ le32 alg_chain_order;
+/* Plain hash */
+#define VIRTIO_CRYPTO_SYM_HASH_MODE_PLAIN 1
+/* Authenticated hash (mac) */
+#define VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH 2
+/* Nested hash */
+#define VIRTIO_CRYPTO_SYM_HASH_MODE_NESTED 3
+ le32 hash_mode;
+ struct virtio_crypto_cipher_session_para cipher_param;
+ union {
+ struct virtio_crypto_hash_session_para hash_param;
+ struct virtio_crypto_mac_session_para mac_param;
+ } u;
+ /* length of the additional authenticated data (AAD) in bytes */
+ le32 aad_len;
+ le32 padding;
+};
+
+struct virtio_crypto_alg_chain_session_req {
+ /* Device-readable part */
+ struct virtio_crypto_alg_chain_session_para para;
+ /* The cipher key */
+ u8 cipher_key[keylen];
+ /* The authenticated key */
+ u8 auth_key[auth_key_len];
+
+ /* Device-writable part */
+ struct virtio_crypto_session_input input;
+};
+\end{lstlisting}
+
+Symmetric algorithm requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_sym_create_session_req {
+ union {
+ struct virtio_crypto_cipher_session_req cipher;
+ struct virtio_crypto_alg_chain_session_req chain;
+ } u;
+
+ /* Device-readable part */
+
+/* No operation */
+#define VIRTIO_CRYPTO_SYM_OP_NONE 0
+/* Cipher only operation on the data */
+#define VIRTIO_CRYPTO_SYM_OP_CIPHER 1
+/* Chain any cipher with any hash or mac operation. The order
+ depends on the value of alg_chain_order param */
+#define VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING 2
+ le32 op_type;
+ le32 padding;
+};
+\end{lstlisting}
+
+The driver can set the \field{op_type} field in struct
virtio_crypto_sym_create_session_req as follows: VIRTIO_CRYPTO_SYM_OP_NONE: no
operation;
+VIRTIO_CRYPTO_SYM_OP_CIPHER: Cipher only operation on the data;
VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING: Chain any cipher with any hash or mac
operation.
+
+\subparagraph{Session operation: AEAD session}\label{sec:Device Types / Crypto
Device / Device
+Operation / Control Virtqueue / Session operation / Session operation: AEAD
session}
+
+AEAD session requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_aead_session_para {
+ /* See VIRTIO_CRYPTO_AEAD_* above */
+ le32 algo;
+ /* length of key */
+ le32 key_len;
+ /* Authentication tag length */
+ le32 tag_len;
+ /* The length of the additional authenticated data (AAD) in bytes */
+ le32 aad_len;
+ /* encryption or decryption, See above VIRTIO_CRYPTO_OP_* */
+ le32 op;
+ le32 padding;
+};
+
+struct virtio_crypto_aead_create_session_req {
+ /* Device-readable part */
+ struct virtio_crypto_aead_session_para para;
+ u8 key[key_len];
+
+ /* Device-writeable part */
+ struct virtio_crypto_session_input input;
+};
+\end{lstlisting}
+
+\drivernormative{\subparagraph}{Session operation: create session}{Device
Types / Crypto Device / Device Operation / Control Virtqueue / Session
operation / Session operation: create session}
+
+\begin{itemize*}
+\item The driver MUST set the control general header and corresponding
properties of the union in structure virtio_crypto_op_ctrl_req. See
\ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}.
+\item The driver MUST set the \field{opcode} field based on service type:
CIPHER, HASH, MAC, or AEAD.
+\item The driver MUST set the \field{queue_id} field to show used dataq.
+\end{itemize*}
+
+\devicenormative{\subparagraph}{Session operation: create session}{Device
Types / Crypto Device / Device
+Operation / Control Virtqueue / Session operation / Session operation: create
session}
+
+\begin{itemize*}
+\item The device MUST set the \field{session_id} field to a unique session
identifier when the device finishes processing session creation.
+\item The device MUST set the \field{status} field to one of the values of
enum VIRTIO_CRYPTO_STATUS.
+\end{itemize*}
+
+\drivernormative{\subparagraph}{Session operation: destroy session}{Device
Types / Crypto Device / Device
+Operation / Control Virtqueue / Session operation / Session operation: destroy
session}
+
+\begin{itemize*}
+\item The driver MUST set the \field{opcode} field based on service type:
CIPHER, HASH, MAC, or AEAD.
+\item The driver MUST set the \field{session_id} to a valid value assigned by
the device when the session was created.
+\end{itemize*}
+
+\devicenormative{\subparagraph}{Session operation: destroy session}{Device
Types / Crypto Device / Device
+Operation / Control Virtqueue / Session operation / Session operation: destroy
session}
+
+\begin{itemize*}
+\item The device MUST set the \field{status} field to one of the values of
enum VIRTIO_CRYPTO_STATUS.
+\end{itemize*}
+
+\subsubsection{Data Virtqueue}\label{sec:Device Types / Crypto Device / Device
Operation / Data Virtqueue}
+
+The driver uses the data virtqueue to transmit crypto operation requests to
the device,
+and completes the crypto operations.
+
+Session mode dataq requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_op_data_req {
+ struct virtio_crypto_op_header header;
+
+ union {
+ struct virtio_crypto_sym_data_req sym_req;
+ struct virtio_crypto_hash_data_req hash_req;
+ struct virtio_crypto_mac_data_req mac_req;
+ struct virtio_crypto_aead_data_req aead_req;
+ } u;
+};
+\end{lstlisting}
+
+Dataq requests for both session and stateless modes are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_op_data_req_mux {
+ struct virtio_crypto_op_header header;
+
+ union {
+ struct virtio_crypto_sym_data_req sym_req;
+ struct virtio_crypto_hash_data_req hash_req;
+ struct virtio_crypto_mac_data_req mac_req;
+ struct virtio_crypto_aead_data_req aead_req;
+ struct virtio_crypto_sym_data_req_stateless sym_stateless_req;
+ struct virtio_crypto_hash_data_req_stateless hash_stateless_req;
+ struct virtio_crypto_mac_data_req_stateless mac_stateless_req;
+ struct virtio_crypto_aead_data_req_stateless aead_stateless_req;
+ } u;
+};
+\end{lstlisting}
+
+The header is the general header and the union is of the algorithm-specific
type,
+which is set by the driver. All properties in the union are shown as follows.
+
+There is a unified input header structure for all crypto services.
+
+The structure is defined as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_inhdr {
+ u8 status;
+};
+\end{lstlisting}
+
+\subsubsection{HASH Service Operation}\label{sec:Device Types / Crypto Device
/ Device Operation / HASH Service Operation}
+
+Session mode HASH service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_hash_para {
+ /* length of source data */
+ le32 src_data_len;
+ /* hash result length */
+ le32 hash_result_len;
+};
+
+struct virtio_crypto_hash_data_req {
+ /* Device-readable part */
+ struct virtio_crypto_hash_para para;
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device-writable part */
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+Each data request uses virtio_crypto_hash_data_req structure to store
information
+used to run the HASH operations.
+
+The information includes the hash parameters stored in \field{para}, output
data and input data.
+The output data here includes the source data and the input data includes the
hash result data used to save the results of the HASH operations.
+\field{inhdr} stores the status of executing the HASH operations.
+
+Stateless mode HASH service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_hash_para_statelesss {
+ struct {
+ /* See VIRTIO_CRYPTO_HASH_* above */
+ le32 algo;
+ } sess_para;
+
+ /* length of source data */
+ le32 src_data_len;
+ /* hash result length */
+ le32 hash_result_len;
+ le32 reserved;
+};
+struct virtio_crypto_hash_data_req_stateless {
+ /* Device-readable part */
+ struct virtio_crypto_hash_para_stateless para;
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device-writable part */
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+\drivernormative{\paragraph}{HASH Service Operation}{Device Types / Crypto
Device / Device Operation / HASH Service Operation}
+
+\begin{itemize*}
+\item If the driver uses the session mode, then the driver MUST set
\field{session_id} in struct virtio_crypto_op_header
+ to a valid value assigned by the device when the session was created.
+\item If the VIRTIO_CRYPTO_F_STATELESS_MODE feature bit is negotiated, the
driver MUST use struct virtio_crypto_op_data_req_mux to wrap crypto requests.
Otherwise, the driver MUST use struct virtio_crypto_op_data_req.
+\item If the VIRTIO_CRYPTO_F_HASH_STATELESS_MODE feature bit is negotiated, 1)
if the driver uses the stateless mode, then the driver MUST set the
\field{flag} field in struct virtio_crypto_op_header
+ to VIRTIO_CRYPTO_FLAG_STATELESS_MODE and MUST set the fields in struct
virtio_crypto_hash_para_statelession.sess_para, 2) if the driver uses the
session mode, then the driver MUST set the \field{flag} field in struct
virtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_STATE_MODE.
+\item The driver MUST set \field{opcode} in struct virtio_crypto_op_header to
VIRTIO_CRYPTO_HASH.
+\end{itemize*}
+
+\devicenormative{\paragraph}{HASH Service Operation}{Device Types / Crypto
Device / Device Operation / HASH Service Operation}
+
+\begin{itemize*}
+\item If the VIRTIO_CRYPTO_F_STATELESS_MODE feature bit is negotiated, the
device MUST parse the struct virtio_crypto_op_data_req_mux for crypto requests.
Otherwise, the device MUST parse the struct virtio_crypto_op_data_req.
+\item If the VIRTIO_CRYPTO_F_HASH_STATELESS_MODE feature bit is negotiated,
the device MUST parse \field{flag} field in struct virtio_crypto_op_header in
order to decide which mode the driver uses.
+\item The device MUST copy the results of HASH operations in the hash_result[]
if HASH operations success.
+\item The device MUST set \field{status} in struct virtio_crypto_inhdr to one
of the values of enum VIRTIO_CRYPTO_STATUS.
+\end{itemize*}
+
+\subsubsection{MAC Service Operation}\label{sec:Device Types / Crypto Device /
Device Operation / MAC Service Operation}
+
+Session mode MAC service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_mac_para {
+ struct virtio_crypto_hash_para hash;
+};
+
+struct virtio_crypto_mac_data_req {
+ /* Device-readable part */
+ struct virtio_crypto_mac_para para;
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device-writable part */
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+Each data request uses virtio_crypto_mac_data_req structure to store
information
+used to run the MAC operations.
+
+The information includes the hash parameters stored in \field{para}, output
data and input data.
+The output data here includes the source data and the input data includes the
hash result data used to save the results of the MAC operations.
+\field{inhdr} stores the status of executing the MAC operations.
+
+Stateless mode MAC service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_mac_para_stateless {
+ struct {
+ /* See VIRTIO_CRYPTO_MAC_* above */
+ le32 algo;
+ /* length of authenticated key */
+ le32 auth_key_len;
+ } sess_para;
+
+ /* length of source data */
+ le32 src_data_len;
+ /* hash result length */
+ le32 hash_result_len;
+};
+
+struct virtio_crypto_mac_data_req_stateless {
+ /* Device-readable part */
+ struct virtio_crypto_mac_para_stateless para;
+ /* The authenticated key */
+ u8 auth_key[auth_key_len];
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device-writable part */
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+\drivernormative{\paragraph}{MAC Service Operation}{Device Types / Crypto
Device / Device Operation / MAC Service Operation}
+
+\begin{itemize*}
+\item If the driver uses the session mode, then the driver MUST set
\field{session_id} in struct virtio_crypto_op_header
+ to a valid value assigned by the device when the session was created.
+\item If the VIRTIO_CRYPTO_F_STATELESS_MODE feature bit is negotiated, the
driver MUST use struct virtio_crypto_op_data_req_mux to wrap crypto requests.
Otherwise, the driver MUST use struct virtio_crypto_op_data_req.
+\item If the VIRTIO_CRYPTO_F_MAC_STATELESS_MODE feature bit is negotiated, 1)
if the driver uses the stateless mode, then the driver MUST set the
\field{flag} field in struct virtio_crypto_op_header
+ to VIRTIO_CRYPTO_FLAG_STATELESS_MODE and MUST set the fields in struct
virtio_crypto_mac_para_statelession.sess_para, 2) if the driver uses the
session mode, then the driver MUST set the \field{flag} field in struct
virtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_STATE_MODE.
+\item The driver MUST set \field{opcode} in struct virtio_crypto_op_header to
VIRTIO_CRYPTO_MAC.
+\end{itemize*}
+
+\devicenormative{\paragraph}{MAC Service Operation}{Device Types / Crypto
Device / Device Operation / MAC Service Operation}
+
+\begin{itemize*}
+\item If the VIRTIO_CRYPTO_F_STATELESS_MODE feature bit is negotiated, the
device MUST parse the struct virtio_crypto_op_data_req_mux for crypto requests.
Otherwise, the device MUST parse the struct virtio_crypto_op_data_req.
+\item If the VIRTIO_CRYPTO_F_MAC_STATELESS_MODE feature bit is negotiated, the
device MUST parse \field{flag} field in struct virtio_crypto_op_header in order
to decide which mode the driver uses.
+\item The device MUST copy the results of MAC operations in the hash_result[]
if HASH operations success.
+\item The device MUST set \field{status} in struct virtio_crypto_inhdr to one
of the values of enum VIRTIO_CRYPTO_STATUS.
+\end{itemize*}
+
+\subsubsection{Symmetric algorithms Operation}\label{sec:Device Types / Crypto
Device / Device Operation / Symmetric algorithms Operation}
+
+Session mode CIPHER service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_cipher_para {
+ /*
+ * Byte Length of valid IV/Counter data pointed to by the below iv data.
+ *
+ * For block ciphers in CBC or F8 mode, or for Kasumi in F8 mode, or for
+ * SNOW3G in UEA2 mode, this is the length of the IV (which
+ * must be the same as the block length of the cipher).
+ * For block ciphers in CTR mode, this is the length of the counter
+ * (which must be the same as the block length of the cipher).
+ */
+ le32 iv_len;
+ /* length of source data */
+ le32 src_data_len;
+ /* length of destination data */
+ le32 dst_data_len;
+ le32 padding;
+};
+
+struct virtio_crypto_cipher_data_req {
+ /* Device-readable part */
+ struct virtio_crypto_cipher_para para;
+ /*
+ * Initialization Vector or Counter data.
+ *
+ * For block ciphers in CBC or F8 mode, or for Kasumi in F8 mode, or for
+ * SNOW3G in UEA2 mode, this is the Initialization Vector (IV)
+ * value.
+ * For block ciphers in CTR mode, this is the counter.
+ * For AES-XTS, this is the 128bit tweak, i, from IEEE Std 1619-2007.
+ *
+ * The IV/Counter will be updated after every partial cryptographic
+ * operation.
+ */
+ u8 iv[iv_len];
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device-writable part */
+ /* Destination data */
+ u8 dst_data[dst_data_len];
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+Session mode requests of algorithm chaining are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_alg_chain_data_para {
+ le32 iv_len;
+ /* Length of source data */
+ le32 src_data_len;
+ /* Length of destination data */
+ le32 dst_data_len;
+ /* Starting point for cipher processing in source data */
+ le32 cipher_start_src_offset;
+ /* Length of the source data that the cipher will be computed on */
+ le32 len_to_cipher;
+ /* Starting point for hash processing in source data */
+ le32 hash_start_src_offset;
+ /* Length of the source data that the hash will be computed on */
+ le32 len_to_hash;
+ /* Length of the additional auth data */
+ le32 aad_len;
+ /* Length of the hash result */
+ le32 hash_result_len;
+ le32 reserved;
+};
+
+struct virtio_crypto_alg_chain_data_req {
+ /* Device-readable part */
+ struct virtio_crypto_alg_chain_data_para para;
+ /* Initialization Vector or Counter data */
+ u8 iv[iv_len];
+ /* Source data */
+ u8 src_data[src_data_len];
+ /* Additional authenticated data if exists */
+ u8 aad[aad_len];
+
+ /* Device-writable part */
+ /* Destination data */
+ u8 dst_data[dst_data_len];
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+Session mode requests of symmetric algorithm are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_sym_data_req {
+ union {
+ struct virtio_crypto_cipher_data_req cipher;
+ struct virtio_crypto_alg_chain_data_req chain;
+ } u;
+
+ /* Device-readable part */
+
+ /* See above VIRTIO_CRYPTO_SYM_OP_* */
+ le32 op_type;
+ le32 padding;
+};
+\end{lstlisting}
+
+Each data request uses virtio_crypto_sym_data_req structure to store
information
+used to run the CIPHER operations.
+
+The information includes the cipher parameters stored in \field{para}, output
data and input data.
+In the first virtio_crypto_cipher_para structure, \field{iv_len} specifies the
length of the initialization vector or counter,
+\field{src_data_len} specifies the length of the source data, and
\field{dst_data_len} specifies the
+length of the destination data.
+For plain CIPHER operations, the output data here includes the IV/Counter data
and source data, and the input data includes the destination data used to save
the results of the CIPHER operations.
+
+For algorithms chain, the output data here includes the IV/Counter data,
source data and additional authenticated data if exists.
+The input data includes both destination data and hash result data used to
store the results of the HASH/MAC operations.
+\field{inhdr} stores the status of executing the crypto operations.
+
+Stateless mode CIPHER service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_cipher_para_stateless {
+ struct {
+ /* See VIRTIO_CRYPTO_CIPHER* above */
+ le32 algo;
+ /* length of key */
+ le32 keylen;
+
+ /* See VIRTIO_CRYPTO_OP_* above */
+ le32 op;
+ } sess_para;
+
+ /*
+ * Byte Length of valid IV/Counter data pointed to by the below iv data.
+ */
+ le32 iv_len;
+ /* length of source data */
+ le32 src_data_len;
+ /* length of destination data */
+ le32 dst_data_len;
+};
+
+struct virtio_crypto_cipher_data_req_stateless {
+ /* Device-readable part */
+ struct virtio_crypto_cipher_para_stateless para;
+ /* The cipher key */
+ u8 cipher_key[keylen];
+
+ /* Initialization Vector or Counter data. */
+ u8 iv[iv_len];
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device-writable part */
+ /* Destination data */
+ u8 dst_data[dst_data_len];
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+Stateless mode requests of algorithm chaining are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_alg_chain_data_para_stateless {
+ struct {
+ /* See VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_* above */
+ le32 alg_chain_order;
+ /* length of the additional authenticated data in bytes */
+ le32 aad_len;
+
+ struct {
+ /* See VIRTIO_CRYPTO_CIPHER* above */
+ le32 algo;
+ /* length of key */
+ le32 keylen;
+ /* See VIRTIO_CRYPTO_OP_* above */
+ le32 op;
+ } cipher;
+
+ struct {
+ /* See VIRTIO_CRYPTO_HASH_* or VIRTIO_CRYPTO_MAC_* above */
+ le32 algo;
+ /* length of authenticated key */
+ le32 auth_key_len;
+ /* See VIRTIO_CRYPTO_SYM_HASH_MODE_* above */
+ le32 hash_mode;
+ } hash;
+ } sess_para;
+
+ le32 iv_len;
+ /* Length of source data */
+ le32 src_data_len;
+ /* Length of destination data */
+ le32 dst_data_len;
+ /* Starting point for cipher processing in source data */
+ le32 cipher_start_src_offset;
+ /* Length of the source data that the cipher will be computed on */
+ le32 len_to_cipher;
+ /* Starting point for hash processing in source data */
+ le32 hash_start_src_offset;
+ /* Length of the source data that the hash will be computed on */
+ le32 len_to_hash;
+ /* Length of the additional auth data */
+ le32 aad_len;
+ /* Length of the hash result */
+ le32 hash_result_len;
+ le32 reserved;
+};
+
+struct virtio_crypto_alg_chain_data_req_stateless {
+ /* Device-readable part */
+ struct virtio_crypto_alg_chain_data_para_stateless para;
+ /* The cipher key */
+ u8 cipher_key[keylen];
+ /* The auth key */
+ u8 auth_key[auth_key_len];
+ /* Initialization Vector or Counter data */
+ u8 iv[iv_len];
+ /* Source data */
+ u8 src_data[src_data_len];
+ /* Additional authenticated data if exists */
+ u8 aad[aad_len];
+
+ /* Device-writable part */
+ /* Destination data */
+ u8 dst_data[dst_data_len];
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+Stateless mode requests of symmetric algorithm are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_sym_data_req_stateless {
+ union {
+ struct virtio_crypto_cipher_data_req_stateless cipher;
+ struct virtio_crypto_alg_chain_data_req_stateless chain;
+ } u;
+
+ /* Device-readable part */
+
+ /* See above VIRTIO_CRYPTO_SYM_OP_* */
+ le32 op_type;
+ le32 padding;
+};
+\end{lstlisting}
+
+\drivernormative{\paragraph}{Symmetric algorithms Operation}{Device Types /
Crypto Device / Device Operation / Symmetric algorithms Operation}
+
+\begin{itemize*}
+\item If the driver uses the session mode, then the driver MUST set
\field{session_id} in struct virtio_crypto_op_header
+ to a valid value assigned by the device when the session was created.
+\item If the VIRTIO_CRYPTO_F_STATELESS_MODE feature bit is negotiated, the
driver MUST use struct virtio_crypto_op_data_req_mux to wrap crypto requests.
Otherwise, the driver MUST use struct virtio_crypto_op_data_req.
+\item If the VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE feature bit is negotiated,
1) if the driver uses the stateless mode, then the driver MUST set the
\field{flag} field in struct virtio_crypto_op_header
+ to VIRTIO_CRYPTO_FLAG_STATELESS_MODE and MUST set the fields in struct
virtio_crypto_cipher_para_statelession.sess_para or struct
virtio_crypto_alg_chain_data_para_stateless.sess_para, 2) if the driver uses
the session mode, then the driver MUST set the \field{flag} field in struct
virtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_STATE_MODE.
+\item The driver MUST set the \field{opcode} field in struct
virtio_crypto_op_header to VIRTIO_CRYPTO_CIPHER_ENCRYPT or
VIRTIO_CRYPTO_CIPHER_DECRYPT.
+\item The driver MUST specify the fields of struct
virtio_crypto_cipher_data_req in struct virtio_crypto_sym_data_req if the
request is based on VIRTIO_CRYPTO_SYM_OP_CIPHER.
+\item The driver MUST specify the fields of both struct
virtio_crypto_cipher_data_req and struct virtio_crypto_mac_data_req in struct
virtio_crypto_sym_data_req if the request
+ is of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING type and in the
VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH mode.
+\end{itemize*}
+
+\devicenormative{\paragraph}{Symmetric algorithms Operation}{Device Types /
Crypto Device / Device Operation / Symmetric algorithms Operation}
+
+\begin{itemize*}
+\item If the VIRTIO_CRYPTO_F_STATELESS_MODE feature bit is negotiated, the
device MUST parse the struct virtio_crypto_op_data_req_mux for crypto requests.
Otherwise, the device MUST parse the struct virtio_crypto_op_data_req.
+\item If the VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE feature bit is negotiated,
the device MUST parse \field{flag} field in struct virtio_crypto_op_header in
order to decide which mode the driver uses.
+\item The device MUST parse the virtio_crypto_sym_data_req based on the
\field{opcode} field in general header.
+\item The device SHOULD only parse fields of struct
virtio_crypto_cipher_data_req in struct virtio_crypto_sym_data_req if the
request is VIRTIO_CRYPTO_SYM_OP_CIPHER type.
+\item The device MUST parse fields of both struct
virtio_crypto_cipher_data_req and struct virtio_crypto_mac_data_req in struct
virtio_crypto_sym_data_req if the request
+ is of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING operation type and in
the VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH mode.
+\item The device MUST copy the result of cryptographic operation in the
dst_data[] in both plain CIPHER mode and algorithms chain mode.
+\item The device MUST check the \field{para}.\field{add_len} is bigger than 0
before parse the additional authenticated data in plain algorithms chain mode.
+\item The device MUST copy the result of HASH/MAC operation in the
hash_result[] is of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING type.
+\item The device MUST set the \field{status} field in struct
virtio_crypto_inhdr to one of the values of enum VIRTIO_CRYPTO_STATUS.
+\end{itemize*}
+
+\paragraph{Steps of Operation}\label{sec:Device Types / Crypto Device / Device
Operation / Symmetric algorithms Operation / Steps of Operation}
+
+\subparagraph{Step1: Create session}\label{sec:Device Types / Crypto Device /
Device Operation / Symmetric algorithms Operation / Steps of Operation / Step1:
Create session on session mode}
+
+\begin{enumerate}
+\item The driver specifies information in struct virtio_crypto_op_ctrl_req,
including the algorithm name, key, keylen etc;
+\item The driver adds the request of session creation into the controlq's
Vring Descriptor Table;
+\item The driver kicks the device;
+\item The device receives the request from controlq;
+\item The device parses information about the request, and determines the
information concerning the backend crypto accelerator;
+\item The device packs information based on the APIs of the backend crypto
accelerator;
+\item The device invokes the session creation APIs of the backend crypto
accelerator to create a session;
+\item The device returns the session id to the driver.
+\end{enumerate}
+
+\subparagraph{Step2: Execute cryptographic operation}\label{sec:Device Types /
Crypto Device / Device Operation / Symmetric algorithms Operation / Steps of
Operation / Step2: Execute cryptographic operation}
+
+\begin{enumerate}
+\item The driver specifies information in struct virtio_crypto_op_data_req,
including struct virtio_crypto_op_header and struct virtio_crypto_sym_data_req,
see \ref{sec:Device Types / Crypto Device / Device
+ Operation / Symmetric algorithms Operation};
+\item The driver adds the request for cryptographic operation into the dataq's
Vring Descriptor Table;
+\item The driver kicks the device (Or the device actively polls the dataq's
Vring Descriptor Table);
+\item The device receives the request from dataq;
+\item The device parses information about the request, and determines the
identification information for the backend crypto accelerator. For example,
converting guest physical addresses to host physical addresses;
+\item The device packs identification information based on the API of the
backend crypto accelerator;
+\item The device invokes the cryptographic APIs of the backend crypto
accelerator;
+\item The backend crypto accelerator executes the cryptographic operation
implicitly;
+\item The device receives the cryptographic results from the backend crypto
accelerator (synchronous or asynchronous);
+\item The device sets the \field{status} in struct virtio_crypto_inhdr;
+\item The device updates and flushes the Used Ring to return the cryptographic
results to the driver;
+\item The device notifies the driver (Or the driver actively polls the dataq's
Used Ring);
+\item The driver saves the cryptographic results.
+\end{enumerate}
+
+\begin{note}
+\begin{itemize*}
+\item For better performance, the device should by preference use vhost scheme
(user space or kernel space)
+ as the backend crypto accelerator in the real production environment.
+\end{itemize*}
+\end{note}
+
+\subsubsection{AEAD Service Operation}\label{sec:Device Types / Crypto Device
/ Device Operation / AEAD Service Operation}
+
+Session mode requests of symmetric algorithm are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_aead_para {
+ /*
+ * Byte Length of valid IV data.
+ *
+ * For GCM mode, this is either 12 (for 96-bit IVs) or 16, in which
+ * case iv points to J0.
+ * For CCM mode, this is the length of the nonce, which can be in the
+ * range 7 to 13 inclusive.
+ */
+ le32 iv_len;
+ /* length of additional auth data */
+ le32 aad_len;
+ /* length of source data */
+ le32 src_data_len;
+ /* length of dst data, this should be at least src_data_len + tag_len */
+ le32 dst_data_len;
+ /* Authentication tag length */
+ le32 tag_len;
+ le32 reserved;
+};
+
+struct virtio_crypto_aead_data_req {
+ /* Device-readable part */
+ struct virtio_crypto_aead_para para;
+ /*
+ * Initialization Vector data.
+ *
+ * For GCM mode, this is either the IV (if the length is 96 bits) or J0
+ * (for other sizes), where J0 is as defined by NIST SP800-38D.
+ * Regardless of the IV length, a full 16 bytes needs to be allocated.
+ * For CCM mode, the first byte is reserved, and the nonce should be
+ * written starting at &iv[1] (to allow space for the implementation
+ * to write in the flags in the first byte). Note that a full 16 bytes
+ * should be allocated, even though the iv_len field will have
+ * a value less than this.
+ *
+ * The IV will be updated after every partial cryptographic operation.
+ */
+ u8 iv[iv_len];
+ /* Source data */
+ u8 src_data[src_data_len];
+ /* Additional authenticated data if exists */
+ u8 aad[aad_len];
+
+ /* Device-writable part */
+ /* Pointer to output data */
+ u8 dst_data[dst_data_len];
+
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+Each data request uses virtio_crypto_aead_data_req structure to store
information
+used to run the AEAD operations.
+
+The information includes the hash parameters stored in \field{para}, output
data and input data.
+In the first virtio_crypto_aead_para structure, \field{iv_len} specifies the
length of the initialization vector. \field{tag_len} specifies the length of
the authentication tag;
+\field{aad_len} specifies the length of additional authentication data,
\field{src_data_len} specifies the
+length of the source data; \field{dst_data_len} specifies the length of the
destination data, which is at least \field{src_data_len} + \field{tag_len}.
+
+The output data here includes the IV/Counter data, source data and additional
authenticated data if exists.
+The input data includes both destination data used to save the results of the
AEAD operations.
+\field{inhdr} stores the status of executing the AEAD operations.
+
+Stateless mode AEAD service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_aead_para_stateless {
+ struct {
+ /* See VIRTIO_CRYPTO_AEAD_* above */
+ le32 algo;
+ /* length of key */
+ le32 key_len;
+ /* encrypt or decrypt, See above VIRTIO_CRYPTO_OP_* */
+ le32 op;
+ } sess_para;
+
+ /* Byte Length of valid IV data. */
+ le32 iv_len;
+ /* Authentication tag length */
+ le32 tag_len;
+ /* length of additional auth data */
+ le32 aad_len;
+ /* length of source data */
+ le32 src_data_len;
+ /* length of dst data, this should be at least src_data_len + tag_len */
+ le32 dst_data_len;
+};
+
+struct virtio_crypto_aead_data_req_stateless {
+ /* Device-readable part */
+ struct virtio_crypto_aead_para_stateless para;
+ /* The cipher key */
+ u8 key[key_len];
+ /* Initialization Vector data. */
+ u8 iv[iv_len];
+ /* Source data */
+ u8 src_data[src_data_len];
+ /* Additional authenticated data if exists */
+ u8 aad[aad_len];
+
+ /* Device-writable part */
+ /* Pointer to output data */
+ u8 dst_data[dst_data_len];
+
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+\drivernormative{\paragraph}{AEAD Service Operation}{Device Types / Crypto
Device / Device Operation / AEAD Service Operation}
+
+\begin{itemize*}
+\item If the driver uses the session mode, then the driver MUST set
\field{session_id} in struct virtio_crypto_op_header
+ to a valid value assigned by the device when the session was created.
+\item If the VIRTIO_CRYPTO_F_STATELESS_MODE feature bit is negotiated, the
driver MUST use struct virtio_crypto_op_data_req_mux to wrap crypto requests.
Otherwise, the driver MUST use struct virtio_crypto_op_data_req.
+\item If the VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE feature bit is negotiated, 1)
if the driver uses the stateless mode, then the driver MUST set the
\field{flag} field in struct virtio_crypto_op_header
+ to VIRTIO_CRYPTO_FLAG_STATELESS_MODE and MUST set the fields in struct
virtio_crypto_aead_para_statelession.sess_para, 2) if the driver uses the
session mode, then the driver MUST set the \field{flag} field in struct
virtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_STATE_MODE.
+\item The driver MUST set the \field{opcode} field in struct
virtio_crypto_op_header to VIRTIO_CRYPTO_AEAD_ENCRYPT or
VIRTIO_CRYPTO_AEAD_DECRYPT.
+\end{itemize*}
+
+\devicenormative{\paragraph}{AEAD Service Operation}{Device Types / Crypto
Device / Device Operation / AEAD Service Operation}
+
+\begin{itemize*}
+\item If the VIRTIO_CRYPTO_F_STATELESS_MODE feature bit is negotiated, the
device MUST parse the struct virtio_crypto_op_data_req_mux for crypto requests.
Otherwise, the device MUST parse the struct virtio_crypto_op_data_req.
+\item If the VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE feature bit is negotiated,
the device MUST parse the virtio_crypto_aead_data_req based on the
\field{opcode} field in general header.
+\item The device MUST copy the result of cryptographic operation in the
dst_data[].
+\item The device MUST copy the authentication tag in the dst_data[] offset the
cipher result.
+\item The device MUST set the \field{status} field in struct
virtio_crypto_inhdr to one of the values of enum VIRTIO_CRYPTO_STATUS.
+\item When the \field{opcode} field is VIRTIO_CRYPTO_AEAD_DECRYPT, the device
MUST verify and return the verification result to the driver, and if the
verification result is incorrect, VIRTIO_CRYPTO_BADMSG (bad message) MUST be
returned to the driver.
+\end{itemize*}
\ No newline at end of file
--
1.7.12.4