* [Qemu-devel] [v23 0/2] virtio-crypto: virtio crypto device specification
@ 2017-12-30 9:35 Longpeng(Mike)
2017-12-30 9:35 ` [Qemu-devel] [v23 1/2] virtio-crypto: Add " Longpeng(Mike)
2017-12-30 9:35 ` [virtio-dev] " Longpeng(Mike)
0 siblings, 2 replies; 31+ messages in thread
From: Longpeng(Mike) @ 2017-12-30 9:35 UTC (permalink / raw)
To: qemu-devel, virtio-dev
Cc: luonengjun, mst, cornelia.huck, stefanha, denglingli,
Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, pasic, wangxinxin.wang,
jianjay.zhou, Longpeng(Mike)
This is the specification about the new virtio crypto device.
---
v23 -> v22
- rename MUX_MODE to REVISION_1 [Halil]
- fixed-length paramenters' instead of 'header' and
'variable-length parameters' instead of 'extra parameters' [Halil]
- add guidance about VIRTIO_CRYPTO_FLAG_SESSION_MODE [Halil]
- other fixes. [Longpeng]
v22 -> v21
- fix some typos and grammar fixes [Halil, Stefan]
- reorder names in alphabetical order [Stefan]
- redescribe the date format [Halil]
v21 -> v20
- rename 'queue_id' to 'reserved' [Halil]
- redescribe the format of the structures which using 'union'
in the previous version [Halil]
v20 -> v19
- fix some typos and grammar fixes [Halil]
- make queue_id reserved [Halil]
- remove 'Steps of Operation'
v19 -> v18:
- fix some typos and grammar fixes [Stefan, Halil]
- rename VIRTIO_CRYPTO_F_STATELESS_MODE to VIRTIO_CRYPTO_F_MUX_MODE
- describe the VIRTIO_CRYPTO_STATUS in detial. [Halil]
- refactor and redescribe the controlq/dataq request's format
of mux mode. [Halil]
- other small fixes. [Halil]
v18 -> v17:
- fix many English grammar problems suggested by Stefan, Thanks a lot!
v17 -> v16:
- Some grammar fixes [Stefan, Halil, Michael]
- add a section named "Supported crypto services" in order to explain bit
numbers and valuse clearly. [Halil, Cornelia]
- avoid word reptition [Halil]
- rename non-session mode to stateless mode [Halil]
- change descriptions for all elements in struct virtio_crypto_config [Halil]
- add Halil as a reviewer in the ackonwledgement part, thanks for his work.
- other fixes here and there.
Changes since v15:
- use feature bits for non-session mode in order to keep compatibility with
pre-existing code. [Halil & Michael]
- introduce VIRTIO_CRYPTO_F_ NON_SESSION_MODE feature bit to control all other
non-session mode feature bits.
- fix some typos. [Stefan]
- introduce struct virtio_crypto_op_data_req_mux to support both session
and non-session based crypto operations and keep compatibility with
pre-existing code.
Changes since v14:
- drop VIRTIO_CRYPTO_S_STARTED status [Halil & Cornelia]
- correct a sentence about dataqueue and controlq in the first paragraph.
[Halil]
- change a MAY to MUST about max_dataqueues. [Halil]
- add non-session mode support
a) add four features for different crypto services to identify wheather
support session mode.
b) rewrite some
For pervious versions of virtio crypto spec, Pls see:
[v18]:
https://www.mail-archive.com/qemu-devel@nongnu.org/msg444897.html
[v14]:
https://lists.gnu.org/archive/html/qemu-devel/2016-11/msg02212.html
[v13]:
https://lists.gnu.org/archive/html/qemu-devel/2016-10/msg07348.html
For more information, please see:
http://qemu-project.org/Features/VirtioCrypto
---
Gonglei (2):
virtio-crypto: Add virtio crypto device specification
virtio-crypto: Add conformance clauses
acknowledgements.tex | 4 +
conformance.tex | 29 +
content.tex | 2 +
virtio-crypto.tex | 1525 ++++++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 1560 insertions(+)
create mode 100644 virtio-crypto.tex
--
1.8.3.1
^ permalink raw reply [flat|nested] 31+ messages in thread
* [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
2017-12-30 9:35 [Qemu-devel] [v23 0/2] virtio-crypto: virtio crypto device specification Longpeng(Mike)
@ 2017-12-30 9:35 ` Longpeng(Mike)
2018-01-09 17:05 ` [virtio-dev] " Halil Pasic
2017-12-30 9:35 ` [virtio-dev] " Longpeng(Mike)
1 sibling, 1 reply; 31+ messages in thread
From: Longpeng(Mike) @ 2017-12-30 9:35 UTC (permalink / raw)
To: qemu-devel, virtio-dev
Cc: luonengjun, mst, cornelia.huck, stefanha, denglingli,
Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, pasic, wangxinxin.wang,
jianjay.zhou, Longpeng(Mike)
From: Gonglei <arei.gonglei@huawei.com>
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 <arei.gonglei@huawei.com>
Signed-off-by: Zhoujian <jianjay.zhou@huawei.com>
Signed-off-by: Longpeng(Mike) <longpeng2@huawei.com>
---
acknowledgements.tex | 4 +
content.tex | 2 +
virtio-crypto.tex | 1525 ++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 1531 insertions(+)
create mode 100644 virtio-crypto.tex
diff --git a/acknowledgements.tex b/acknowledgements.tex
index 2d893d9..cdde247 100644
--- a/acknowledgements.tex
+++ b/acknowledgements.tex
@@ -16,10 +16,13 @@ Daniel Kiper, Oracle \newline
Geoff Brown, Machine-to-Machine Intelligence (M2MI) Corporation \newline
Gershon Janssen, Individual Member \newline
James Bottomley, Parallels IP Holdings GmbH \newline
+Jian Zhou, Huawei \newline
+Lei Gong, Huawei \newline
Luiz Capitulino, Red Hat \newline
Michael S. Tsirkin, Red Hat \newline
Paolo Bonzini, Red Hat \newline
Pawel Moll, ARM \newline
+Peng Long, Huawei \newline
Richard Sohn, Alcatel-Lucent \newline
Rusty Russell, IBM \newline
Sasha Levin, Oracle \newline
@@ -38,6 +41,7 @@ Brian Foley, ARM \newline
David Alan Gilbert, Red Hat \newline
Fam Zheng, Red Hat \newline
Gerd Hoffmann, Red Hat \newline
+Halil Pasic, IBM \newline
Jason Wang, Red Hat \newline
Laura Novich, Red Hat \newline
Patrick Durusau, Technical Advisory Board, OASIS \newline
diff --git a/content.tex b/content.tex
index c840588..d1d3b09 100644
--- a/content.tex
+++ b/content.tex
@@ -5819,6 +5819,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 these device-independent feature bits defined:
diff --git a/virtio-crypto.tex b/virtio-crypto.tex
new file mode 100644
index 0000000..4bd5b51
--- /dev/null
+++ b/virtio-crypto.tex
@@ -0,0 +1,1525 @@
+\section{Crypto Device}\label{sec:Device Types / Crypto Device}
+
+The virtio crypto device is a virtual cryptography device as well as a
+virtual cryptographic accelerator. The virtio crypto device provides the
+following crypto services: CIPHER, MAC, HASH, and AEAD. Virtio crypto
+devices have a single control queue and at least one data queue. Crypto
+operation requests are placed into a data queue, and serviced by the
+device. Some crypto operation requests are only valid in the context of a
+session. The role of the control queue is facilitating control operation
+requests. Sessions management is realized with control operation
+requests.
+
+\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}
+
+\begin{description}
+\item VIRTIO_CRYPTO_F_REVISION_1 (0) revision 1. Revision 1 has a specific
+ request format and other enhancements (which result in some additional
+ requirements).
+\item VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE (1) stateless mode requests are
+ supported by the CIPHER service.
+\item VIRTIO_CRYPTO_F_HASH_STATELESS_MODE (2) stateless mode requests are
+ supported by the HASH service.
+\item VIRTIO_CRYPTO_F_MAC_STATELESS_MODE (3) stateless mode requests are
+ supported by the MAC service.
+\item VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE (4) stateless mode requests are
+ supported by the AEAD service.
+\end{description}
+
+
+\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_REVISION_1.
+\item[VIRTIO_CRYPTO_F_HASH_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
+\item[VIRTIO_CRYPTO_F_MAC_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
+\item[VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
+\end{description}
+
+\subsection{Supported crypto services}\label{sec:Device Types / Crypto Device / Supported crypto services}
+
+The following crypto services are defined:
+
+\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 designate bits used to indicate the which of crypto services are
+offered by the device as described in, 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 designate the algorithm in (CIPHER type) crypto
+operation requests, 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 designate the algorithm in (HASH type) crypto
+operation 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 designate the algorithm in (MAC type) crypto
+operation requests, 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 designate the algorithm in (DEAD type) crypto
+operation requests, 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 Currently, only one \field(status) bit is defined: VIRTIO_CRYPTO_S_HW_READY
+ set indicates that the device is ready to process requests, this bit is read-only
+ for the driver
+\begin{lstlisting}
+#define VIRTIO_CRYPTO_S_HW_READY (1 << 0)
+\end{lstlisting}
+
+\item[\field{max_dataqueues}] is the maximum number of data virtqueues that can
+ be configured by the device. The driver MAY use only one data queue, or it
+ can use more to achieve better performance.
+
+\item[\field{crypto_services}] crypto service offered, see \ref{sec:Device Types / Crypto Device / Supported crypto services}.
+
+\item[\field{cipher_algo_l}] CIPHER algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
+
+\item[\field{cipher_algo_h}] CIPHER algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
+
+\item[\field{hash_algo}] HASH algorithms bits, see \ref{sec:Device Types / Crypto Device / Supported crypto services / HASH services}.
+
+\item[\field{mac_algo_l}] MAC algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
+
+\item[\field{mac_algo_h}] MAC algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
+
+\item[\field{aead_algo}] AEAD algorithms bits, 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 the \field{status} with valid flags, undefined flags MUST NOT be set.
+\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 for each service advertised by \field{crypto_services}.
+ The device MUST NOT set the not defined algorithms bits.
+\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 \field{status} from the bottom bit of status to check whether the
+ VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
+\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD ignore the not defined algorithms bits.
+\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 configure 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}
+
+The operation of a virtio crypto device is driven by requests placed on the virtqueues.
+Requests consist of a queue-type specific header (specifying among others the operation)
+and an operation specific payload.
+
+If VIRTIO_CRYPTO_F_REVISION_1 is negotiated the device may support both session mode
+(See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation})
+and stateless mode operation requests.
+In stateless mode all operation parameters are supplied as a part of each request,
+while in session mode, some or all operation parameters are managed within the
+session. Stateless mode is guarded by feature bits 0-4 on a service level. If
+stateless mode is negotiated for a service, the service is available both in
+session and stateless mode; otherwise it's only available in session mode.
+
+\subsubsection{Operation Status}\label{sec:Device Types / Crypto Device / Device Operation / Operation status}
+The device MUST return a status code as part of the operation (both session
+operation and service operation) result. The valid operation status as follows:
+
+\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_NOSPC = 5,
+ VIRTIO_CRYPTO_MAX
+};
+\end{lstlisting}
+
+\begin{itemize*}
+\item VIRTIO_CRYPTO_OK: success.
+\item VIRTIO_CRYPTO_BADMSG: authentication failed (only when AEAD decryption).
+\item VIRTIO_CRYPTO_NOTSUPP: operation or algorithm is unsupported.
+\item VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto operations.
+\item VIRTIO_CRYPTO_NOSPC: no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
+ feature bit is negotiated).
+\item VIRTIO_CRYPTO_ERR: any failure not mentioned above occurs.
+\end{itemize*}
+
+\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}).
+
+The header for controlq is of the following form:
+\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;
+ le32 reserved;
+};
+\end{lstlisting}
+
+The controlq request is composed of four parts:
+\begin{lstlisting}
+struct virtio_crypto_op_ctrl_req {
+ /* Device read only portion */
+
+ struct virtio_crypto_ctrl_header header;
+
+#define VIRTIO_CRYPTO_CTRLQ_OP_SPEC_HDR_LEGACY 56
+ /* fixed length fields, opcode specific */
+ u8 op_flf[flf_len];
+
+ /* variable length fields, opcode specific */
+ u8 op_vlf[vlf_len];
+
+ /* Device write only portion */
+
+ /* op result or completion status */
+ u8 op_outcome[outcome_len];
+};
+\end{lstlisting}
+
+\field{header} is a general header (see above).
+
+\field{op_flf} is the opcode (in \field{header}) specific fixed-length paramenters.
+
+\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit (see below).
+
+\field{op_vlf} is the opcode (in \field{header}) specific variable-length paramenters.
+
+\field{vlf_len} is the size of the specific structure used.
+\begin{note}
+The \field{vlf_len} of session-destroy operation and the hash-session-create
+operation is ZERO.
+\end{note}
+
+\begin{itemize*}
+\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_CREATE_SESSION
+ then \field{op_flf} is struct virtio_crypto_sym_create_session_flf if
+ VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_sym_create_session_flf if
+ padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
+ virtio_crypto_sym_create_session_vlf.
+\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH_CREATE_SESSION
+ then \field{op_flf} is struct virtio_crypto_hash_create_session_flf if
+ VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_hash_create_session_flf if
+ padded to 56 bytes if NOT negotiated.
+\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC_CREATE_SESSION
+ then \field{op_flf} is struct virtio_crypto_mac_create_session_flf if
+ VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_mac_create_session_flf if
+ padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
+ virtio_crypto_mac_create_session_vlf.
+\end{itemize*}
+\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_CREATE_SESSION
+ then \field{op_flf} is struct virtio_crypto_aead_create_session_flf if
+ VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_aead_create_session_flf if
+ padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
+ virtio_crypto_aead_create_session_vlf.
+\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_DESTROY_SESSION
+ or VIRTIO_CRYPTO_HASH_DESTROY_SESSION or VIRTIO_CRYPTO_MAC_DESTROY_SESSION or
+ VIRTIO_CRYPTO_AEAD_DESTROY_SESSION then \field{op_flf} is struct
+ virtio_crypto_destroy_session_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated and
+ struct virtio_crypto_destroy_session_flf if padded to 56 bytes if NOT negotiated.
+\end{itemize*}
+
+\field{op_outcome} stores the result of operation and must be struct
+virtio_crypto_destroy_session_input for session-destroy operation or
+struct virtio_crypto_session_input.
+
+\field{outcome_len} is the size of the structure used.
+
+
+\paragraph{Session operation}\label{sec:Device Types / Crypto Device / Device
+Operation / Control Virtqueue / Session operation}
+
+The session is a handle which describes the cryptographic parameters to be
+applied to a number of buffers.
+
+The following structure stores the result of session creation set by the device:
+
+\begin{lstlisting}
+struct virtio_crypto_session_input {
+ /* Device write only portion */
+ 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_flf {
+ /* Device read only portion */
+ le64 session_id;
+};
+
+struct virtio_crypto_destroy_session_input {
+ /* Device write only portion */
+ 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}
+
+The fixed-length paramenters of HASH session requests is as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_hash_create_session_flf {
+ /* Device read only portion */
+
+ /* See VIRTIO_CRYPTO_HASH_* above */
+ le32 algo;
+ /* hash result length */
+ le32 hash_result_len;
+};
+\end{lstlisting}
+
+
+\subparagraph{Session operation: MAC session}\label{sec:Device Types / Crypto Device / Device
+Operation / Control Virtqueue / Session operation / Session operation: MAC session}
+
+The fixed-length and the variable-length parameters of MAC session requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_mac_create_session_flf {
+ /* Device read only portion */
+
+ /* 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_vlf {
+ /* Device read only portion */
+
+ /* The authenticated key */
+ u8 auth_key[auth_key_len];
+};
+\end{lstlisting}
+
+The length of \field{auth_key} is specified in \field{auth_key_len} in the struct
+virtio_crypto_mac_create_session_flf.
+
+
+\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 could be the CIPHER algorithms request
+or the chain algorithms (chaining CIPHER and HASH/MAC) request.
+
+The fixed-length and the variable-length parameters of CIPHER session requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_cipher_session_flf {
+ /* Device read only portion */
+
+ /* 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_vlf {
+ /* Device read only portion */
+
+ /* The cipher key */
+ u8 cipher_key[keylen];
+};
+\end{lstlisting}
+
+The length of \field{cipher_key} is specified in \field{keylen} in the struct
+virtio_crypto_cipher_session_flf.
+
+The fixed-length and the variable-length parameters of Chain session requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_alg_chain_session_flf {
+ /* Device read only portion */
+
+#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_flf cipher_hdr;
+
+#define VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE 16
+ /* fixed length fields, algo specific */
+ u8 algo_flf[VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE];
+
+ /* length of the additional authenticated data (AAD) in bytes */
+ le32 aad_len;
+ le32 padding;
+};
+
+struct virtio_crypto_alg_chain_session_vlf {
+ /* Device read only portion */
+
+ /* The cipher key */
+ u8 cipher_key[keylen];
+ /* The authenticated key */
+ u8 auth_key[auth_key_len];
+};
+\end{lstlisting}
+
+\field{hash_mode} decides the type used by \field{algo_flf}.
+
+\field{algo_flf} is fixed to 16 bytes and MUST contains or be one of
+the following types:
+\begin{itemize*}
+\item struct virtio_crypto_hash_create_session_flf
+\item struct virtio_crypto_mac_create_session_flf
+\end{itemize*}
+The data of unused part (if has) in \field{algo_flf} will be ignored.
+
+The length of \field{cipher_key} is specified in \field{keylen} in \field{cipher_hdr}.
+
+The length of \field{auth_key} is specified in \field{auth_key_len} in struct
+virtio_crypto_mac_create_session_flf.
+
+The fixed-length parameters of Symmetric session requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_sym_create_session_flf {
+ /* Device read only portion */
+
+#define VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE 48
+ /* fixed length fields, opcode specific */
+ u8 op_flf[VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE];
+
+/* 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}
+
+\field{op_flf} is fixed to 48 bytes, MUST contains or be one of
+the following types:
+\begin{itemize*}
+\item struct virtio_crypto_cipher_session_flf
+\item struct virtio_crypto_alg_chain_session_flf
+\end{itemize*}
+The data of unused part (if has) in \field{op_flf} will be ignored.
+
+\field{op_type} decides the type used by \field{op_flf}.
+
+The variable-length parameters of Symmetric session requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_sym_create_session_vlf {
+ /* Device read only portion */
+ /* variable length fields, opcode specific */
+ u8 op_vlf[vlf_len];
+};
+\end{lstlisting}
+
+\field{op_vlf} MUST contains or be one of the following types:
+\begin{itemize*}
+\item struct virtio_crypto_cipher_session_vlf
+\item struct virtio_crypto_alg_chain_session_vlf
+\end{itemize*}
+
+\field{op_type} in struct virtio_crypto_sym_create_session_flf decides the
+type used by \field{op_vlf}.
+
+\field{vlf_len} is the size of the specific structure used.
+
+
+\subparagraph{Session operation: AEAD session}\label{sec:Device Types / Crypto Device / Device
+Operation / Control Virtqueue / Session operation / Session operation: AEAD session}
+
+The fixed-length and the variable-length parameters of AEAD session requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_aead_create_session_flf {
+ /* Device read only portion */
+
+ /* 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_vlf {
+ /* Device read only portion */
+ u8 key[key_len];
+};
+\end{lstlisting}
+
+The length of \field{key} is specified in \field{key_len} in struct
+virtio_crypto_aead_create_session_flf.
+
+
+\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 \field{opcode} field based on service type: CIPHER, HASH, MAC, or AEAD.
+\item The driver MUST set the control general header, the opcode specific header,
+ the opcode specific extra parameters and the opcode specific outcome buffer in turn.
+ See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}.
+\item The driver MUST set the \field{reversed} field to zero.
+\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 use the corresponding opcode specific structure according to the
+ \field{opcode} in the control general header.
+\item The device MUST extract extra parameters according to the structures used.
+\item The device MUST set the \field{status} field to one of the following values of enum
+ VIRTIO_CRYPTO_STATUS after finish a session creation:
+\begin{itemize*}
+\item VIRTIO_CRYPTO_OK if a session is created successfully.
+\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
+\item VIRTIO_CRYPTO_NOSPC if no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
+ feature bit is negotiated).
+\item VIRTIO_CRYPTO_ERR if failure not mentioned above occurs.
+\end{itemize*}
+\item The device MUST set the \field{session_id} field to a unique session identifier only
+ if the status is set to VIRTIO_CRYPTO_OK.
+\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 following values of enum VIRTIO_CRYPTO_STATUS.
+\begin{itemize*}
+\item VIRTIO_CRYPTO_OK if a session is created successfully.
+\item VIRTIO_CRYPTO_ERR if any failure occurs.
+\end{itemize*}
+\end{itemize*}
+
+
+\subsubsection{Data Virtqueue}\label{sec:Device Types / Crypto Device / Device Operation / Data Virtqueue}
+
+The driver uses the data virtqueues to transmit crypto operation requests to the device,
+and completes the crypto operations.
+
+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_SESSION_MODE 1
+ /* control flag to control the request */
+ le32 flag;
+ le32 padding;
+};
+\end{lstlisting}
+
+\begin{note}
+If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
+is not negotiated then <SERVICE> retuqests with the \field{flag} (in struct
+virtio_crypto_op_header) is ZERO need to be rejected. If VIRTIO_CRYPTO_F_REVISION_1 is
+not negotiated the \field{flag} is ignored.
+\end{note}
+
+The dataq request is composed of four parts:
+\begin{lstlisting}
+struct virtio_crypto_op_data_req {
+ /* Device read only portion */
+
+ struct virtio_crypto_op_header header;
+
+#define VIRTIO_CRYPTO_DATAQ_OP_SPEC_HDR_LEGACY 48
+ /* fixed length fields, opcode specific */
+ u8 op_flf[flf_len];
+
+ /* Device read && write portion */
+ /* variable length fields, opcode specific */
+ u8 op_vlf[vlf_len];
+
+ /* Device write only portion */
+ struct virtio_crypto_inhdr inhdr;
+};
+\end{lstlisting}
+
+\field{header} is a general header (see above).
+
+\field{op_flf} is the opcode (in \field{header}) specific header.
+
+\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit
+(see below).
+
+\field{op_vlf} is the opcode (in \field{header}) specific parameters.
+
+\field{vlf_len} is the size of the specific structure used.
+
+\begin{itemize*}
+\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_ENCRYPT
+ or VIRTIO_CRYPTO_CIPHER_DECRYPT then:
+ \begin{itemize*}
+ \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is negotiated, \field{op_flf} is
+ struct virtio_crypto_sym_data_flf_stateless, and \field{op_vlf} is struct
+ virtio_crypto_sym_data_vlf_stateless.
+ \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is NOT negotiated, \field{op_flf}
+ is struct virtio_crypto_sym_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
+ and struct virtio_crypto_sym_data_flf if padded to 48 bytes if NOT negotiated,
+ and \field{op_vlf} is struct virtio_crypto_sym_data_vlf.
+ \end{itemize*}
+\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH:
+ \begin{itemize*}
+ \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is negotiated, \field{op_flf} is
+ struct virtio_crypto_hash_data_flf_stateless, and \field{op_vlf} is struct
+ virtio_crypto_hash_data_vlf_stateless.
+ \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is NOT negotiated, \field{op_flf}
+ is struct virtio_crypto_hash_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
+ and struct virtio_crypto_hash_data_flf if padded to 48 bytes if NOT negotiated,
+ and \field{op_vlf} is struct virtio_crypto_hash_data_vlf.
+\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC:
+ \begin{itemize*}
+ \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is negotiated, \field{op_flf} is
+ struct virtio_crypto_mac_data_flf_stateless, and \field{op_vlf} is struct
+ virtio_crypto_mac_data_vlf_stateless.
+ \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is NOT negotiated, \field{op_flf}
+ is struct virtio_crypto_mac_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
+ and struct virtio_crypto_mac_data_flf if padded to 48 bytes if NOT negotiated,
+ and \field{op_vlf} is struct virtio_crypto_mac_data_vlf.
+\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_ENCRYPT
+ or VIRTIO_CRYPTO_AEAD_DECRYPT then:
+ \begin{itemize*}
+ \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is negotiated, \field{op_flf} is
+ struct virtio_crypto_aead_data_flf_stateless, and \field{op_vlf} is struct
+ virtio_crypto_aead_data_vlf_stateless.
+ \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is NOT negotiated, \field{op_flf}
+ is struct virtio_crypto_aead_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
+ and struct virtio_crypto_aead_data_flf if padded to 48 bytes if NOT negotiated,
+ and \field{op_vlf} is struct virtio_crypto_aead_data_vlf.
+\end{itemize*}
+
+\field{inhdr} is a unified input header that used to return the status of
+the operations, 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_data_flf {
+ /* length of source data */
+ le32 src_data_len;
+ /* hash result length */
+ le32 hash_result_len;
+};
+
+struct virtio_crypto_hash_data_vlf {
+ /* Device read only portion */
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device write only portion */
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+};
+\end{lstlisting}
+
+Each data request uses the virtio_crypto_hash_data_flf structure and the
+virtio_crypto_hash_data_vlfto structure to store information used to run the
+HASH operations.
+
+\field{src_data} is the source data that will be processed.
+\field{src_data_len} is the length of source data.
+\field{hash_result} is the result data and \field{hash_result_len} is the length
+of it.
+
+Stateless mode HASH service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_hash_data_flf_stateless {
+ 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_vlf_stateless {
+ /* Device read only portion */
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device write only portion */
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+};
+\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_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 ZERO and MUST set the fields in struct
+ virtio_crypto_hash_data_flf_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_SESSION_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 The device MUST use the corresponding structure according to the \field{opcode}
+ in the data general header.
+\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
+ following values of enum VIRTIO_CRYPTO_STATUS:
+\begin{itemize*}
+\item VIRTIO_CRYPTO_OK if the operation success.
+\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
+\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
+\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
+\end{itemize*}
+\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_data_flf {
+ struct virtio_crypto_hash_data_flf hdr;
+};
+
+struct virtio_crypto_mac_data_vlf {
+ /* Device read only portion */
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device write only portion */
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+};
+\end{lstlisting}
+
+Each request uses the virtio_crypto_mac_data_flf structure and the
+virtio_crypto_mac_data_vlf structure to store information used to run the
+MAC operations.
+
+\field{src_data} is the source data that will be processed.
+\field{src_data_len} is the length of source data.
+\field{hash_result} is the result data and \field{hash_result_len} is the length
+of it.
+
+Stateless mode MAC service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_mac_data_flf_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_vlf_stateless {
+ /* Device read only portion */
+ /* The authenticated key */
+ u8 auth_key[auth_key_len];
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device write only portion */
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+};
+\end{lstlisting}
+
+\field{auth_key} is the authenticated key that will be used during the process.
+\field{auth_key_len} is the length of the key.
+
+\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_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 ZERO and MUST set the fields in struct
+ virtio_crypto_mac_data_flf_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_SESSION_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_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
+ following values of enum VIRTIO_CRYPTO_STATUS:
+\begin{itemize*}
+\item VIRTIO_CRYPTO_OK if the operation success.
+\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
+\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
+\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
+\end{itemize*}
+\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_data_flf {
+ /*
+ * 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_vlf {
+ /* Device read only portion */
+
+ /*
+ * 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 write only portion */
+ /* Destination data */
+ u8 dst_data[dst_data_len];
+};
+\end{lstlisting}
+
+Session mode requests of algorithm chaining are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_alg_chain_data_flf {
+ 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_vlf {
+ /* Device read only portion */
+
+ /* 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 write only portion */
+
+ /* Destination data */
+ u8 dst_data[dst_data_len];
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+};
+\end{lstlisting}
+
+Session mode requests of symmetric algorithm are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_sym_data_flf {
+ /* Device read only portion */
+
+#define VIRTIO_CRYPTO_SYM_DATA_REQ_HDR_SIZE 40
+ u8 op_type_flf[VIRTIO_CRYPTO_SYM_DATA_REQ_HDR_SIZE];
+
+ /* See above VIRTIO_CRYPTO_SYM_OP_* */
+ le32 op_type;
+ le32 padding;
+};
+
+struct virtio_crypto_sym_data_vlf {
+ u8 op_type_vlf[sym_para_len];
+};
+\end{lstlisting}
+
+Each request uses the virtio_crypto_sym_data_flf structure and the
+virtio_crypto_sym_data_flf structure to store information used to run the
+CIPHER operations.
+
+\field{op_type_flf} is the \field{op_type} specific header, it MUST starts
+with or be one of the following structures:
+\begin{itemize*}
+\item struct virtio_crypto_cipher_data_flf
+\item struct virtio_crypto_alg_chain_data_flf
+\end{itemize*}
+
+The length of \field{op_type_flf} is fixed to 40 bytes, the data of unused
+part (if has) will be ingored.
+
+\field{op_type_vlf} is the \field{op_type} specific parameters, it MUST starts
+with or be one of the following structures:
+\begin{itemize*}
+\item struct virtio_crypto_cipher_data_vlf
+\item struct virtio_crypto_alg_chain_data_vlf
+\end{itemize*}
+
+\field{sym_para_len} is the size of the specific structure used.
+
+Stateless mode CIPHER service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_cipher_data_flf_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_vlf_stateless {
+ /* Device read only portion */
+
+ /* 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 write only portion */
+ /* Destination data */
+ u8 dst_data[dst_data_len];
+};
+\end{lstlisting}
+
+Stateless mode requests of algorithm chaining are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_alg_chain_data_flf_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_vlf_stateless {
+ /* Device read only portion */
+
+ /* 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];
+ /* Additional authenticated data if exists */
+ u8 aad[aad_len];
+ /* Source data */
+ u8 src_data[src_data_len];
+
+ /* Device write only portion */
+
+ /* Destination data */
+ u8 dst_data[dst_data_len];
+ /* Hash result data */
+ u8 hash_result[hash_result_len];
+};
+\end{lstlisting}
+
+Stateless mode requests of symmetric algorithm are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_sym_data_flf_stateless {
+ /* Device read only portion */
+#define VIRTIO_CRYPTO_SYM_DATE_REQ_HDR_STATELESS_SIZE 72
+ u8 op_type_flf[VIRTIO_CRYPTO_SYM_DATE_REQ_HDR_STATELESS_SIZE];
+
+ /* Device write only portion */
+ /* See above VIRTIO_CRYPTO_SYM_OP_* */
+ le32 op_type;
+};
+
+struct virtio_crypto_sym_data_vlf_stateless {
+ u8 op_type_vlf[sym_para_len];
+};
+\end{lstlisting}
+
+\field{op_type_flf} is the \field{op_type} specific header, it MUST starts
+with or be one of the following structures:
+\begin{itemize*}
+\item struct virtio_crypto_cipher_data_flf_stateless
+\item struct virtio_crypto_alg_chain_data_flf_stateless
+\end{itemize*}
+
+The length of \field{op_type_flf} is fixed to 72 bytes, the data of unused
+part (if has) will be ingored.
+
+\field{op_type_vlf} is the \field{op_type} specific parameters, it MUST starts
+with or be one of the following structures:
+\begin{itemize*}
+\item struct virtio_crypto_cipher_data_vlf_stateless
+\item struct virtio_crypto_alg_chain_data_vlf_stateless
+\end{itemize*}
+
+\field{sym_para_len} is the size of the specific structure used.
+
+\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_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 ZERO and MUST set the fields in struct
+ virtio_crypto_cipher_data_flf_stateless.sess_para or struct
+ virtio_crypto_alg_chain_data_flf_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_SESSION_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_flf in
+ struct virtio_crypto_sym_data_flf and struct virtio_crypto_cipher_data_vlf in
+ struct virtio_crypto_sym_data_vlf if the request is based on VIRTIO_CRYPTO_SYM_OP_CIPHER.
+\item The driver MUST specify the fields of struct virtio_crypto_alg_chain_data_flf
+ in struct virtio_crypto_sym_data_flf and struct virtio_crypto_alg_chain_data_vlf
+ in struct virtio_crypto_sym_data_vlf if the request is of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING
+ type.
+\end{itemize*}
+
+\devicenormative{\paragraph}{Symmetric algorithms Operation}{Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation}
+
+\begin{itemize*}
+\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 MUST parse the fields of struct virtio_crypto_cipher_data_flf in
+ struct virtio_crypto_sym_data_flf and struct virtio_crypto_cipher_data_vlf in
+ struct virtio_crypto_sym_data_vlf if the request is based on VIRTIO_CRYPTO_SYM_OP_CIPHER.
+\item The device MUST parse the fields of struct virtio_crypto_alg_chain_data_flf
+ in struct virtio_crypto_sym_data_flf and struct virtio_crypto_alg_chain_data_vlf
+ in struct virtio_crypto_sym_data_vlf if the request is of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING
+ type.
+\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 following values of enum VIRTIO_CRYPTO_STATUS:
+\begin{itemize*}
+\item VIRTIO_CRYPTO_OK if the operation success.
+\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
+\item VIRTIO_CRYPTO_INVSESS if the session ID is invalid in session mode.
+\item VIRTIO_CRYPTO_ERR if failure not mentioned above occurs.
+\end{itemize*}
+\end{itemize*}
+
+\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_data_flf {
+ /*
+ * 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_vlf {
+ /* Device read only portion */
+
+ /*
+ * 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 write only portion */
+ /* Pointer to output data */
+ u8 dst_data[dst_data_len];
+};
+\end{lstlisting}
+
+Each request uses the virtio_crypto_aead_data_flf structure and the
+virtio_crypto_aead_data_flf structure to store information used to run the
+AEAD operations.
+
+Stateless mode AEAD service requests are as follows:
+
+\begin{lstlisting}
+struct virtio_crypto_aead_data_flf_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_vlf_stateless {
+ /* Device read only portion */
+
+ /* 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 write only portion */
+ /* Pointer to output data */
+ u8 dst_data[dst_data_len];
+};
+\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_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 ZERO and MUST set the fields in
+ struct virtio_crypto_aead_data_flf_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_SESSION_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_AEAD_STATELESS_MODE feature bit is negotiated, the
+ device MUST parse the virtio_crypto_aead_data_vlf_stateless 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 following 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.
+\begin{itemize*}
+\item VIRTIO_CRYPTO_OK if the operation success.
+\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
+\item VIRTIO_CRYPTO_BADMSG if the verification result is incorrect.
+\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
+\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
+\end{itemize*}
+\end{itemize*}
--
1.8.3.1
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [Qemu-devel] [v23 2/2] virtio-crypto: Add conformance clauses
2017-12-30 9:35 [Qemu-devel] [v23 0/2] virtio-crypto: virtio crypto device specification Longpeng(Mike)
@ 2017-12-30 9:35 ` Longpeng(Mike)
2017-12-30 9:35 ` [virtio-dev] " Longpeng(Mike)
1 sibling, 0 replies; 31+ messages in thread
From: Longpeng(Mike) @ 2017-12-30 9:35 UTC (permalink / raw)
To: qemu-devel, virtio-dev
Cc: luonengjun, mst, cornelia.huck, stefanha, denglingli,
Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, pasic, wangxinxin.wang,
jianjay.zhou, Longpeng(Mike)
From: Gonglei <arei.gonglei@huawei.com>
Add the conformance targets and clauses for
virtio-crypto device.
Signed-off-by: Gonglei <arei.gonglei@huawei.com>
Signed-off-by: Zhoujian <jianjay.zhou@huawei.com>
Signed-off-by: Longpeng(Mike) <longpeng2@huawei.com>
---
conformance.tex | 29 +++++++++++++++++++++++++++++
1 file changed, 29 insertions(+)
diff --git a/conformance.tex b/conformance.tex
index f59e360..cf5f1ac 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -146,6 +146,21 @@ An SCSI host driver MUST conform to the following normative statements:
\item \ref{drivernormative:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
\end{itemize}
+\subsection{Crypto Driver Conformance}\label{sec:Conformance / Driver Conformance / Crypto Driver Conformance}
+
+A Crypto driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / Crypto Device / Device configuration layout}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Initialization}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: create session}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: destroy session}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / HASH Service operation}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / MAC Service operation}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / AEAD Service operation}
+\end{itemize}
+
\section{Device Conformance}\label{sec:Conformance / Device Conformance}
A device MUST conform to the following normative statements:
@@ -267,6 +282,20 @@ An SCSI host device MUST conform to the following normative statements:
\item \ref{devicenormative:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
\end{itemize}
+\subsection{Crypto Device Conformance}\label{sec:Conformance / Device Conformance / Crypto Device Conformance}
+
+A Crypto device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / Crypto Device / Device configuration layout}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: create session}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: destroy session}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / HASH Service operation}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / MAC Service operation}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / AEAD Service operation}
+\end{itemize}
+
\section{Legacy Interface: Transitional Device and
Transitional Driver Conformance}\label{sec:Conformance / Legacy
Interface: Transitional Device and
--
1.8.3.1
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [virtio-dev] [v23 2/2] virtio-crypto: Add conformance clauses
@ 2017-12-30 9:35 ` Longpeng(Mike)
0 siblings, 0 replies; 31+ messages in thread
From: Longpeng(Mike) @ 2017-12-30 9:35 UTC (permalink / raw)
To: qemu-devel, virtio-dev
Cc: luonengjun, mst, cornelia.huck, stefanha, denglingli,
Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, pasic, wangxinxin.wang,
jianjay.zhou, Longpeng(Mike)
From: Gonglei <arei.gonglei@huawei.com>
Add the conformance targets and clauses for
virtio-crypto device.
Signed-off-by: Gonglei <arei.gonglei@huawei.com>
Signed-off-by: Zhoujian <jianjay.zhou@huawei.com>
Signed-off-by: Longpeng(Mike) <longpeng2@huawei.com>
---
conformance.tex | 29 +++++++++++++++++++++++++++++
1 file changed, 29 insertions(+)
diff --git a/conformance.tex b/conformance.tex
index f59e360..cf5f1ac 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -146,6 +146,21 @@ An SCSI host driver MUST conform to the following normative statements:
\item \ref{drivernormative:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
\end{itemize}
+\subsection{Crypto Driver Conformance}\label{sec:Conformance / Driver Conformance / Crypto Driver Conformance}
+
+A Crypto driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / Crypto Device / Device configuration layout}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Initialization}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: create session}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: destroy session}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / HASH Service operation}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / MAC Service operation}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation}
+\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / AEAD Service operation}
+\end{itemize}
+
\section{Device Conformance}\label{sec:Conformance / Device Conformance}
A device MUST conform to the following normative statements:
@@ -267,6 +282,20 @@ An SCSI host device MUST conform to the following normative statements:
\item \ref{devicenormative:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq}
\end{itemize}
+\subsection{Crypto Device Conformance}\label{sec:Conformance / Device Conformance / Crypto Device Conformance}
+
+A Crypto device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / Crypto Device / Device configuration layout}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: create session}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: destroy session}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / HASH Service operation}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / MAC Service operation}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation}
+\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / AEAD Service operation}
+\end{itemize}
+
\section{Legacy Interface: Transitional Device and
Transitional Driver Conformance}\label{sec:Conformance / Legacy
Interface: Transitional Device and
--
1.8.3.1
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply related [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
2017-12-30 9:35 ` [Qemu-devel] [v23 1/2] virtio-crypto: Add " Longpeng(Mike)
@ 2018-01-09 17:05 ` Halil Pasic
0 siblings, 0 replies; 31+ messages in thread
From: Halil Pasic @ 2018-01-09 17:05 UTC (permalink / raw)
To: Longpeng(Mike), qemu-devel, virtio-dev
Cc: luonengjun, mst, cornelia.huck, stefanha, denglingli,
Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
> From: Gonglei <arei.gonglei@huawei.com>
>
> 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 <arei.gonglei@huawei.com>
> Signed-off-by: Zhoujian <jianjay.zhou@huawei.com>
> Signed-off-by: Longpeng(Mike) <longpeng2@huawei.com>
> ---
> acknowledgements.tex | 4 +
> content.tex | 2 +
> virtio-crypto.tex | 1525 ++++++++++++++++++++++++++++++++++++++++++++++++++
> 3 files changed, 1531 insertions(+)
> create mode 100644 virtio-crypto.tex
>
> diff --git a/acknowledgements.tex b/acknowledgements.tex
> index 2d893d9..cdde247 100644
> --- a/acknowledgements.tex
> +++ b/acknowledgements.tex
> @@ -16,10 +16,13 @@ Daniel Kiper, Oracle \newline
> Geoff Brown, Machine-to-Machine Intelligence (M2MI) Corporation \newline
> Gershon Janssen, Individual Member \newline
> James Bottomley, Parallels IP Holdings GmbH \newline
> +Jian Zhou, Huawei \newline
> +Lei Gong, Huawei \newline
> Luiz Capitulino, Red Hat \newline
> Michael S. Tsirkin, Red Hat \newline
> Paolo Bonzini, Red Hat \newline
> Pawel Moll, ARM \newline
> +Peng Long, Huawei \newline
> Richard Sohn, Alcatel-Lucent \newline
> Rusty Russell, IBM \newline
> Sasha Levin, Oracle \newline
> @@ -38,6 +41,7 @@ Brian Foley, ARM \newline
> David Alan Gilbert, Red Hat \newline
> Fam Zheng, Red Hat \newline
> Gerd Hoffmann, Red Hat \newline
> +Halil Pasic, IBM \newline
> Jason Wang, Red Hat \newline
> Laura Novich, Red Hat \newline
> Patrick Durusau, Technical Advisory Board, OASIS \newline
> diff --git a/content.tex b/content.tex
> index c840588..d1d3b09 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -5819,6 +5819,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 these device-independent feature bits defined:
> diff --git a/virtio-crypto.tex b/virtio-crypto.tex
> new file mode 100644
> index 0000000..4bd5b51
> --- /dev/null
> +++ b/virtio-crypto.tex
> @@ -0,0 +1,1525 @@
> +\section{Crypto Device}\label{sec:Device Types / Crypto Device}
> +
> +The virtio crypto device is a virtual cryptography device as well as a
> +virtual cryptographic accelerator. The virtio crypto device provides the
> +following crypto services: CIPHER, MAC, HASH, and AEAD. Virtio crypto
> +devices have a single control queue and at least one data queue. Crypto
> +operation requests are placed into a data queue, and serviced by the
> +device. Some crypto operation requests are only valid in the context of a
> +session. The role of the control queue is facilitating control operation
> +requests. Sessions management is realized with control operation
> +requests.
> +
> +\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}
> +
> +\begin{description}
> +\item VIRTIO_CRYPTO_F_REVISION_1 (0) revision 1. Revision 1 has a specific
> + request format and other enhancements (which result in some additional
> + requirements).
> +\item VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE (1) stateless mode requests are
> + supported by the CIPHER service.
> +\item VIRTIO_CRYPTO_F_HASH_STATELESS_MODE (2) stateless mode requests are
> + supported by the HASH service.
> +\item VIRTIO_CRYPTO_F_MAC_STATELESS_MODE (3) stateless mode requests are
> + supported by the MAC service.
> +\item VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE (4) stateless mode requests are
> + supported by the AEAD service.
> +\end{description}
> +
> +
> +\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_REVISION_1.
> +\item[VIRTIO_CRYPTO_F_HASH_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
> +\item[VIRTIO_CRYPTO_F_MAC_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
> +\item[VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
> +\end{description}
> +
> +\subsection{Supported crypto services}\label{sec:Device Types / Crypto Device / Supported crypto services}
> +
> +The following crypto services are defined:
> +
> +\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 designate bits used to indicate the which of crypto services are
> +offered by the device as described in, 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 designate the algorithm in (CIPHER type) crypto
> +operation requests, 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 designate the algorithm in (HASH type) crypto
> +operation 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 designate the algorithm in (MAC type) crypto
> +operation requests, 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 designate the algorithm in (DEAD type) crypto
> +operation requests, 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 Currently, only one \field(status) bit is defined: VIRTIO_CRYPTO_S_HW_READY
> + set indicates that the device is ready to process requests, this bit is read-only
> + for the driver
> +\begin{lstlisting}
> +#define VIRTIO_CRYPTO_S_HW_READY (1 << 0)
> +\end{lstlisting}
> +
> +\item[\field{max_dataqueues}] is the maximum number of data virtqueues that can
> + be configured by the device. The driver MAY use only one data queue, or it
> + can use more to achieve better performance.
> +
> +\item[\field{crypto_services}] crypto service offered, see \ref{sec:Device Types / Crypto Device / Supported crypto services}.
> +
> +\item[\field{cipher_algo_l}] CIPHER algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
> +
> +\item[\field{cipher_algo_h}] CIPHER algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
> +
> +\item[\field{hash_algo}] HASH algorithms bits, see \ref{sec:Device Types / Crypto Device / Supported crypto services / HASH services}.
> +
> +\item[\field{mac_algo_l}] MAC algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
> +
> +\item[\field{mac_algo_h}] MAC algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
> +
> +\item[\field{aead_algo}] AEAD algorithms bits, 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.
I can't find what happens if this limit isn't honored by the driver. Moreover
reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
such requests? I think in qemu implementation we fail the request.
This question is only about niceness. We are already good enough, IMHO:
since the implementer of the driver can't be sure what is going to happen
if the driver disregards max_cipher_key_len it is already an implicit
SHOULD.
> +
> +\item[\field{max_auth_key_len}] is the maximum length of authenticated key supported by the device.
Same here.
> +
> +\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
s/device/device.
What a content of a request and how is its size calculated? Where is this defined.
The question what happens if not honored applies similarly.
> +\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 the \field{status} with valid flags, undefined flags MUST NOT be set.
> +\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 for each service advertised by \field{crypto_services}.
> + The device MUST NOT set the not defined algorithms bits.
> +\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 \field{status} from the bottom bit of status to check whether the
> + VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
> +\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD ignore the not defined algorithms bits.
> +\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*}
Seems to like a common practice in the virtio spec to say SHOULD read some
config space parameter in a driver normative but then having no driver normative
about the operational implications of the parameter.
While I do think that the reader is usually fully capable of inferring
the operational requirement, I find it a bit strange: having the operational
stuff explicit (and possibly needs to be read from the config space implicit)
seems more straight forward to me.
Anyway, you are consistent with the rest of the spec, so prefer keeping it
like this.
> +
> +\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 configure 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}
> +
> +The operation of a virtio crypto device is driven by requests placed on the virtqueues.
> +Requests consist of a queue-type specific header (specifying among others the operation)
> +and an operation specific payload.
> +
> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated the device may support both session mode
> +(See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation})
> +and stateless mode operation requests.
> +In stateless mode all operation parameters are supplied as a part of each request,
> +while in session mode, some or all operation parameters are managed within the
> +session. Stateless mode is guarded by feature bits 0-4 on a service level. If
> +stateless mode is negotiated for a service, the service is available both in
> +session and stateless mode; otherwise it's only available in session mode.
How about the following?
"""
If stateless mode is negotiated for a service, the service accepts both session mode and stateless
requests; otherwise stateless mode requests are rejected (via operation status).
"""
I prefer it because i think it makes clearer than session mode and stateless
mode are concepts that apply on request and not on service (or let's say queue)
level.
> +
> +\subsubsection{Operation Status}\label{sec:Device Types / Crypto Device / Device Operation / Operation status}
> +The device MUST return a status code as part of the operation (both session
> +operation and service operation) result. The valid operation status as follows:
> +
> +\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_NOSPC = 5,
> + VIRTIO_CRYPTO_MAX
> +};
> +\end{lstlisting}
> +
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK: success.
> +\item VIRTIO_CRYPTO_BADMSG: authentication failed (only when AEAD decryption).
> +\item VIRTIO_CRYPTO_NOTSUPP: operation or algorithm is unsupported.
> +\item VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto operations.
> +\item VIRTIO_CRYPTO_NOSPC: no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
> + feature bit is negotiated).
> +\item VIRTIO_CRYPTO_ERR: any failure not mentioned above occurs.
> +\end{itemize*}
> +
Just thinking loud: We don't seem to be able to differentiate between device
detected a driver (guest) bug, and something went wrong with the backend.
I'm not sure differentiating between the two is useful in the first place.
> +\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}).
> +
> +The header for controlq is of the following form:
> +\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;
> + le32 reserved;
> +};
> +\end{lstlisting}
> +
> +The controlq request is composed of four parts:
> +\begin{lstlisting}
> +struct virtio_crypto_op_ctrl_req {
> + /* Device read only portion */
> +
> + struct virtio_crypto_ctrl_header header;
> +
> +#define VIRTIO_CRYPTO_CTRLQ_OP_SPEC_HDR_LEGACY 56
> + /* fixed length fields, opcode specific */
> + u8 op_flf[flf_len];
> +
> + /* variable length fields, opcode specific */
> + u8 op_vlf[vlf_len];
> +
> + /* Device write only portion */
> +
> + /* op result or completion status */
> + u8 op_outcome[outcome_len];
> +};
> +\end{lstlisting}
> +
> +\field{header} is a general header (see above).
> +
> +\field{op_flf} is the opcode (in \field{header}) specific fixed-length paramenters.
> +
> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit (see below).
> +
> +\field{op_vlf} is the opcode (in \field{header}) specific variable-length paramenters.
> +
> +\field{vlf_len} is the size of the specific structure used.
> +\begin{note}
> +The \field{vlf_len} of session-destroy operation and the hash-session-create
> +operation is ZERO.
> +\end{note}
> +
> +\begin{itemize*}
> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_CREATE_SESSION
> + then \field{op_flf} is struct virtio_crypto_sym_create_session_flf if
> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_sym_create_session_flf if
> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
> + virtio_crypto_sym_create_session_vlf.
> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH_CREATE_SESSION
> + then \field{op_flf} is struct virtio_crypto_hash_create_session_flf if
> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_hash_create_session_flf if
> + padded to 56 bytes if NOT negotiated.
> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC_CREATE_SESSION
> + then \field{op_flf} is struct virtio_crypto_mac_create_session_flf if
> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_mac_create_session_flf if
> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
> + virtio_crypto_mac_create_session_vlf.
> +\end{itemize*}
> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_CREATE_SESSION
> + then \field{op_flf} is struct virtio_crypto_aead_create_session_flf if
> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_aead_create_session_flf if
> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
> + virtio_crypto_aead_create_session_vlf.
> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_DESTROY_SESSION
> + or VIRTIO_CRYPTO_HASH_DESTROY_SESSION or VIRTIO_CRYPTO_MAC_DESTROY_SESSION or
> + VIRTIO_CRYPTO_AEAD_DESTROY_SESSION then \field{op_flf} is struct
> + virtio_crypto_destroy_session_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated and
> + struct virtio_crypto_destroy_session_flf if padded to 56 bytes if NOT negotiated.
> +\end{itemize*}
> +
> +\field{op_outcome} stores the result of operation and must be struct
> +virtio_crypto_destroy_session_input for session-destroy operation or
> +struct virtio_crypto_session_input.
> +
> +\field{outcome_len} is the size of the structure used.
> +
> +
> +\paragraph{Session operation}\label{sec:Device Types / Crypto Device / Device
> +Operation / Control Virtqueue / Session operation}
> +
> +The session is a handle which describes the cryptographic parameters to be
> +applied to a number of buffers.
> +
> +The following structure stores the result of session creation set by the device:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_session_input {
> + /* Device write only portion */
I think you cann drop this comment along with the following similar
comments. We have already told whats device read only and what is
device write only in virtio_crypto_op_ctrl_req.
Restating it at each struct is redundant and IMHO just confusing. The
R/W is determined by where does the struct sit in the request.
> + 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_flf {
> + /* Device read only portion */
> + le64 session_id;
> +};
> +
> +struct virtio_crypto_destroy_session_input {
> + /* Device write only portion */
> + 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}
> +
> +The fixed-length paramenters of HASH session requests is as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_hash_create_session_flf {
> + /* Device read only portion */
> +
> + /* See VIRTIO_CRYPTO_HASH_* above */
> + le32 algo;
> + /* hash result length */
> + le32 hash_result_len;
> +};
> +\end{lstlisting}
> +
> +
> +\subparagraph{Session operation: MAC session}\label{sec:Device Types / Crypto Device / Device
> +Operation / Control Virtqueue / Session operation / Session operation: MAC session}
> +
> +The fixed-length and the variable-length parameters of MAC session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_mac_create_session_flf {
> + /* Device read only portion */
> +
> + /* 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_vlf {
> + /* Device read only portion */
> +
> + /* The authenticated key */
> + u8 auth_key[auth_key_len];
> +};
> +\end{lstlisting}
> +
> +The length of \field{auth_key} is specified in \field{auth_key_len} in the struct
> +virtio_crypto_mac_create_session_flf.
> +
> +
> +\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 could be the CIPHER algorithms request
> +or the chain algorithms (chaining CIPHER and HASH/MAC) request.
> +
> +The fixed-length and the variable-length parameters of CIPHER session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_cipher_session_flf {
> + /* Device read only portion */
> +
> + /* 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_vlf {
> + /* Device read only portion */
> +
> + /* The cipher key */
> + u8 cipher_key[keylen];
> +};
> +\end{lstlisting}
> +
> +The length of \field{cipher_key} is specified in \field{keylen} in the struct
> +virtio_crypto_cipher_session_flf.
> +
> +The fixed-length and the variable-length parameters of Chain session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_alg_chain_session_flf {
> + /* Device read only portion */
> +
> +#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_flf cipher_hdr;
> +
> +#define VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE 16
> + /* fixed length fields, algo specific */
> + u8 algo_flf[VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE];
> +
> + /* length of the additional authenticated data (AAD) in bytes */
> + le32 aad_len;
> + le32 padding;
> +};
> +
> +struct virtio_crypto_alg_chain_session_vlf {
> + /* Device read only portion */
> +
> + /* The cipher key */
> + u8 cipher_key[keylen];
> + /* The authenticated key */
> + u8 auth_key[auth_key_len];
> +};
> +\end{lstlisting}
> +
> +\field{hash_mode} decides the type used by \field{algo_flf}.
> +
> +\field{algo_flf} is fixed to 16 bytes and MUST contains or be one of
> +the following types:
> +\begin{itemize*}
> +\item struct virtio_crypto_hash_create_session_flf
> +\item struct virtio_crypto_mac_create_session_flf
> +\end{itemize*}
> +The data of unused part (if has) in \field{algo_flf} will be ignored.
> +
> +The length of \field{cipher_key} is specified in \field{keylen} in \field{cipher_hdr}.
> +
> +The length of \field{auth_key} is specified in \field{auth_key_len} in struct
> +virtio_crypto_mac_create_session_flf.
> +
> +The fixed-length parameters of Symmetric session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_sym_create_session_flf {
> + /* Device read only portion */
> +
> +#define VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE 48
> + /* fixed length fields, opcode specific */
> + u8 op_flf[VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE];
> +
> +/* 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}
> +
> +\field{op_flf} is fixed to 48 bytes, MUST contains or be one of
> +the following types:
> +\begin{itemize*}
> +\item struct virtio_crypto_cipher_session_flf
> +\item struct virtio_crypto_alg_chain_session_flf
> +\end{itemize*}
> +The data of unused part (if has) in \field{op_flf} will be ignored.
> +
> +\field{op_type} decides the type used by \field{op_flf}.
> +
> +The variable-length parameters of Symmetric session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_sym_create_session_vlf {
> + /* Device read only portion */
> + /* variable length fields, opcode specific */
> + u8 op_vlf[vlf_len];
> +};
> +\end{lstlisting}
> +
> +\field{op_vlf} MUST contains or be one of the following types:
> +\begin{itemize*}
> +\item struct virtio_crypto_cipher_session_vlf
> +\item struct virtio_crypto_alg_chain_session_vlf
> +\end{itemize*}
> +
> +\field{op_type} in struct virtio_crypto_sym_create_session_flf decides the
> +type used by \field{op_vlf}.
> +
> +\field{vlf_len} is the size of the specific structure used.
> +
> +
> +\subparagraph{Session operation: AEAD session}\label{sec:Device Types / Crypto Device / Device
> +Operation / Control Virtqueue / Session operation / Session operation: AEAD session}
> +
> +The fixed-length and the variable-length parameters of AEAD session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_aead_create_session_flf {
> + /* Device read only portion */
> +
> + /* 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_vlf {
> + /* Device read only portion */
> + u8 key[key_len];
> +};
> +\end{lstlisting}
> +
> +The length of \field{key} is specified in \field{key_len} in struct
> +virtio_crypto_aead_create_session_flf.
> +
> +
> +\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 \field{opcode} field based on service type: CIPHER, HASH, MAC, or AEAD.
> +\item The driver MUST set the control general header, the opcode specific header,
> + the opcode specific extra parameters and the opcode specific outcome buffer in turn.
> + See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}.
> +\item The driver MUST set the \field{reversed} field to zero.
> +\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 use the corresponding opcode specific structure according to the
> + \field{opcode} in the control general header.
> +\item The device MUST extract extra parameters according to the structures used.
> +\item The device MUST set the \field{status} field to one of the following values of enum
> + VIRTIO_CRYPTO_STATUS after finish a session creation:
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
> +\item VIRTIO_CRYPTO_NOSPC if no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
> + feature bit is negotiated).
> +\item VIRTIO_CRYPTO_ERR if failure not mentioned above occurs.
> +\end{itemize*}
> +\item The device MUST set the \field{session_id} field to a unique session identifier only
> + if the status is set to VIRTIO_CRYPTO_OK.
> +\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 following values of enum VIRTIO_CRYPTO_STATUS.
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
> +\item VIRTIO_CRYPTO_ERR if any failure occurs.
> +\end{itemize*}
> +\end{itemize*}
> +
> +
> +\subsubsection{Data Virtqueue}\label{sec:Device Types / Crypto Device / Device Operation / Data Virtqueue}
> +
> +The driver uses the data virtqueues to transmit crypto operation requests to the device,
> +and completes the crypto operations.
> +
> +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_SESSION_MODE 1
> + /* control flag to control the request */
> + le32 flag;
> + le32 padding;
> +};
> +\end{lstlisting}
> +
> +\begin{note}
> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
> +is not negotiated then <SERVICE> retuqests with the \field{flag} (in struct
s/retuqests/requests
> +virtio_crypto_op_header) is ZERO need to be rejected. If VIRTIO_CRYPTO_F_REVISION_1 is
> +not negotiated the \field{flag} is ignored.
> +\end{note}
> +
I think your formulation is a bit hard to understand.
I would prefer:
+\begin{note}
+If VIRTIO_CRYPTO_F_REVISION_1 is not negotiated the \field{flag} is ignored.
+
+If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
+is not negotiated, then the device should reject <SERVICE> requests if
+VIRTIO_CRYPTO_FLAG_SESSION_MODE is not set (in \field{flag}).
+\end{note}
+
> +The dataq request is composed of four parts:
> +\begin{lstlisting}
> +struct virtio_crypto_op_data_req {
> + /* Device read only portion */
> +
> + struct virtio_crypto_op_header header;
> +
> +#define VIRTIO_CRYPTO_DATAQ_OP_SPEC_HDR_LEGACY 48
> + /* fixed length fields, opcode specific */
> + u8 op_flf[flf_len];
> +
> + /* Device read && write portion */
> + /* variable length fields, opcode specific */
> + u8 op_vlf[vlf_len];
Descriptors are either read or write. You need read && write (whatever the
sematic is) because you throw things together that don't belong together.
I would try to do the same as for the ctrl requests:
+ * Device write only portion */
+ u8 op_outcome;
and describe the outcome on a per service basis. Also see my
comments about the dst_data_len below.
> +
> + /* Device write only portion */
> + struct virtio_crypto_inhdr inhdr;
> +};
> +\end{lstlisting}
> +
> +\field{header} is a general header (see above).
> +
> +\field{op_flf} is the opcode (in \field{header}) specific header.
> +
> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit
> +(see below).
> +
> +\field{op_vlf} is the opcode (in \field{header}) specific parameters.
> +
> +\field{vlf_len} is the size of the specific structure used.
> +
> +\begin{itemize*}
> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_ENCRYPT
> + or VIRTIO_CRYPTO_CIPHER_DECRYPT then:
> + \begin{itemize*}
> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is negotiated, \field{op_flf} is
> + struct virtio_crypto_sym_data_flf_stateless, and \field{op_vlf} is struct
> + virtio_crypto_sym_data_vlf_stateless.
What does this _data_ (in the name) symbolise?
> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is NOT negotiated, \field{op_flf}
> + is struct virtio_crypto_sym_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
> + and struct virtio_crypto_sym_data_flf if padded to 48 bytes if NOT negotiated,
> + and \field{op_vlf} is struct virtio_crypto_sym_data_vlf.
> + \end{itemize*}
> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH:
> + \begin{itemize*}
> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is negotiated, \field{op_flf} is
> + struct virtio_crypto_hash_data_flf_stateless, and \field{op_vlf} is struct
> + virtio_crypto_hash_data_vlf_stateless.
> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is NOT negotiated, \field{op_flf}
> + is struct virtio_crypto_hash_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
> + and struct virtio_crypto_hash_data_flf if padded to 48 bytes if NOT negotiated,
> + and \field{op_vlf} is struct virtio_crypto_hash_data_vlf.
> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC:
> + \begin{itemize*}
> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is negotiated, \field{op_flf} is
> + struct virtio_crypto_mac_data_flf_stateless, and \field{op_vlf} is struct
> + virtio_crypto_mac_data_vlf_stateless.
> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is NOT negotiated, \field{op_flf}
> + is struct virtio_crypto_mac_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
> + and struct virtio_crypto_mac_data_flf if padded to 48 bytes if NOT negotiated,
> + and \field{op_vlf} is struct virtio_crypto_mac_data_vlf.
> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_ENCRYPT
> + or VIRTIO_CRYPTO_AEAD_DECRYPT then:
> + \begin{itemize*}
> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is negotiated, \field{op_flf} is
> + struct virtio_crypto_aead_data_flf_stateless, and \field{op_vlf} is struct
> + virtio_crypto_aead_data_vlf_stateless.
> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is NOT negotiated, \field{op_flf}
> + is struct virtio_crypto_aead_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
> + and struct virtio_crypto_aead_data_flf if padded to 48 bytes if NOT negotiated,
> + and \field{op_vlf} is struct virtio_crypto_aead_data_vlf.
> +\end{itemize*}
> +
> +\field{inhdr} is a unified input header that used to return the status of
> +the operations, 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_data_flf {
> + /* length of source data */
> + le32 src_data_len;
> + /* hash result length */
> + le32 hash_result_len;
> +};
> +
> +struct virtio_crypto_hash_data_vlf {
> + /* Device read only portion */
> + /* Source data */
> + u8 src_data[src_data_len];
> +
> + /* Device write only portion */
> + /* Hash result data */
> + u8 hash_result[hash_result_len];
> +};
> +\end{lstlisting}
> +
> +Each data request uses the virtio_crypto_hash_data_flf structure and the
> +virtio_crypto_hash_data_vlfto structure to store information used to run the
> +HASH operations.
> +
> +\field{src_data} is the source data that will be processed.
> +\field{src_data_len} is the length of source data.
> +\field{hash_result} is the result data and \field{hash_result_len} is the length
> +of it.
> +
> +Stateless mode HASH service requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_hash_data_flf_stateless {
> + 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_vlf_stateless {
> + /* Device read only portion */
> + /* Source data */
> + u8 src_data[src_data_len];
> +
> + /* Device write only portion */
> + /* Hash result data */
> + u8 hash_result[hash_result_len];
> +};
> +\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_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 ZERO and MUST set the fields in struct
> + virtio_crypto_hash_data_flf_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_SESSION_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 The device MUST use the corresponding structure according to the \field{opcode}
> + in the data general header.
> +\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
> + following values of enum VIRTIO_CRYPTO_STATUS:
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK if the operation success.
> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
> +\end{itemize*}
> +\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_data_flf {
> + struct virtio_crypto_hash_data_flf hdr;
> +};
> +
> +struct virtio_crypto_mac_data_vlf {
> + /* Device read only portion */
> + /* Source data */
> + u8 src_data[src_data_len];
> +
> + /* Device write only portion */
> + /* Hash result data */
> + u8 hash_result[hash_result_len];
> +};
> +\end{lstlisting}
> +
> +Each request uses the virtio_crypto_mac_data_flf structure and the
> +virtio_crypto_mac_data_vlf structure to store information used to run the
> +MAC operations.
> +
> +\field{src_data} is the source data that will be processed.
> +\field{src_data_len} is the length of source data.
> +\field{hash_result} is the result data and \field{hash_result_len} is the length
> +of it.
> +
> +Stateless mode MAC service requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_mac_data_flf_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_vlf_stateless {
> + /* Device read only portion */
> + /* The authenticated key */
> + u8 auth_key[auth_key_len];
> + /* Source data */
> + u8 src_data[src_data_len];
> +
> + /* Device write only portion */
> + /* Hash result data */
> + u8 hash_result[hash_result_len];
> +};
> +\end{lstlisting}
> +
> +\field{auth_key} is the authenticated key that will be used during the process.
> +\field{auth_key_len} is the length of the key.
> +
> +\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_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 ZERO and MUST set the fields in struct
> + virtio_crypto_mac_data_flf_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_SESSION_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_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
> + following values of enum VIRTIO_CRYPTO_STATUS:
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK if the operation success.
> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
> +\end{itemize*}
> +\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_data_flf {
> + /*
> + * 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_vlf {
> + /* Device read only portion */
> +
> + /*
> + * 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 write only portion */
> + /* Destination data */
> + u8 dst_data[dst_data_len];
I'm a bit puzzled about dst_data_len. I'm by no means a crypto expert,
and that is probably the very reason of my discomfort.
I've tried to figure out how dst_data_len is used and expected to find
a place that checks, that at least a sufficiently large buffer was provided.
I've also assumed that the src_data_len is likely to imply the dst_data_len
for any given algorithm. Furthermore, I even hypothesised that the both
lengths are the same. All based on what I remember about block ciphers.
If that hypothesis is right, then I don't understand why do we need
both src_data_len and dst_data_len.
Since dst_data_len is device read only, the driver I figure the driver
needs to know the exact length (since I cant figure out, based on this
spec, how is it supposed to be told by the device which part of the
buffer is the result and which part garbage). So the only sane usage
I was able to come up with is to avoid the device overwritting other
parts of the requests device writtable part because of a driver
bug (wrong dst_data_len). But as I've said I could not find the corresponding
code in qemu.
Anyway providing some more background for the guys only superficially
involved with crypto (like me) would be appreciated.
I will stop here for now. I read the rest real quick and I did not
see anything major. I think we are slowly getting there.
Regards,
Halil
^ permalink raw reply [flat|nested] 31+ messages in thread
* [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-01-09 17:05 ` Halil Pasic
0 siblings, 0 replies; 31+ messages in thread
From: Halil Pasic @ 2018-01-09 17:05 UTC (permalink / raw)
To: Longpeng(Mike), qemu-devel, virtio-dev
Cc: luonengjun, mst, cornelia.huck, stefanha, denglingli,
Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
> From: Gonglei <arei.gonglei@huawei.com>
>
> 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 <arei.gonglei@huawei.com>
> Signed-off-by: Zhoujian <jianjay.zhou@huawei.com>
> Signed-off-by: Longpeng(Mike) <longpeng2@huawei.com>
> ---
> acknowledgements.tex | 4 +
> content.tex | 2 +
> virtio-crypto.tex | 1525 ++++++++++++++++++++++++++++++++++++++++++++++++++
> 3 files changed, 1531 insertions(+)
> create mode 100644 virtio-crypto.tex
>
> diff --git a/acknowledgements.tex b/acknowledgements.tex
> index 2d893d9..cdde247 100644
> --- a/acknowledgements.tex
> +++ b/acknowledgements.tex
> @@ -16,10 +16,13 @@ Daniel Kiper, Oracle \newline
> Geoff Brown, Machine-to-Machine Intelligence (M2MI) Corporation \newline
> Gershon Janssen, Individual Member \newline
> James Bottomley, Parallels IP Holdings GmbH \newline
> +Jian Zhou, Huawei \newline
> +Lei Gong, Huawei \newline
> Luiz Capitulino, Red Hat \newline
> Michael S. Tsirkin, Red Hat \newline
> Paolo Bonzini, Red Hat \newline
> Pawel Moll, ARM \newline
> +Peng Long, Huawei \newline
> Richard Sohn, Alcatel-Lucent \newline
> Rusty Russell, IBM \newline
> Sasha Levin, Oracle \newline
> @@ -38,6 +41,7 @@ Brian Foley, ARM \newline
> David Alan Gilbert, Red Hat \newline
> Fam Zheng, Red Hat \newline
> Gerd Hoffmann, Red Hat \newline
> +Halil Pasic, IBM \newline
> Jason Wang, Red Hat \newline
> Laura Novich, Red Hat \newline
> Patrick Durusau, Technical Advisory Board, OASIS \newline
> diff --git a/content.tex b/content.tex
> index c840588..d1d3b09 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -5819,6 +5819,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 these device-independent feature bits defined:
> diff --git a/virtio-crypto.tex b/virtio-crypto.tex
> new file mode 100644
> index 0000000..4bd5b51
> --- /dev/null
> +++ b/virtio-crypto.tex
> @@ -0,0 +1,1525 @@
> +\section{Crypto Device}\label{sec:Device Types / Crypto Device}
> +
> +The virtio crypto device is a virtual cryptography device as well as a
> +virtual cryptographic accelerator. The virtio crypto device provides the
> +following crypto services: CIPHER, MAC, HASH, and AEAD. Virtio crypto
> +devices have a single control queue and at least one data queue. Crypto
> +operation requests are placed into a data queue, and serviced by the
> +device. Some crypto operation requests are only valid in the context of a
> +session. The role of the control queue is facilitating control operation
> +requests. Sessions management is realized with control operation
> +requests.
> +
> +\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}
> +
> +\begin{description}
> +\item VIRTIO_CRYPTO_F_REVISION_1 (0) revision 1. Revision 1 has a specific
> + request format and other enhancements (which result in some additional
> + requirements).
> +\item VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE (1) stateless mode requests are
> + supported by the CIPHER service.
> +\item VIRTIO_CRYPTO_F_HASH_STATELESS_MODE (2) stateless mode requests are
> + supported by the HASH service.
> +\item VIRTIO_CRYPTO_F_MAC_STATELESS_MODE (3) stateless mode requests are
> + supported by the MAC service.
> +\item VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE (4) stateless mode requests are
> + supported by the AEAD service.
> +\end{description}
> +
> +
> +\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_REVISION_1.
> +\item[VIRTIO_CRYPTO_F_HASH_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
> +\item[VIRTIO_CRYPTO_F_MAC_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
> +\item[VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
> +\end{description}
> +
> +\subsection{Supported crypto services}\label{sec:Device Types / Crypto Device / Supported crypto services}
> +
> +The following crypto services are defined:
> +
> +\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 designate bits used to indicate the which of crypto services are
> +offered by the device as described in, 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 designate the algorithm in (CIPHER type) crypto
> +operation requests, 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 designate the algorithm in (HASH type) crypto
> +operation 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 designate the algorithm in (MAC type) crypto
> +operation requests, 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 designate the algorithm in (DEAD type) crypto
> +operation requests, 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 Currently, only one \field(status) bit is defined: VIRTIO_CRYPTO_S_HW_READY
> + set indicates that the device is ready to process requests, this bit is read-only
> + for the driver
> +\begin{lstlisting}
> +#define VIRTIO_CRYPTO_S_HW_READY (1 << 0)
> +\end{lstlisting}
> +
> +\item[\field{max_dataqueues}] is the maximum number of data virtqueues that can
> + be configured by the device. The driver MAY use only one data queue, or it
> + can use more to achieve better performance.
> +
> +\item[\field{crypto_services}] crypto service offered, see \ref{sec:Device Types / Crypto Device / Supported crypto services}.
> +
> +\item[\field{cipher_algo_l}] CIPHER algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
> +
> +\item[\field{cipher_algo_h}] CIPHER algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
> +
> +\item[\field{hash_algo}] HASH algorithms bits, see \ref{sec:Device Types / Crypto Device / Supported crypto services / HASH services}.
> +
> +\item[\field{mac_algo_l}] MAC algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
> +
> +\item[\field{mac_algo_h}] MAC algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
> +
> +\item[\field{aead_algo}] AEAD algorithms bits, 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.
I can't find what happens if this limit isn't honored by the driver. Moreover
reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
such requests? I think in qemu implementation we fail the request.
This question is only about niceness. We are already good enough, IMHO:
since the implementer of the driver can't be sure what is going to happen
if the driver disregards max_cipher_key_len it is already an implicit
SHOULD.
> +
> +\item[\field{max_auth_key_len}] is the maximum length of authenticated key supported by the device.
Same here.
> +
> +\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
s/device/device.
What a content of a request and how is its size calculated? Where is this defined.
The question what happens if not honored applies similarly.
> +\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 the \field{status} with valid flags, undefined flags MUST NOT be set.
> +\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 for each service advertised by \field{crypto_services}.
> + The device MUST NOT set the not defined algorithms bits.
> +\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 \field{status} from the bottom bit of status to check whether the
> + VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
> +\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD ignore the not defined algorithms bits.
> +\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*}
Seems to like a common practice in the virtio spec to say SHOULD read some
config space parameter in a driver normative but then having no driver normative
about the operational implications of the parameter.
While I do think that the reader is usually fully capable of inferring
the operational requirement, I find it a bit strange: having the operational
stuff explicit (and possibly needs to be read from the config space implicit)
seems more straight forward to me.
Anyway, you are consistent with the rest of the spec, so prefer keeping it
like this.
> +
> +\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 configure 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}
> +
> +The operation of a virtio crypto device is driven by requests placed on the virtqueues.
> +Requests consist of a queue-type specific header (specifying among others the operation)
> +and an operation specific payload.
> +
> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated the device may support both session mode
> +(See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation})
> +and stateless mode operation requests.
> +In stateless mode all operation parameters are supplied as a part of each request,
> +while in session mode, some or all operation parameters are managed within the
> +session. Stateless mode is guarded by feature bits 0-4 on a service level. If
> +stateless mode is negotiated for a service, the service is available both in
> +session and stateless mode; otherwise it's only available in session mode.
How about the following?
"""
If stateless mode is negotiated for a service, the service accepts both session mode and stateless
requests; otherwise stateless mode requests are rejected (via operation status).
"""
I prefer it because i think it makes clearer than session mode and stateless
mode are concepts that apply on request and not on service (or let's say queue)
level.
> +
> +\subsubsection{Operation Status}\label{sec:Device Types / Crypto Device / Device Operation / Operation status}
> +The device MUST return a status code as part of the operation (both session
> +operation and service operation) result. The valid operation status as follows:
> +
> +\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_NOSPC = 5,
> + VIRTIO_CRYPTO_MAX
> +};
> +\end{lstlisting}
> +
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK: success.
> +\item VIRTIO_CRYPTO_BADMSG: authentication failed (only when AEAD decryption).
> +\item VIRTIO_CRYPTO_NOTSUPP: operation or algorithm is unsupported.
> +\item VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto operations.
> +\item VIRTIO_CRYPTO_NOSPC: no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
> + feature bit is negotiated).
> +\item VIRTIO_CRYPTO_ERR: any failure not mentioned above occurs.
> +\end{itemize*}
> +
Just thinking loud: We don't seem to be able to differentiate between device
detected a driver (guest) bug, and something went wrong with the backend.
I'm not sure differentiating between the two is useful in the first place.
> +\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}).
> +
> +The header for controlq is of the following form:
> +\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;
> + le32 reserved;
> +};
> +\end{lstlisting}
> +
> +The controlq request is composed of four parts:
> +\begin{lstlisting}
> +struct virtio_crypto_op_ctrl_req {
> + /* Device read only portion */
> +
> + struct virtio_crypto_ctrl_header header;
> +
> +#define VIRTIO_CRYPTO_CTRLQ_OP_SPEC_HDR_LEGACY 56
> + /* fixed length fields, opcode specific */
> + u8 op_flf[flf_len];
> +
> + /* variable length fields, opcode specific */
> + u8 op_vlf[vlf_len];
> +
> + /* Device write only portion */
> +
> + /* op result or completion status */
> + u8 op_outcome[outcome_len];
> +};
> +\end{lstlisting}
> +
> +\field{header} is a general header (see above).
> +
> +\field{op_flf} is the opcode (in \field{header}) specific fixed-length paramenters.
> +
> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit (see below).
> +
> +\field{op_vlf} is the opcode (in \field{header}) specific variable-length paramenters.
> +
> +\field{vlf_len} is the size of the specific structure used.
> +\begin{note}
> +The \field{vlf_len} of session-destroy operation and the hash-session-create
> +operation is ZERO.
> +\end{note}
> +
> +\begin{itemize*}
> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_CREATE_SESSION
> + then \field{op_flf} is struct virtio_crypto_sym_create_session_flf if
> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_sym_create_session_flf if
> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
> + virtio_crypto_sym_create_session_vlf.
> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH_CREATE_SESSION
> + then \field{op_flf} is struct virtio_crypto_hash_create_session_flf if
> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_hash_create_session_flf if
> + padded to 56 bytes if NOT negotiated.
> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC_CREATE_SESSION
> + then \field{op_flf} is struct virtio_crypto_mac_create_session_flf if
> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_mac_create_session_flf if
> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
> + virtio_crypto_mac_create_session_vlf.
> +\end{itemize*}
> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_CREATE_SESSION
> + then \field{op_flf} is struct virtio_crypto_aead_create_session_flf if
> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_aead_create_session_flf if
> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
> + virtio_crypto_aead_create_session_vlf.
> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_DESTROY_SESSION
> + or VIRTIO_CRYPTO_HASH_DESTROY_SESSION or VIRTIO_CRYPTO_MAC_DESTROY_SESSION or
> + VIRTIO_CRYPTO_AEAD_DESTROY_SESSION then \field{op_flf} is struct
> + virtio_crypto_destroy_session_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated and
> + struct virtio_crypto_destroy_session_flf if padded to 56 bytes if NOT negotiated.
> +\end{itemize*}
> +
> +\field{op_outcome} stores the result of operation and must be struct
> +virtio_crypto_destroy_session_input for session-destroy operation or
> +struct virtio_crypto_session_input.
> +
> +\field{outcome_len} is the size of the structure used.
> +
> +
> +\paragraph{Session operation}\label{sec:Device Types / Crypto Device / Device
> +Operation / Control Virtqueue / Session operation}
> +
> +The session is a handle which describes the cryptographic parameters to be
> +applied to a number of buffers.
> +
> +The following structure stores the result of session creation set by the device:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_session_input {
> + /* Device write only portion */
I think you cann drop this comment along with the following similar
comments. We have already told whats device read only and what is
device write only in virtio_crypto_op_ctrl_req.
Restating it at each struct is redundant and IMHO just confusing. The
R/W is determined by where does the struct sit in the request.
> + 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_flf {
> + /* Device read only portion */
> + le64 session_id;
> +};
> +
> +struct virtio_crypto_destroy_session_input {
> + /* Device write only portion */
> + 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}
> +
> +The fixed-length paramenters of HASH session requests is as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_hash_create_session_flf {
> + /* Device read only portion */
> +
> + /* See VIRTIO_CRYPTO_HASH_* above */
> + le32 algo;
> + /* hash result length */
> + le32 hash_result_len;
> +};
> +\end{lstlisting}
> +
> +
> +\subparagraph{Session operation: MAC session}\label{sec:Device Types / Crypto Device / Device
> +Operation / Control Virtqueue / Session operation / Session operation: MAC session}
> +
> +The fixed-length and the variable-length parameters of MAC session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_mac_create_session_flf {
> + /* Device read only portion */
> +
> + /* 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_vlf {
> + /* Device read only portion */
> +
> + /* The authenticated key */
> + u8 auth_key[auth_key_len];
> +};
> +\end{lstlisting}
> +
> +The length of \field{auth_key} is specified in \field{auth_key_len} in the struct
> +virtio_crypto_mac_create_session_flf.
> +
> +
> +\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 could be the CIPHER algorithms request
> +or the chain algorithms (chaining CIPHER and HASH/MAC) request.
> +
> +The fixed-length and the variable-length parameters of CIPHER session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_cipher_session_flf {
> + /* Device read only portion */
> +
> + /* 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_vlf {
> + /* Device read only portion */
> +
> + /* The cipher key */
> + u8 cipher_key[keylen];
> +};
> +\end{lstlisting}
> +
> +The length of \field{cipher_key} is specified in \field{keylen} in the struct
> +virtio_crypto_cipher_session_flf.
> +
> +The fixed-length and the variable-length parameters of Chain session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_alg_chain_session_flf {
> + /* Device read only portion */
> +
> +#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_flf cipher_hdr;
> +
> +#define VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE 16
> + /* fixed length fields, algo specific */
> + u8 algo_flf[VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE];
> +
> + /* length of the additional authenticated data (AAD) in bytes */
> + le32 aad_len;
> + le32 padding;
> +};
> +
> +struct virtio_crypto_alg_chain_session_vlf {
> + /* Device read only portion */
> +
> + /* The cipher key */
> + u8 cipher_key[keylen];
> + /* The authenticated key */
> + u8 auth_key[auth_key_len];
> +};
> +\end{lstlisting}
> +
> +\field{hash_mode} decides the type used by \field{algo_flf}.
> +
> +\field{algo_flf} is fixed to 16 bytes and MUST contains or be one of
> +the following types:
> +\begin{itemize*}
> +\item struct virtio_crypto_hash_create_session_flf
> +\item struct virtio_crypto_mac_create_session_flf
> +\end{itemize*}
> +The data of unused part (if has) in \field{algo_flf} will be ignored.
> +
> +The length of \field{cipher_key} is specified in \field{keylen} in \field{cipher_hdr}.
> +
> +The length of \field{auth_key} is specified in \field{auth_key_len} in struct
> +virtio_crypto_mac_create_session_flf.
> +
> +The fixed-length parameters of Symmetric session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_sym_create_session_flf {
> + /* Device read only portion */
> +
> +#define VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE 48
> + /* fixed length fields, opcode specific */
> + u8 op_flf[VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE];
> +
> +/* 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}
> +
> +\field{op_flf} is fixed to 48 bytes, MUST contains or be one of
> +the following types:
> +\begin{itemize*}
> +\item struct virtio_crypto_cipher_session_flf
> +\item struct virtio_crypto_alg_chain_session_flf
> +\end{itemize*}
> +The data of unused part (if has) in \field{op_flf} will be ignored.
> +
> +\field{op_type} decides the type used by \field{op_flf}.
> +
> +The variable-length parameters of Symmetric session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_sym_create_session_vlf {
> + /* Device read only portion */
> + /* variable length fields, opcode specific */
> + u8 op_vlf[vlf_len];
> +};
> +\end{lstlisting}
> +
> +\field{op_vlf} MUST contains or be one of the following types:
> +\begin{itemize*}
> +\item struct virtio_crypto_cipher_session_vlf
> +\item struct virtio_crypto_alg_chain_session_vlf
> +\end{itemize*}
> +
> +\field{op_type} in struct virtio_crypto_sym_create_session_flf decides the
> +type used by \field{op_vlf}.
> +
> +\field{vlf_len} is the size of the specific structure used.
> +
> +
> +\subparagraph{Session operation: AEAD session}\label{sec:Device Types / Crypto Device / Device
> +Operation / Control Virtqueue / Session operation / Session operation: AEAD session}
> +
> +The fixed-length and the variable-length parameters of AEAD session requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_aead_create_session_flf {
> + /* Device read only portion */
> +
> + /* 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_vlf {
> + /* Device read only portion */
> + u8 key[key_len];
> +};
> +\end{lstlisting}
> +
> +The length of \field{key} is specified in \field{key_len} in struct
> +virtio_crypto_aead_create_session_flf.
> +
> +
> +\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 \field{opcode} field based on service type: CIPHER, HASH, MAC, or AEAD.
> +\item The driver MUST set the control general header, the opcode specific header,
> + the opcode specific extra parameters and the opcode specific outcome buffer in turn.
> + See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}.
> +\item The driver MUST set the \field{reversed} field to zero.
> +\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 use the corresponding opcode specific structure according to the
> + \field{opcode} in the control general header.
> +\item The device MUST extract extra parameters according to the structures used.
> +\item The device MUST set the \field{status} field to one of the following values of enum
> + VIRTIO_CRYPTO_STATUS after finish a session creation:
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
> +\item VIRTIO_CRYPTO_NOSPC if no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
> + feature bit is negotiated).
> +\item VIRTIO_CRYPTO_ERR if failure not mentioned above occurs.
> +\end{itemize*}
> +\item The device MUST set the \field{session_id} field to a unique session identifier only
> + if the status is set to VIRTIO_CRYPTO_OK.
> +\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 following values of enum VIRTIO_CRYPTO_STATUS.
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
> +\item VIRTIO_CRYPTO_ERR if any failure occurs.
> +\end{itemize*}
> +\end{itemize*}
> +
> +
> +\subsubsection{Data Virtqueue}\label{sec:Device Types / Crypto Device / Device Operation / Data Virtqueue}
> +
> +The driver uses the data virtqueues to transmit crypto operation requests to the device,
> +and completes the crypto operations.
> +
> +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_SESSION_MODE 1
> + /* control flag to control the request */
> + le32 flag;
> + le32 padding;
> +};
> +\end{lstlisting}
> +
> +\begin{note}
> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
> +is not negotiated then <SERVICE> retuqests with the \field{flag} (in struct
s/retuqests/requests
> +virtio_crypto_op_header) is ZERO need to be rejected. If VIRTIO_CRYPTO_F_REVISION_1 is
> +not negotiated the \field{flag} is ignored.
> +\end{note}
> +
I think your formulation is a bit hard to understand.
I would prefer:
+\begin{note}
+If VIRTIO_CRYPTO_F_REVISION_1 is not negotiated the \field{flag} is ignored.
+
+If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
+is not negotiated, then the device should reject <SERVICE> requests if
+VIRTIO_CRYPTO_FLAG_SESSION_MODE is not set (in \field{flag}).
+\end{note}
+
> +The dataq request is composed of four parts:
> +\begin{lstlisting}
> +struct virtio_crypto_op_data_req {
> + /* Device read only portion */
> +
> + struct virtio_crypto_op_header header;
> +
> +#define VIRTIO_CRYPTO_DATAQ_OP_SPEC_HDR_LEGACY 48
> + /* fixed length fields, opcode specific */
> + u8 op_flf[flf_len];
> +
> + /* Device read && write portion */
> + /* variable length fields, opcode specific */
> + u8 op_vlf[vlf_len];
Descriptors are either read or write. You need read && write (whatever the
sematic is) because you throw things together that don't belong together.
I would try to do the same as for the ctrl requests:
+ * Device write only portion */
+ u8 op_outcome;
and describe the outcome on a per service basis. Also see my
comments about the dst_data_len below.
> +
> + /* Device write only portion */
> + struct virtio_crypto_inhdr inhdr;
> +};
> +\end{lstlisting}
> +
> +\field{header} is a general header (see above).
> +
> +\field{op_flf} is the opcode (in \field{header}) specific header.
> +
> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit
> +(see below).
> +
> +\field{op_vlf} is the opcode (in \field{header}) specific parameters.
> +
> +\field{vlf_len} is the size of the specific structure used.
> +
> +\begin{itemize*}
> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_ENCRYPT
> + or VIRTIO_CRYPTO_CIPHER_DECRYPT then:
> + \begin{itemize*}
> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is negotiated, \field{op_flf} is
> + struct virtio_crypto_sym_data_flf_stateless, and \field{op_vlf} is struct
> + virtio_crypto_sym_data_vlf_stateless.
What does this _data_ (in the name) symbolise?
> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is NOT negotiated, \field{op_flf}
> + is struct virtio_crypto_sym_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
> + and struct virtio_crypto_sym_data_flf if padded to 48 bytes if NOT negotiated,
> + and \field{op_vlf} is struct virtio_crypto_sym_data_vlf.
> + \end{itemize*}
> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH:
> + \begin{itemize*}
> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is negotiated, \field{op_flf} is
> + struct virtio_crypto_hash_data_flf_stateless, and \field{op_vlf} is struct
> + virtio_crypto_hash_data_vlf_stateless.
> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is NOT negotiated, \field{op_flf}
> + is struct virtio_crypto_hash_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
> + and struct virtio_crypto_hash_data_flf if padded to 48 bytes if NOT negotiated,
> + and \field{op_vlf} is struct virtio_crypto_hash_data_vlf.
> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC:
> + \begin{itemize*}
> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is negotiated, \field{op_flf} is
> + struct virtio_crypto_mac_data_flf_stateless, and \field{op_vlf} is struct
> + virtio_crypto_mac_data_vlf_stateless.
> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is NOT negotiated, \field{op_flf}
> + is struct virtio_crypto_mac_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
> + and struct virtio_crypto_mac_data_flf if padded to 48 bytes if NOT negotiated,
> + and \field{op_vlf} is struct virtio_crypto_mac_data_vlf.
> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_ENCRYPT
> + or VIRTIO_CRYPTO_AEAD_DECRYPT then:
> + \begin{itemize*}
> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is negotiated, \field{op_flf} is
> + struct virtio_crypto_aead_data_flf_stateless, and \field{op_vlf} is struct
> + virtio_crypto_aead_data_vlf_stateless.
> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is NOT negotiated, \field{op_flf}
> + is struct virtio_crypto_aead_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
> + and struct virtio_crypto_aead_data_flf if padded to 48 bytes if NOT negotiated,
> + and \field{op_vlf} is struct virtio_crypto_aead_data_vlf.
> +\end{itemize*}
> +
> +\field{inhdr} is a unified input header that used to return the status of
> +the operations, 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_data_flf {
> + /* length of source data */
> + le32 src_data_len;
> + /* hash result length */
> + le32 hash_result_len;
> +};
> +
> +struct virtio_crypto_hash_data_vlf {
> + /* Device read only portion */
> + /* Source data */
> + u8 src_data[src_data_len];
> +
> + /* Device write only portion */
> + /* Hash result data */
> + u8 hash_result[hash_result_len];
> +};
> +\end{lstlisting}
> +
> +Each data request uses the virtio_crypto_hash_data_flf structure and the
> +virtio_crypto_hash_data_vlfto structure to store information used to run the
> +HASH operations.
> +
> +\field{src_data} is the source data that will be processed.
> +\field{src_data_len} is the length of source data.
> +\field{hash_result} is the result data and \field{hash_result_len} is the length
> +of it.
> +
> +Stateless mode HASH service requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_hash_data_flf_stateless {
> + 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_vlf_stateless {
> + /* Device read only portion */
> + /* Source data */
> + u8 src_data[src_data_len];
> +
> + /* Device write only portion */
> + /* Hash result data */
> + u8 hash_result[hash_result_len];
> +};
> +\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_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 ZERO and MUST set the fields in struct
> + virtio_crypto_hash_data_flf_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_SESSION_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 The device MUST use the corresponding structure according to the \field{opcode}
> + in the data general header.
> +\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
> + following values of enum VIRTIO_CRYPTO_STATUS:
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK if the operation success.
> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
> +\end{itemize*}
> +\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_data_flf {
> + struct virtio_crypto_hash_data_flf hdr;
> +};
> +
> +struct virtio_crypto_mac_data_vlf {
> + /* Device read only portion */
> + /* Source data */
> + u8 src_data[src_data_len];
> +
> + /* Device write only portion */
> + /* Hash result data */
> + u8 hash_result[hash_result_len];
> +};
> +\end{lstlisting}
> +
> +Each request uses the virtio_crypto_mac_data_flf structure and the
> +virtio_crypto_mac_data_vlf structure to store information used to run the
> +MAC operations.
> +
> +\field{src_data} is the source data that will be processed.
> +\field{src_data_len} is the length of source data.
> +\field{hash_result} is the result data and \field{hash_result_len} is the length
> +of it.
> +
> +Stateless mode MAC service requests are as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_mac_data_flf_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_vlf_stateless {
> + /* Device read only portion */
> + /* The authenticated key */
> + u8 auth_key[auth_key_len];
> + /* Source data */
> + u8 src_data[src_data_len];
> +
> + /* Device write only portion */
> + /* Hash result data */
> + u8 hash_result[hash_result_len];
> +};
> +\end{lstlisting}
> +
> +\field{auth_key} is the authenticated key that will be used during the process.
> +\field{auth_key_len} is the length of the key.
> +
> +\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_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 ZERO and MUST set the fields in struct
> + virtio_crypto_mac_data_flf_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_SESSION_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_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
> + following values of enum VIRTIO_CRYPTO_STATUS:
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK if the operation success.
> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
> +\end{itemize*}
> +\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_data_flf {
> + /*
> + * 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_vlf {
> + /* Device read only portion */
> +
> + /*
> + * 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 write only portion */
> + /* Destination data */
> + u8 dst_data[dst_data_len];
I'm a bit puzzled about dst_data_len. I'm by no means a crypto expert,
and that is probably the very reason of my discomfort.
I've tried to figure out how dst_data_len is used and expected to find
a place that checks, that at least a sufficiently large buffer was provided.
I've also assumed that the src_data_len is likely to imply the dst_data_len
for any given algorithm. Furthermore, I even hypothesised that the both
lengths are the same. All based on what I remember about block ciphers.
If that hypothesis is right, then I don't understand why do we need
both src_data_len and dst_data_len.
Since dst_data_len is device read only, the driver I figure the driver
needs to know the exact length (since I cant figure out, based on this
spec, how is it supposed to be told by the device which part of the
buffer is the result and which part garbage). So the only sane usage
I was able to come up with is to avoid the device overwritting other
parts of the requests device writtable part because of a driver
bug (wrong dst_data_len). But as I've said I could not find the corresponding
code in qemu.
Anyway providing some more background for the guys only superficially
involved with crypto (like me) would be appreciated.
I will stop here for now. I read the rest real quick and I did not
see anything major. I think we are slowly getting there.
Regards,
Halil
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-01-09 17:05 ` [virtio-dev] " Halil Pasic
@ 2018-01-09 17:41 ` Michael S. Tsirkin
-1 siblings, 0 replies; 31+ messages in thread
From: Michael S. Tsirkin @ 2018-01-09 17:41 UTC (permalink / raw)
To: Halil Pasic
Cc: Longpeng(Mike),
qemu-devel, virtio-dev, luonengjun, cornelia.huck, stefanha,
denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On Tue, Jan 09, 2018 at 06:05:41PM +0100, Halil Pasic wrote:
> > +\drivernormative{\subsubsection}{Device configuration layout}{Device Types / Crypto Device / Device configuration layout}
> > +
> > +\begin{itemize*}
> > +\item The driver MUST read the \field{status} from the bottom bit of status to check whether the
> > + VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
> > +\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD ignore the not defined algorithms bits.
> > +\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*}
>
> Seems to like a common practice in the virtio spec to say SHOULD read some
> config space parameter in a driver normative but then having no driver normative
> about the operational implications of the parameter.
>
> While I do think that the reader is usually fully capable of inferring
> the operational requirement, I find it a bit strange: having the operational
> stuff explicit (and possibly needs to be read from the config space implicit)
> seems more straight forward to me.
>
> Anyway, you are consistent with the rest of the spec, so prefer keeping it
> like this.
The reason for this in virtio generally is that driver is really
only required to be consistent with the device.
Something like reading the value once and storing in e.g.
registry, then using the stored value from registry on
following values seems to also be ok.
Restricting values below the limits allowed by the device
also seems to be ok.
^ permalink raw reply [flat|nested] 31+ messages in thread
* [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-01-09 17:41 ` Michael S. Tsirkin
0 siblings, 0 replies; 31+ messages in thread
From: Michael S. Tsirkin @ 2018-01-09 17:41 UTC (permalink / raw)
To: Halil Pasic
Cc: Longpeng(Mike),
qemu-devel, virtio-dev, luonengjun, cornelia.huck, stefanha,
denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On Tue, Jan 09, 2018 at 06:05:41PM +0100, Halil Pasic wrote:
> > +\drivernormative{\subsubsection}{Device configuration layout}{Device Types / Crypto Device / Device configuration layout}
> > +
> > +\begin{itemize*}
> > +\item The driver MUST read the \field{status} from the bottom bit of status to check whether the
> > + VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
> > +\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD ignore the not defined algorithms bits.
> > +\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*}
>
> Seems to like a common practice in the virtio spec to say SHOULD read some
> config space parameter in a driver normative but then having no driver normative
> about the operational implications of the parameter.
>
> While I do think that the reader is usually fully capable of inferring
> the operational requirement, I find it a bit strange: having the operational
> stuff explicit (and possibly needs to be read from the config space implicit)
> seems more straight forward to me.
>
> Anyway, you are consistent with the rest of the spec, so prefer keeping it
> like this.
The reason for this in virtio generally is that driver is really
only required to be consistent with the device.
Something like reading the value once and storing in e.g.
registry, then using the stored value from registry on
following values seems to also be ok.
Restricting values below the limits allowed by the device
also seems to be ok.
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-01-09 17:05 ` [virtio-dev] " Halil Pasic
@ 2018-01-10 5:53 ` Longpeng (Mike)
-1 siblings, 0 replies; 31+ messages in thread
From: Longpeng (Mike) @ 2018-01-10 5:53 UTC (permalink / raw)
To: Halil Pasic
Cc: qemu-devel, virtio-dev, luonengjun, mst, cornelia.huck, stefanha,
denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
Hi Halil,
We are fixing the Intel BUG these days, so I will go through your comments after
we're done. Thanks.
--
Regards,
Longpeng(Mike)
On 2018/1/10 1:05, Halil Pasic wrote:
>
>
> On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
>> From: Gonglei <arei.gonglei@huawei.com>
>>
>> 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 <arei.gonglei@huawei.com>
>> Signed-off-by: Zhoujian <jianjay.zhou@huawei.com>
>> Signed-off-by: Longpeng(Mike) <longpeng2@huawei.com>
>> ---
>> acknowledgements.tex | 4 +
>> content.tex | 2 +
>> virtio-crypto.tex | 1525 ++++++++++++++++++++++++++++++++++++++++++++++++++
>> 3 files changed, 1531 insertions(+)
>> create mode 100644 virtio-crypto.tex
>>
>> diff --git a/acknowledgements.tex b/acknowledgements.tex
>> index 2d893d9..cdde247 100644
>> --- a/acknowledgements.tex
>> +++ b/acknowledgements.tex
>> @@ -16,10 +16,13 @@ Daniel Kiper, Oracle \newline
>> Geoff Brown, Machine-to-Machine Intelligence (M2MI) Corporation \newline
>> Gershon Janssen, Individual Member \newline
>> James Bottomley, Parallels IP Holdings GmbH \newline
>> +Jian Zhou, Huawei \newline
>> +Lei Gong, Huawei \newline
>> Luiz Capitulino, Red Hat \newline
>> Michael S. Tsirkin, Red Hat \newline
>> Paolo Bonzini, Red Hat \newline
>> Pawel Moll, ARM \newline
>> +Peng Long, Huawei \newline
>> Richard Sohn, Alcatel-Lucent \newline
>> Rusty Russell, IBM \newline
>> Sasha Levin, Oracle \newline
>> @@ -38,6 +41,7 @@ Brian Foley, ARM \newline
>> David Alan Gilbert, Red Hat \newline
>> Fam Zheng, Red Hat \newline
>> Gerd Hoffmann, Red Hat \newline
>> +Halil Pasic, IBM \newline
>> Jason Wang, Red Hat \newline
>> Laura Novich, Red Hat \newline
>> Patrick Durusau, Technical Advisory Board, OASIS \newline
>> diff --git a/content.tex b/content.tex
>> index c840588..d1d3b09 100644
>> --- a/content.tex
>> +++ b/content.tex
>> @@ -5819,6 +5819,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 these device-independent feature bits defined:
>> diff --git a/virtio-crypto.tex b/virtio-crypto.tex
>> new file mode 100644
>> index 0000000..4bd5b51
>> --- /dev/null
>> +++ b/virtio-crypto.tex
>> @@ -0,0 +1,1525 @@
>> +\section{Crypto Device}\label{sec:Device Types / Crypto Device}
>> +
>> +The virtio crypto device is a virtual cryptography device as well as a
>> +virtual cryptographic accelerator. The virtio crypto device provides the
>> +following crypto services: CIPHER, MAC, HASH, and AEAD. Virtio crypto
>> +devices have a single control queue and at least one data queue. Crypto
>> +operation requests are placed into a data queue, and serviced by the
>> +device. Some crypto operation requests are only valid in the context of a
>> +session. The role of the control queue is facilitating control operation
>> +requests. Sessions management is realized with control operation
>> +requests.
>> +
>> +\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}
>> +
>> +\begin{description}
>> +\item VIRTIO_CRYPTO_F_REVISION_1 (0) revision 1. Revision 1 has a specific
>> + request format and other enhancements (which result in some additional
>> + requirements).
>> +\item VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE (1) stateless mode requests are
>> + supported by the CIPHER service.
>> +\item VIRTIO_CRYPTO_F_HASH_STATELESS_MODE (2) stateless mode requests are
>> + supported by the HASH service.
>> +\item VIRTIO_CRYPTO_F_MAC_STATELESS_MODE (3) stateless mode requests are
>> + supported by the MAC service.
>> +\item VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE (4) stateless mode requests are
>> + supported by the AEAD service.
>> +\end{description}
>> +
>> +
>> +\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_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_HASH_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_MAC_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\end{description}
>> +
>> +\subsection{Supported crypto services}\label{sec:Device Types / Crypto Device / Supported crypto services}
>> +
>> +The following crypto services are defined:
>> +
>> +\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 designate bits used to indicate the which of crypto services are
>> +offered by the device as described in, 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 designate the algorithm in (CIPHER type) crypto
>> +operation requests, 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 designate the algorithm in (HASH type) crypto
>> +operation 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 designate the algorithm in (MAC type) crypto
>> +operation requests, 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 designate the algorithm in (DEAD type) crypto
>> +operation requests, 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 Currently, only one \field(status) bit is defined: VIRTIO_CRYPTO_S_HW_READY
>> + set indicates that the device is ready to process requests, this bit is read-only
>> + for the driver
>> +\begin{lstlisting}
>> +#define VIRTIO_CRYPTO_S_HW_READY (1 << 0)
>> +\end{lstlisting}
>> +
>> +\item[\field{max_dataqueues}] is the maximum number of data virtqueues that can
>> + be configured by the device. The driver MAY use only one data queue, or it
>> + can use more to achieve better performance.
>> +
>> +\item[\field{crypto_services}] crypto service offered, see \ref{sec:Device Types / Crypto Device / Supported crypto services}.
>> +
>> +\item[\field{cipher_algo_l}] CIPHER algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
>> +
>> +\item[\field{cipher_algo_h}] CIPHER algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
>> +
>> +\item[\field{hash_algo}] HASH algorithms bits, see \ref{sec:Device Types / Crypto Device / Supported crypto services / HASH services}.
>> +
>> +\item[\field{mac_algo_l}] MAC algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
>> +
>> +\item[\field{mac_algo_h}] MAC algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
>> +
>> +\item[\field{aead_algo}] AEAD algorithms bits, 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.
>
> I can't find what happens if this limit isn't honored by the driver. Moreover
> reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
> such requests? I think in qemu implementation we fail the request.
>
> This question is only about niceness. We are already good enough, IMHO:
> since the implementer of the driver can't be sure what is going to happen
> if the driver disregards max_cipher_key_len it is already an implicit
> SHOULD.
>
>> +
>> +\item[\field{max_auth_key_len}] is the maximum length of authenticated key supported by the device.
>
> Same here.
>
>> +
>> +\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
>
> s/device/device.
>
> What a content of a request and how is its size calculated? Where is this defined.
>
> The question what happens if not honored applies similarly.
>
>> +\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 the \field{status} with valid flags, undefined flags MUST NOT be set.
>> +\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 for each service advertised by \field{crypto_services}.
>> + The device MUST NOT set the not defined algorithms bits.
>> +\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 \field{status} from the bottom bit of status to check whether the
>> + VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
>> +\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD ignore the not defined algorithms bits.
>> +\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*}
>
> Seems to like a common practice in the virtio spec to say SHOULD read some
> config space parameter in a driver normative but then having no driver normative
> about the operational implications of the parameter.
>
> While I do think that the reader is usually fully capable of inferring
> the operational requirement, I find it a bit strange: having the operational
> stuff explicit (and possibly needs to be read from the config space implicit)
> seems more straight forward to me.
>
> Anyway, you are consistent with the rest of the spec, so prefer keeping it
> like this.
>
>
>> +
>> +\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 configure 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}
>> +
>> +The operation of a virtio crypto device is driven by requests placed on the virtqueues.
>> +Requests consist of a queue-type specific header (specifying among others the operation)
>> +and an operation specific payload.
>> +
>> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated the device may support both session mode
>> +(See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation})
>> +and stateless mode operation requests.
>> +In stateless mode all operation parameters are supplied as a part of each request,
>> +while in session mode, some or all operation parameters are managed within the
>> +session. Stateless mode is guarded by feature bits 0-4 on a service level. If
>> +stateless mode is negotiated for a service, the service is available both in
>> +session and stateless mode; otherwise it's only available in session mode.
>
> How about the following?
>
> """
> If stateless mode is negotiated for a service, the service accepts both session mode and stateless
> requests; otherwise stateless mode requests are rejected (via operation status).
> """
>
> I prefer it because i think it makes clearer than session mode and stateless
> mode are concepts that apply on request and not on service (or let's say queue)
> level.
>
>> +
>> +\subsubsection{Operation Status}\label{sec:Device Types / Crypto Device / Device Operation / Operation status}
>> +The device MUST return a status code as part of the operation (both session
>> +operation and service operation) result. The valid operation status as follows:
>> +
>> +\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_NOSPC = 5,
>> + VIRTIO_CRYPTO_MAX
>> +};
>> +\end{lstlisting}
>> +
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK: success.
>> +\item VIRTIO_CRYPTO_BADMSG: authentication failed (only when AEAD decryption).
>> +\item VIRTIO_CRYPTO_NOTSUPP: operation or algorithm is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto operations.
>> +\item VIRTIO_CRYPTO_NOSPC: no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
>> + feature bit is negotiated).
>> +\item VIRTIO_CRYPTO_ERR: any failure not mentioned above occurs.
>> +\end{itemize*}
>> +
>
> Just thinking loud: We don't seem to be able to differentiate between device
> detected a driver (guest) bug, and something went wrong with the backend.
> I'm not sure differentiating between the two is useful in the first place.
>
>> +\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}).
>> +
>> +The header for controlq is of the following form:
>> +\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;
>> + le32 reserved;
>> +};
>> +\end{lstlisting}
>> +
>> +The controlq request is composed of four parts:
>> +\begin{lstlisting}
>> +struct virtio_crypto_op_ctrl_req {
>> + /* Device read only portion */
>> +
>> + struct virtio_crypto_ctrl_header header;
>> +
>> +#define VIRTIO_CRYPTO_CTRLQ_OP_SPEC_HDR_LEGACY 56
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[flf_len];
>> +
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>> +
>> + /* Device write only portion */
>> +
>> + /* op result or completion status */
>> + u8 op_outcome[outcome_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{header} is a general header (see above).
>> +
>> +\field{op_flf} is the opcode (in \field{header}) specific fixed-length paramenters.
>> +
>> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit (see below).
>> +
>> +\field{op_vlf} is the opcode (in \field{header}) specific variable-length paramenters.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +\begin{note}
>> +The \field{vlf_len} of session-destroy operation and the hash-session-create
>> +operation is ZERO.
>> +\end{note}
>> +
>> +\begin{itemize*}
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_sym_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_sym_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_sym_create_session_vlf.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_hash_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_hash_create_session_flf if
>> + padded to 56 bytes if NOT negotiated.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_mac_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_mac_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_mac_create_session_vlf.
>> +\end{itemize*}
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_aead_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_aead_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_aead_create_session_vlf.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_DESTROY_SESSION
>> + or VIRTIO_CRYPTO_HASH_DESTROY_SESSION or VIRTIO_CRYPTO_MAC_DESTROY_SESSION or
>> + VIRTIO_CRYPTO_AEAD_DESTROY_SESSION then \field{op_flf} is struct
>> + virtio_crypto_destroy_session_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated and
>> + struct virtio_crypto_destroy_session_flf if padded to 56 bytes if NOT negotiated.
>> +\end{itemize*}
>> +
>> +\field{op_outcome} stores the result of operation and must be struct
>> +virtio_crypto_destroy_session_input for session-destroy operation or
>> +struct virtio_crypto_session_input.
>> +
>> +\field{outcome_len} is the size of the structure used.
>> +
>> +
>> +\paragraph{Session operation}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation}
>> +
>> +The session is a handle which describes the cryptographic parameters to be
>> +applied to a number of buffers.
>> +
>> +The following structure stores the result of session creation set by the device:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_session_input {
>> + /* Device write only portion */
>
> I think you cann drop this comment along with the following similar
> comments. We have already told whats device read only and what is
> device write only in virtio_crypto_op_ctrl_req.
>
> Restating it at each struct is redundant and IMHO just confusing. The
> R/W is determined by where does the struct sit in the request.
>
>> + 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_flf {
>> + /* Device read only portion */
>> + le64 session_id;
>> +};
>> +
>> +struct virtio_crypto_destroy_session_input {
>> + /* Device write only portion */
>> + 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}
>> +
>> +The fixed-length paramenters of HASH session requests is as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_hash_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* See VIRTIO_CRYPTO_HASH_* above */
>> + le32 algo;
>> + /* hash result length */
>> + le32 hash_result_len;
>> +};
>> +\end{lstlisting}
>> +
>> +
>> +\subparagraph{Session operation: MAC session}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation / Session operation: MAC session}
>> +
>> +The fixed-length and the variable-length parameters of MAC session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_mac_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> +
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{auth_key} is specified in \field{auth_key_len} in the struct
>> +virtio_crypto_mac_create_session_flf.
>> +
>> +
>> +\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 could be the CIPHER algorithms request
>> +or the chain algorithms (chaining CIPHER and HASH/MAC) request.
>> +
>> +The fixed-length and the variable-length parameters of CIPHER session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_cipher_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> +
>> + /* The cipher key */
>> + u8 cipher_key[keylen];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{cipher_key} is specified in \field{keylen} in the struct
>> +virtio_crypto_cipher_session_flf.
>> +
>> +The fixed-length and the variable-length parameters of Chain session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_alg_chain_session_flf {
>> + /* Device read only portion */
>> +
>> +#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_flf cipher_hdr;
>> +
>> +#define VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE 16
>> + /* fixed length fields, algo specific */
>> + u8 algo_flf[VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE];
>> +
>> + /* length of the additional authenticated data (AAD) in bytes */
>> + le32 aad_len;
>> + le32 padding;
>> +};
>> +
>> +struct virtio_crypto_alg_chain_session_vlf {
>> + /* Device read only portion */
>> +
>> + /* The cipher key */
>> + u8 cipher_key[keylen];
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{hash_mode} decides the type used by \field{algo_flf}.
>> +
>> +\field{algo_flf} is fixed to 16 bytes and MUST contains or be one of
>> +the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_hash_create_session_flf
>> +\item struct virtio_crypto_mac_create_session_flf
>> +\end{itemize*}
>> +The data of unused part (if has) in \field{algo_flf} will be ignored.
>> +
>> +The length of \field{cipher_key} is specified in \field{keylen} in \field{cipher_hdr}.
>> +
>> +The length of \field{auth_key} is specified in \field{auth_key_len} in struct
>> +virtio_crypto_mac_create_session_flf.
>> +
>> +The fixed-length parameters of Symmetric session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_sym_create_session_flf {
>> + /* Device read only portion */
>> +
>> +#define VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE 48
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE];
>> +
>> +/* 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}
>> +
>> +\field{op_flf} is fixed to 48 bytes, MUST contains or be one of
>> +the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_cipher_session_flf
>> +\item struct virtio_crypto_alg_chain_session_flf
>> +\end{itemize*}
>> +The data of unused part (if has) in \field{op_flf} will be ignored.
>> +
>> +\field{op_type} decides the type used by \field{op_flf}.
>> +
>> +The variable-length parameters of Symmetric session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_sym_create_session_vlf {
>> + /* Device read only portion */
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{op_vlf} MUST contains or be one of the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_cipher_session_vlf
>> +\item struct virtio_crypto_alg_chain_session_vlf
>> +\end{itemize*}
>> +
>> +\field{op_type} in struct virtio_crypto_sym_create_session_flf decides the
>> +type used by \field{op_vlf}.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +
>> +
>> +\subparagraph{Session operation: AEAD session}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation / Session operation: AEAD session}
>> +
>> +The fixed-length and the variable-length parameters of AEAD session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_aead_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> + u8 key[key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{key} is specified in \field{key_len} in struct
>> +virtio_crypto_aead_create_session_flf.
>> +
>> +
>> +\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 \field{opcode} field based on service type: CIPHER, HASH, MAC, or AEAD.
>> +\item The driver MUST set the control general header, the opcode specific header,
>> + the opcode specific extra parameters and the opcode specific outcome buffer in turn.
>> + See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}.
>> +\item The driver MUST set the \field{reversed} field to zero.
>> +\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 use the corresponding opcode specific structure according to the
>> + \field{opcode} in the control general header.
>> +\item The device MUST extract extra parameters according to the structures used.
>> +\item The device MUST set the \field{status} field to one of the following values of enum
>> + VIRTIO_CRYPTO_STATUS after finish a session creation:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_NOSPC if no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
>> + feature bit is negotiated).
>> +\item VIRTIO_CRYPTO_ERR if failure not mentioned above occurs.
>> +\end{itemize*}
>> +\item The device MUST set the \field{session_id} field to a unique session identifier only
>> + if the status is set to VIRTIO_CRYPTO_OK.
>> +\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 following values of enum VIRTIO_CRYPTO_STATUS.
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
>> +\item VIRTIO_CRYPTO_ERR if any failure occurs.
>> +\end{itemize*}
>> +\end{itemize*}
>> +
>> +
>> +\subsubsection{Data Virtqueue}\label{sec:Device Types / Crypto Device / Device Operation / Data Virtqueue}
>> +
>> +The driver uses the data virtqueues to transmit crypto operation requests to the device,
>> +and completes the crypto operations.
>> +
>> +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_SESSION_MODE 1
>> + /* control flag to control the request */
>> + le32 flag;
>> + le32 padding;
>> +};
>> +\end{lstlisting}
>> +
>> +\begin{note}
>> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
>> +is not negotiated then <SERVICE> retuqests with the \field{flag} (in struct
>
>
> s/retuqests/requests
>
>> +virtio_crypto_op_header) is ZERO need to be rejected. If VIRTIO_CRYPTO_F_REVISION_1 is
>> +not negotiated the \field{flag} is ignored.
>> +\end{note}
>> +
>
> I think your formulation is a bit hard to understand.
>
> I would prefer:
> +\begin{note}
> +If VIRTIO_CRYPTO_F_REVISION_1 is not negotiated the \field{flag} is ignored.
> +
> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
> +is not negotiated, then the device should reject <SERVICE> requests if
> +VIRTIO_CRYPTO_FLAG_SESSION_MODE is not set (in \field{flag}).
> +\end{note}
> +
>
>> +The dataq request is composed of four parts:
>> +\begin{lstlisting}
>> +struct virtio_crypto_op_data_req {
>> + /* Device read only portion */
>> +
>> + struct virtio_crypto_op_header header;
>> +
>> +#define VIRTIO_CRYPTO_DATAQ_OP_SPEC_HDR_LEGACY 48
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[flf_len];
>> +
>> + /* Device read && write portion */
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>
> Descriptors are either read or write. You need read && write (whatever the
> sematic is) because you throw things together that don't belong together.
>
> I would try to do the same as for the ctrl requests:
> + * Device write only portion */
> + u8 op_outcome;
>
> and describe the outcome on a per service basis. Also see my
> comments about the dst_data_len below.
>
>> +
>> + /* Device write only portion */
>> + struct virtio_crypto_inhdr inhdr;
>> +};
>> +\end{lstlisting}
>> +
>> +\field{header} is a general header (see above).
>> +
>> +\field{op_flf} is the opcode (in \field{header}) specific header.
>> +
>> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit
>> +(see below).
>> +
>> +\field{op_vlf} is the opcode (in \field{header}) specific parameters.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +
>> +\begin{itemize*}
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_ENCRYPT
>> + or VIRTIO_CRYPTO_CIPHER_DECRYPT then:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_sym_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_sym_data_vlf_stateless.
>
> What does this _data_ (in the name) symbolise?
>
>> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_sym_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_sym_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_sym_data_vlf.
>> + \end{itemize*}
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_hash_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_hash_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_hash_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_hash_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_hash_data_vlf.
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_mac_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_mac_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_mac_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_mac_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_mac_data_vlf.
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_ENCRYPT
>> + or VIRTIO_CRYPTO_AEAD_DECRYPT then:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_aead_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_aead_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_aead_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_aead_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_aead_data_vlf.
>> +\end{itemize*}
>> +
>> +\field{inhdr} is a unified input header that used to return the status of
>> +the operations, 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_data_flf {
>> + /* length of source data */
>> + le32 src_data_len;
>> + /* hash result length */
>> + le32 hash_result_len;
>> +};
>> +
>> +struct virtio_crypto_hash_data_vlf {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +Each data request uses the virtio_crypto_hash_data_flf structure and the
>> +virtio_crypto_hash_data_vlfto structure to store information used to run the
>> +HASH operations.
>> +
>> +\field{src_data} is the source data that will be processed.
>> +\field{src_data_len} is the length of source data.
>> +\field{hash_result} is the result data and \field{hash_result_len} is the length
>> +of it.
>> +
>> +Stateless mode HASH service requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_hash_data_flf_stateless {
>> + 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_vlf_stateless {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\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_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 ZERO and MUST set the fields in struct
>> + virtio_crypto_hash_data_flf_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_SESSION_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 The device MUST use the corresponding structure according to the \field{opcode}
>> + in the data general header.
>> +\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
>> + following values of enum VIRTIO_CRYPTO_STATUS:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if the operation success.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
>> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
>> +\end{itemize*}
>> +\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_data_flf {
>> + struct virtio_crypto_hash_data_flf hdr;
>> +};
>> +
>> +struct virtio_crypto_mac_data_vlf {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +Each request uses the virtio_crypto_mac_data_flf structure and the
>> +virtio_crypto_mac_data_vlf structure to store information used to run the
>> +MAC operations.
>> +
>> +\field{src_data} is the source data that will be processed.
>> +\field{src_data_len} is the length of source data.
>> +\field{hash_result} is the result data and \field{hash_result_len} is the length
>> +of it.
>> +
>> +Stateless mode MAC service requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_mac_data_flf_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_vlf_stateless {
>> + /* Device read only portion */
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{auth_key} is the authenticated key that will be used during the process.
>> +\field{auth_key_len} is the length of the key.
>> +
>> +\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_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 ZERO and MUST set the fields in struct
>> + virtio_crypto_mac_data_flf_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_SESSION_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_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
>> + following values of enum VIRTIO_CRYPTO_STATUS:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if the operation success.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
>> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
>> +\end{itemize*}
>> +\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_data_flf {
>> + /*
>> + * 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_vlf {
>> + /* Device read only portion */
>> +
>> + /*
>> + * 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 write only portion */
>> + /* Destination data */
>> + u8 dst_data[dst_data_len];
>
>
> I'm a bit puzzled about dst_data_len. I'm by no means a crypto expert,
> and that is probably the very reason of my discomfort.
>
> I've tried to figure out how dst_data_len is used and expected to find
> a place that checks, that at least a sufficiently large buffer was provided.
>
> I've also assumed that the src_data_len is likely to imply the dst_data_len
> for any given algorithm. Furthermore, I even hypothesised that the both
> lengths are the same. All based on what I remember about block ciphers.
>
> If that hypothesis is right, then I don't understand why do we need
> both src_data_len and dst_data_len.
>
> Since dst_data_len is device read only, the driver I figure the driver
> needs to know the exact length (since I cant figure out, based on this
> spec, how is it supposed to be told by the device which part of the
> buffer is the result and which part garbage). So the only sane usage
> I was able to come up with is to avoid the device overwritting other
> parts of the requests device writtable part because of a driver
> bug (wrong dst_data_len). But as I've said I could not find the corresponding
> code in qemu.
>
> Anyway providing some more background for the guys only superficially
> involved with crypto (like me) would be appreciated.
>
> I will stop here for now. I read the rest real quick and I did not
> see anything major. I think we are slowly getting there.
>
> Regards,
> Halil
>
>
> .
>
--
Regards,
Longpeng(Mike)
^ permalink raw reply [flat|nested] 31+ messages in thread
* [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-01-10 5:53 ` Longpeng (Mike)
0 siblings, 0 replies; 31+ messages in thread
From: Longpeng (Mike) @ 2018-01-10 5:53 UTC (permalink / raw)
To: Halil Pasic
Cc: qemu-devel, virtio-dev, luonengjun, mst, cornelia.huck, stefanha,
denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
Hi Halil,
We are fixing the Intel BUG these days, so I will go through your comments after
we're done. Thanks.
--
Regards,
Longpeng(Mike)
On 2018/1/10 1:05, Halil Pasic wrote:
>
>
> On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
>> From: Gonglei <arei.gonglei@huawei.com>
>>
>> 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 <arei.gonglei@huawei.com>
>> Signed-off-by: Zhoujian <jianjay.zhou@huawei.com>
>> Signed-off-by: Longpeng(Mike) <longpeng2@huawei.com>
>> ---
>> acknowledgements.tex | 4 +
>> content.tex | 2 +
>> virtio-crypto.tex | 1525 ++++++++++++++++++++++++++++++++++++++++++++++++++
>> 3 files changed, 1531 insertions(+)
>> create mode 100644 virtio-crypto.tex
>>
>> diff --git a/acknowledgements.tex b/acknowledgements.tex
>> index 2d893d9..cdde247 100644
>> --- a/acknowledgements.tex
>> +++ b/acknowledgements.tex
>> @@ -16,10 +16,13 @@ Daniel Kiper, Oracle \newline
>> Geoff Brown, Machine-to-Machine Intelligence (M2MI) Corporation \newline
>> Gershon Janssen, Individual Member \newline
>> James Bottomley, Parallels IP Holdings GmbH \newline
>> +Jian Zhou, Huawei \newline
>> +Lei Gong, Huawei \newline
>> Luiz Capitulino, Red Hat \newline
>> Michael S. Tsirkin, Red Hat \newline
>> Paolo Bonzini, Red Hat \newline
>> Pawel Moll, ARM \newline
>> +Peng Long, Huawei \newline
>> Richard Sohn, Alcatel-Lucent \newline
>> Rusty Russell, IBM \newline
>> Sasha Levin, Oracle \newline
>> @@ -38,6 +41,7 @@ Brian Foley, ARM \newline
>> David Alan Gilbert, Red Hat \newline
>> Fam Zheng, Red Hat \newline
>> Gerd Hoffmann, Red Hat \newline
>> +Halil Pasic, IBM \newline
>> Jason Wang, Red Hat \newline
>> Laura Novich, Red Hat \newline
>> Patrick Durusau, Technical Advisory Board, OASIS \newline
>> diff --git a/content.tex b/content.tex
>> index c840588..d1d3b09 100644
>> --- a/content.tex
>> +++ b/content.tex
>> @@ -5819,6 +5819,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 these device-independent feature bits defined:
>> diff --git a/virtio-crypto.tex b/virtio-crypto.tex
>> new file mode 100644
>> index 0000000..4bd5b51
>> --- /dev/null
>> +++ b/virtio-crypto.tex
>> @@ -0,0 +1,1525 @@
>> +\section{Crypto Device}\label{sec:Device Types / Crypto Device}
>> +
>> +The virtio crypto device is a virtual cryptography device as well as a
>> +virtual cryptographic accelerator. The virtio crypto device provides the
>> +following crypto services: CIPHER, MAC, HASH, and AEAD. Virtio crypto
>> +devices have a single control queue and at least one data queue. Crypto
>> +operation requests are placed into a data queue, and serviced by the
>> +device. Some crypto operation requests are only valid in the context of a
>> +session. The role of the control queue is facilitating control operation
>> +requests. Sessions management is realized with control operation
>> +requests.
>> +
>> +\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}
>> +
>> +\begin{description}
>> +\item VIRTIO_CRYPTO_F_REVISION_1 (0) revision 1. Revision 1 has a specific
>> + request format and other enhancements (which result in some additional
>> + requirements).
>> +\item VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE (1) stateless mode requests are
>> + supported by the CIPHER service.
>> +\item VIRTIO_CRYPTO_F_HASH_STATELESS_MODE (2) stateless mode requests are
>> + supported by the HASH service.
>> +\item VIRTIO_CRYPTO_F_MAC_STATELESS_MODE (3) stateless mode requests are
>> + supported by the MAC service.
>> +\item VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE (4) stateless mode requests are
>> + supported by the AEAD service.
>> +\end{description}
>> +
>> +
>> +\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_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_HASH_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_MAC_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\end{description}
>> +
>> +\subsection{Supported crypto services}\label{sec:Device Types / Crypto Device / Supported crypto services}
>> +
>> +The following crypto services are defined:
>> +
>> +\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 designate bits used to indicate the which of crypto services are
>> +offered by the device as described in, 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 designate the algorithm in (CIPHER type) crypto
>> +operation requests, 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 designate the algorithm in (HASH type) crypto
>> +operation 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 designate the algorithm in (MAC type) crypto
>> +operation requests, 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 designate the algorithm in (DEAD type) crypto
>> +operation requests, 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 Currently, only one \field(status) bit is defined: VIRTIO_CRYPTO_S_HW_READY
>> + set indicates that the device is ready to process requests, this bit is read-only
>> + for the driver
>> +\begin{lstlisting}
>> +#define VIRTIO_CRYPTO_S_HW_READY (1 << 0)
>> +\end{lstlisting}
>> +
>> +\item[\field{max_dataqueues}] is the maximum number of data virtqueues that can
>> + be configured by the device. The driver MAY use only one data queue, or it
>> + can use more to achieve better performance.
>> +
>> +\item[\field{crypto_services}] crypto service offered, see \ref{sec:Device Types / Crypto Device / Supported crypto services}.
>> +
>> +\item[\field{cipher_algo_l}] CIPHER algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
>> +
>> +\item[\field{cipher_algo_h}] CIPHER algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
>> +
>> +\item[\field{hash_algo}] HASH algorithms bits, see \ref{sec:Device Types / Crypto Device / Supported crypto services / HASH services}.
>> +
>> +\item[\field{mac_algo_l}] MAC algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
>> +
>> +\item[\field{mac_algo_h}] MAC algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
>> +
>> +\item[\field{aead_algo}] AEAD algorithms bits, 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.
>
> I can't find what happens if this limit isn't honored by the driver. Moreover
> reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
> such requests? I think in qemu implementation we fail the request.
>
> This question is only about niceness. We are already good enough, IMHO:
> since the implementer of the driver can't be sure what is going to happen
> if the driver disregards max_cipher_key_len it is already an implicit
> SHOULD.
>
>> +
>> +\item[\field{max_auth_key_len}] is the maximum length of authenticated key supported by the device.
>
> Same here.
>
>> +
>> +\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
>
> s/device/device.
>
> What a content of a request and how is its size calculated? Where is this defined.
>
> The question what happens if not honored applies similarly.
>
>> +\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 the \field{status} with valid flags, undefined flags MUST NOT be set.
>> +\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 for each service advertised by \field{crypto_services}.
>> + The device MUST NOT set the not defined algorithms bits.
>> +\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 \field{status} from the bottom bit of status to check whether the
>> + VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
>> +\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD ignore the not defined algorithms bits.
>> +\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*}
>
> Seems to like a common practice in the virtio spec to say SHOULD read some
> config space parameter in a driver normative but then having no driver normative
> about the operational implications of the parameter.
>
> While I do think that the reader is usually fully capable of inferring
> the operational requirement, I find it a bit strange: having the operational
> stuff explicit (and possibly needs to be read from the config space implicit)
> seems more straight forward to me.
>
> Anyway, you are consistent with the rest of the spec, so prefer keeping it
> like this.
>
>
>> +
>> +\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 configure 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}
>> +
>> +The operation of a virtio crypto device is driven by requests placed on the virtqueues.
>> +Requests consist of a queue-type specific header (specifying among others the operation)
>> +and an operation specific payload.
>> +
>> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated the device may support both session mode
>> +(See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation})
>> +and stateless mode operation requests.
>> +In stateless mode all operation parameters are supplied as a part of each request,
>> +while in session mode, some or all operation parameters are managed within the
>> +session. Stateless mode is guarded by feature bits 0-4 on a service level. If
>> +stateless mode is negotiated for a service, the service is available both in
>> +session and stateless mode; otherwise it's only available in session mode.
>
> How about the following?
>
> """
> If stateless mode is negotiated for a service, the service accepts both session mode and stateless
> requests; otherwise stateless mode requests are rejected (via operation status).
> """
>
> I prefer it because i think it makes clearer than session mode and stateless
> mode are concepts that apply on request and not on service (or let's say queue)
> level.
>
>> +
>> +\subsubsection{Operation Status}\label{sec:Device Types / Crypto Device / Device Operation / Operation status}
>> +The device MUST return a status code as part of the operation (both session
>> +operation and service operation) result. The valid operation status as follows:
>> +
>> +\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_NOSPC = 5,
>> + VIRTIO_CRYPTO_MAX
>> +};
>> +\end{lstlisting}
>> +
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK: success.
>> +\item VIRTIO_CRYPTO_BADMSG: authentication failed (only when AEAD decryption).
>> +\item VIRTIO_CRYPTO_NOTSUPP: operation or algorithm is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto operations.
>> +\item VIRTIO_CRYPTO_NOSPC: no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
>> + feature bit is negotiated).
>> +\item VIRTIO_CRYPTO_ERR: any failure not mentioned above occurs.
>> +\end{itemize*}
>> +
>
> Just thinking loud: We don't seem to be able to differentiate between device
> detected a driver (guest) bug, and something went wrong with the backend.
> I'm not sure differentiating between the two is useful in the first place.
>
>> +\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}).
>> +
>> +The header for controlq is of the following form:
>> +\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;
>> + le32 reserved;
>> +};
>> +\end{lstlisting}
>> +
>> +The controlq request is composed of four parts:
>> +\begin{lstlisting}
>> +struct virtio_crypto_op_ctrl_req {
>> + /* Device read only portion */
>> +
>> + struct virtio_crypto_ctrl_header header;
>> +
>> +#define VIRTIO_CRYPTO_CTRLQ_OP_SPEC_HDR_LEGACY 56
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[flf_len];
>> +
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>> +
>> + /* Device write only portion */
>> +
>> + /* op result or completion status */
>> + u8 op_outcome[outcome_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{header} is a general header (see above).
>> +
>> +\field{op_flf} is the opcode (in \field{header}) specific fixed-length paramenters.
>> +
>> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit (see below).
>> +
>> +\field{op_vlf} is the opcode (in \field{header}) specific variable-length paramenters.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +\begin{note}
>> +The \field{vlf_len} of session-destroy operation and the hash-session-create
>> +operation is ZERO.
>> +\end{note}
>> +
>> +\begin{itemize*}
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_sym_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_sym_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_sym_create_session_vlf.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_hash_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_hash_create_session_flf if
>> + padded to 56 bytes if NOT negotiated.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_mac_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_mac_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_mac_create_session_vlf.
>> +\end{itemize*}
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_aead_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_aead_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_aead_create_session_vlf.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_DESTROY_SESSION
>> + or VIRTIO_CRYPTO_HASH_DESTROY_SESSION or VIRTIO_CRYPTO_MAC_DESTROY_SESSION or
>> + VIRTIO_CRYPTO_AEAD_DESTROY_SESSION then \field{op_flf} is struct
>> + virtio_crypto_destroy_session_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated and
>> + struct virtio_crypto_destroy_session_flf if padded to 56 bytes if NOT negotiated.
>> +\end{itemize*}
>> +
>> +\field{op_outcome} stores the result of operation and must be struct
>> +virtio_crypto_destroy_session_input for session-destroy operation or
>> +struct virtio_crypto_session_input.
>> +
>> +\field{outcome_len} is the size of the structure used.
>> +
>> +
>> +\paragraph{Session operation}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation}
>> +
>> +The session is a handle which describes the cryptographic parameters to be
>> +applied to a number of buffers.
>> +
>> +The following structure stores the result of session creation set by the device:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_session_input {
>> + /* Device write only portion */
>
> I think you cann drop this comment along with the following similar
> comments. We have already told whats device read only and what is
> device write only in virtio_crypto_op_ctrl_req.
>
> Restating it at each struct is redundant and IMHO just confusing. The
> R/W is determined by where does the struct sit in the request.
>
>> + 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_flf {
>> + /* Device read only portion */
>> + le64 session_id;
>> +};
>> +
>> +struct virtio_crypto_destroy_session_input {
>> + /* Device write only portion */
>> + 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}
>> +
>> +The fixed-length paramenters of HASH session requests is as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_hash_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* See VIRTIO_CRYPTO_HASH_* above */
>> + le32 algo;
>> + /* hash result length */
>> + le32 hash_result_len;
>> +};
>> +\end{lstlisting}
>> +
>> +
>> +\subparagraph{Session operation: MAC session}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation / Session operation: MAC session}
>> +
>> +The fixed-length and the variable-length parameters of MAC session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_mac_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> +
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{auth_key} is specified in \field{auth_key_len} in the struct
>> +virtio_crypto_mac_create_session_flf.
>> +
>> +
>> +\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 could be the CIPHER algorithms request
>> +or the chain algorithms (chaining CIPHER and HASH/MAC) request.
>> +
>> +The fixed-length and the variable-length parameters of CIPHER session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_cipher_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> +
>> + /* The cipher key */
>> + u8 cipher_key[keylen];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{cipher_key} is specified in \field{keylen} in the struct
>> +virtio_crypto_cipher_session_flf.
>> +
>> +The fixed-length and the variable-length parameters of Chain session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_alg_chain_session_flf {
>> + /* Device read only portion */
>> +
>> +#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_flf cipher_hdr;
>> +
>> +#define VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE 16
>> + /* fixed length fields, algo specific */
>> + u8 algo_flf[VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE];
>> +
>> + /* length of the additional authenticated data (AAD) in bytes */
>> + le32 aad_len;
>> + le32 padding;
>> +};
>> +
>> +struct virtio_crypto_alg_chain_session_vlf {
>> + /* Device read only portion */
>> +
>> + /* The cipher key */
>> + u8 cipher_key[keylen];
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{hash_mode} decides the type used by \field{algo_flf}.
>> +
>> +\field{algo_flf} is fixed to 16 bytes and MUST contains or be one of
>> +the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_hash_create_session_flf
>> +\item struct virtio_crypto_mac_create_session_flf
>> +\end{itemize*}
>> +The data of unused part (if has) in \field{algo_flf} will be ignored.
>> +
>> +The length of \field{cipher_key} is specified in \field{keylen} in \field{cipher_hdr}.
>> +
>> +The length of \field{auth_key} is specified in \field{auth_key_len} in struct
>> +virtio_crypto_mac_create_session_flf.
>> +
>> +The fixed-length parameters of Symmetric session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_sym_create_session_flf {
>> + /* Device read only portion */
>> +
>> +#define VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE 48
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE];
>> +
>> +/* 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}
>> +
>> +\field{op_flf} is fixed to 48 bytes, MUST contains or be one of
>> +the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_cipher_session_flf
>> +\item struct virtio_crypto_alg_chain_session_flf
>> +\end{itemize*}
>> +The data of unused part (if has) in \field{op_flf} will be ignored.
>> +
>> +\field{op_type} decides the type used by \field{op_flf}.
>> +
>> +The variable-length parameters of Symmetric session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_sym_create_session_vlf {
>> + /* Device read only portion */
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{op_vlf} MUST contains or be one of the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_cipher_session_vlf
>> +\item struct virtio_crypto_alg_chain_session_vlf
>> +\end{itemize*}
>> +
>> +\field{op_type} in struct virtio_crypto_sym_create_session_flf decides the
>> +type used by \field{op_vlf}.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +
>> +
>> +\subparagraph{Session operation: AEAD session}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation / Session operation: AEAD session}
>> +
>> +The fixed-length and the variable-length parameters of AEAD session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_aead_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> + u8 key[key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{key} is specified in \field{key_len} in struct
>> +virtio_crypto_aead_create_session_flf.
>> +
>> +
>> +\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 \field{opcode} field based on service type: CIPHER, HASH, MAC, or AEAD.
>> +\item The driver MUST set the control general header, the opcode specific header,
>> + the opcode specific extra parameters and the opcode specific outcome buffer in turn.
>> + See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}.
>> +\item The driver MUST set the \field{reversed} field to zero.
>> +\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 use the corresponding opcode specific structure according to the
>> + \field{opcode} in the control general header.
>> +\item The device MUST extract extra parameters according to the structures used.
>> +\item The device MUST set the \field{status} field to one of the following values of enum
>> + VIRTIO_CRYPTO_STATUS after finish a session creation:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_NOSPC if no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
>> + feature bit is negotiated).
>> +\item VIRTIO_CRYPTO_ERR if failure not mentioned above occurs.
>> +\end{itemize*}
>> +\item The device MUST set the \field{session_id} field to a unique session identifier only
>> + if the status is set to VIRTIO_CRYPTO_OK.
>> +\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 following values of enum VIRTIO_CRYPTO_STATUS.
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
>> +\item VIRTIO_CRYPTO_ERR if any failure occurs.
>> +\end{itemize*}
>> +\end{itemize*}
>> +
>> +
>> +\subsubsection{Data Virtqueue}\label{sec:Device Types / Crypto Device / Device Operation / Data Virtqueue}
>> +
>> +The driver uses the data virtqueues to transmit crypto operation requests to the device,
>> +and completes the crypto operations.
>> +
>> +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_SESSION_MODE 1
>> + /* control flag to control the request */
>> + le32 flag;
>> + le32 padding;
>> +};
>> +\end{lstlisting}
>> +
>> +\begin{note}
>> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
>> +is not negotiated then <SERVICE> retuqests with the \field{flag} (in struct
>
>
> s/retuqests/requests
>
>> +virtio_crypto_op_header) is ZERO need to be rejected. If VIRTIO_CRYPTO_F_REVISION_1 is
>> +not negotiated the \field{flag} is ignored.
>> +\end{note}
>> +
>
> I think your formulation is a bit hard to understand.
>
> I would prefer:
> +\begin{note}
> +If VIRTIO_CRYPTO_F_REVISION_1 is not negotiated the \field{flag} is ignored.
> +
> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
> +is not negotiated, then the device should reject <SERVICE> requests if
> +VIRTIO_CRYPTO_FLAG_SESSION_MODE is not set (in \field{flag}).
> +\end{note}
> +
>
>> +The dataq request is composed of four parts:
>> +\begin{lstlisting}
>> +struct virtio_crypto_op_data_req {
>> + /* Device read only portion */
>> +
>> + struct virtio_crypto_op_header header;
>> +
>> +#define VIRTIO_CRYPTO_DATAQ_OP_SPEC_HDR_LEGACY 48
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[flf_len];
>> +
>> + /* Device read && write portion */
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>
> Descriptors are either read or write. You need read && write (whatever the
> sematic is) because you throw things together that don't belong together.
>
> I would try to do the same as for the ctrl requests:
> + * Device write only portion */
> + u8 op_outcome;
>
> and describe the outcome on a per service basis. Also see my
> comments about the dst_data_len below.
>
>> +
>> + /* Device write only portion */
>> + struct virtio_crypto_inhdr inhdr;
>> +};
>> +\end{lstlisting}
>> +
>> +\field{header} is a general header (see above).
>> +
>> +\field{op_flf} is the opcode (in \field{header}) specific header.
>> +
>> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit
>> +(see below).
>> +
>> +\field{op_vlf} is the opcode (in \field{header}) specific parameters.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +
>> +\begin{itemize*}
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_ENCRYPT
>> + or VIRTIO_CRYPTO_CIPHER_DECRYPT then:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_sym_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_sym_data_vlf_stateless.
>
> What does this _data_ (in the name) symbolise?
>
>> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_sym_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_sym_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_sym_data_vlf.
>> + \end{itemize*}
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_hash_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_hash_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_hash_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_hash_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_hash_data_vlf.
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_mac_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_mac_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_mac_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_mac_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_mac_data_vlf.
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_ENCRYPT
>> + or VIRTIO_CRYPTO_AEAD_DECRYPT then:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_aead_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_aead_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_aead_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_aead_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_aead_data_vlf.
>> +\end{itemize*}
>> +
>> +\field{inhdr} is a unified input header that used to return the status of
>> +the operations, 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_data_flf {
>> + /* length of source data */
>> + le32 src_data_len;
>> + /* hash result length */
>> + le32 hash_result_len;
>> +};
>> +
>> +struct virtio_crypto_hash_data_vlf {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +Each data request uses the virtio_crypto_hash_data_flf structure and the
>> +virtio_crypto_hash_data_vlfto structure to store information used to run the
>> +HASH operations.
>> +
>> +\field{src_data} is the source data that will be processed.
>> +\field{src_data_len} is the length of source data.
>> +\field{hash_result} is the result data and \field{hash_result_len} is the length
>> +of it.
>> +
>> +Stateless mode HASH service requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_hash_data_flf_stateless {
>> + 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_vlf_stateless {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\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_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 ZERO and MUST set the fields in struct
>> + virtio_crypto_hash_data_flf_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_SESSION_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 The device MUST use the corresponding structure according to the \field{opcode}
>> + in the data general header.
>> +\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
>> + following values of enum VIRTIO_CRYPTO_STATUS:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if the operation success.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
>> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
>> +\end{itemize*}
>> +\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_data_flf {
>> + struct virtio_crypto_hash_data_flf hdr;
>> +};
>> +
>> +struct virtio_crypto_mac_data_vlf {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +Each request uses the virtio_crypto_mac_data_flf structure and the
>> +virtio_crypto_mac_data_vlf structure to store information used to run the
>> +MAC operations.
>> +
>> +\field{src_data} is the source data that will be processed.
>> +\field{src_data_len} is the length of source data.
>> +\field{hash_result} is the result data and \field{hash_result_len} is the length
>> +of it.
>> +
>> +Stateless mode MAC service requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_mac_data_flf_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_vlf_stateless {
>> + /* Device read only portion */
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{auth_key} is the authenticated key that will be used during the process.
>> +\field{auth_key_len} is the length of the key.
>> +
>> +\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_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 ZERO and MUST set the fields in struct
>> + virtio_crypto_mac_data_flf_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_SESSION_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_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
>> + following values of enum VIRTIO_CRYPTO_STATUS:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if the operation success.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
>> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
>> +\end{itemize*}
>> +\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_data_flf {
>> + /*
>> + * 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_vlf {
>> + /* Device read only portion */
>> +
>> + /*
>> + * 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 write only portion */
>> + /* Destination data */
>> + u8 dst_data[dst_data_len];
>
>
> I'm a bit puzzled about dst_data_len. I'm by no means a crypto expert,
> and that is probably the very reason of my discomfort.
>
> I've tried to figure out how dst_data_len is used and expected to find
> a place that checks, that at least a sufficiently large buffer was provided.
>
> I've also assumed that the src_data_len is likely to imply the dst_data_len
> for any given algorithm. Furthermore, I even hypothesised that the both
> lengths are the same. All based on what I remember about block ciphers.
>
> If that hypothesis is right, then I don't understand why do we need
> both src_data_len and dst_data_len.
>
> Since dst_data_len is device read only, the driver I figure the driver
> needs to know the exact length (since I cant figure out, based on this
> spec, how is it supposed to be told by the device which part of the
> buffer is the result and which part garbage). So the only sane usage
> I was able to come up with is to avoid the device overwritting other
> parts of the requests device writtable part because of a driver
> bug (wrong dst_data_len). But as I've said I could not find the corresponding
> code in qemu.
>
> Anyway providing some more background for the guys only superficially
> involved with crypto (like me) would be appreciated.
>
> I will stop here for now. I read the rest real quick and I did not
> see anything major. I think we are slowly getting there.
>
> Regards,
> Halil
>
>
> .
>
--
Regards,
Longpeng(Mike)
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [virtio-dev] Re: [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-01-09 17:05 ` [virtio-dev] " Halil Pasic
@ 2018-03-16 16:27 ` Michael S. Tsirkin
-1 siblings, 0 replies; 31+ messages in thread
From: Michael S. Tsirkin @ 2018-03-16 16:27 UTC (permalink / raw)
To: Halil Pasic
Cc: Longpeng(Mike),
qemu-devel, virtio-dev, luonengjun, cornelia.huck, stefanha,
denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On Tue, Jan 09, 2018 at 06:05:41PM +0100, Halil Pasic wrote:
> > +\item[\field{max_cipher_key_len}] is the maximum length of cipher key supported by the device.
>
> I can't find what happens if this limit isn't honored by the driver. Moreover
> reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
> such requests? I think in qemu implementation we fail the request.
>
> This question is only about niceness. We are already good enough, IMHO:
> since the implementer of the driver can't be sure what is going to happen
> if the driver disregards max_cipher_key_len it is already an implicit
> SHOULD.
I am not sure documenting undefined behaviour is always required.
We certainly do not do this for all other devices.
Reading a field being SHOULD seems reasonable: e.g.
driver might read it once and cache it in memory.
Halil, could you try to split your comments between requirements
for more conformance clauses/clarifications as opposed to
defects where it's wrong and does not match actual or
expected behaviour?
I think spec is better off with some documentation for this
device than none at all like today.
--
MST
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-03-16 16:27 ` Michael S. Tsirkin
0 siblings, 0 replies; 31+ messages in thread
From: Michael S. Tsirkin @ 2018-03-16 16:27 UTC (permalink / raw)
To: Halil Pasic
Cc: Longpeng(Mike),
qemu-devel, virtio-dev, luonengjun, cornelia.huck, stefanha,
denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On Tue, Jan 09, 2018 at 06:05:41PM +0100, Halil Pasic wrote:
> > +\item[\field{max_cipher_key_len}] is the maximum length of cipher key supported by the device.
>
> I can't find what happens if this limit isn't honored by the driver. Moreover
> reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
> such requests? I think in qemu implementation we fail the request.
>
> This question is only about niceness. We are already good enough, IMHO:
> since the implementer of the driver can't be sure what is going to happen
> if the driver disregards max_cipher_key_len it is already an implicit
> SHOULD.
I am not sure documenting undefined behaviour is always required.
We certainly do not do this for all other devices.
Reading a field being SHOULD seems reasonable: e.g.
driver might read it once and cache it in memory.
Halil, could you try to split your comments between requirements
for more conformance clauses/clarifications as opposed to
defects where it's wrong and does not match actual or
expected behaviour?
I think spec is better off with some documentation for this
device than none at all like today.
--
MST
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [virtio-dev] Re: [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-03-16 16:27 ` [virtio-dev] Re: [Qemu-devel] " Michael S. Tsirkin
@ 2018-03-16 18:18 ` Halil Pasic
-1 siblings, 0 replies; 31+ messages in thread
From: Halil Pasic @ 2018-03-16 18:18 UTC (permalink / raw)
To: Michael S. Tsirkin
Cc: Longpeng(Mike),
qemu-devel, virtio-dev, luonengjun, cornelia.huck, stefanha,
denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On 03/16/2018 05:27 PM, Michael S. Tsirkin wrote:
> On Tue, Jan 09, 2018 at 06:05:41PM +0100, Halil Pasic wrote:
>>> +\item[\field{max_cipher_key_len}] is the maximum length of cipher key supported by the device.
>>
>> I can't find what happens if this limit isn't honored by the driver. Moreover
>> reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
>> such requests? I think in qemu implementation we fail the request.
>>
>> This question is only about niceness. We are already good enough, IMHO:
>> since the implementer of the driver can't be sure what is going to happen
>> if the driver disregards max_cipher_key_len it is already an implicit
>> SHOULD.
>
> I am not sure documenting undefined behaviour is always required.
I kind of agree. But I'm afraid I did not get through my point. It's
about clarity. The driver supplying a cipher key larger that
max_cipher_key_len isn't violating any driver normative statement.
I find it strange make obtaining a piece of configuration a driver
normative but have neither a driver normative that says the driver must
(or should) operate according to the same (at least in certain)
circumstances nor a device normative that implicitly educates the driver
implementer what happens if the driver is acting stupid (see below).
> We certainly do not do this for all other devices>
"""
5.2.6.2 Device Requirements: Device Operation
A device MUST set the status byte to VIRTIO_BLK_S_IOERR for a write request if the VIRTIO_BLK_F_RO feature if offered, and MUST NOT write any data.
"""
I was under the impression, that we sometimes express what is naively
a driver-requirement (e.g. thou shall not write to a read only
device) as a device-requirement. This has benefits in my opinion:
the driver implementer is educated about a certain behavior being a no-no
and hopefully leading to sane error handling (with a compliant device
sitting on the other side) --- instead of offending drivers landing beyond
the spec (in undefined behavior land) by violating a driver-normative.
> Reading a field being SHOULD seems reasonable: e.g.
> driver might read it once and cache it in memory.
I don't quite understand. Let me quote the normative section
+\drivernormative{\subsubsection}{Device configuration layout}{Device Types / Crypto Device / Device configuration layout}
+
+\begin{itemize*}
+\item The driver MUST read the \field{status} from the bottom bit of status to check whether the
+ VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
+\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD read \field{max_cipher_key_len} to discover the maximum length of cipher key
+ the device supports.
Does it mean it's OK for the driver (e.g. after a configuration change
notification to use a stale) \field{max_cipher_key_len} ) as it is SHOULD read
bit it's not OK to use a stale \field{max_dataqueues}?
AFAIU all configuration space stuff eligible for caching, but
under certain circumstances the cache invalidates and a re-read
is necessary.
>
> Halil, could you try to split your comments between requirements
> for more conformance clauses/clarifications as opposed to
> defects where it's wrong and does not match actual or
> expected behaviour?
Yes. I'm already trying to tag my comments. 'This question is only
about niceness. We are already good enough' was supposed to indicate
that this one is not requirement.
Do you mean putting these in separate emails?
>
> I think spec is better off with some documentation for this
> device than none at all like today.
>
If the rest community says it's good enough, I won't fight against
inclusion neither in the repo nor in the next Committee Specification.
I would %100 agree with you if this were normal documentation.
The problem with standards is that both correctness and completeness
are crucial. What is not part of the standard, is not part of the
standard and period.
Virtio is especially tricky as there is no versions of the standard.
What once was a compliant device/driver must be kept compliant when
we change the text. That is why this better something than nothing
does not entirely work for me.
Regards,
Halil
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-03-16 18:18 ` Halil Pasic
0 siblings, 0 replies; 31+ messages in thread
From: Halil Pasic @ 2018-03-16 18:18 UTC (permalink / raw)
To: Michael S. Tsirkin
Cc: Longpeng(Mike),
qemu-devel, virtio-dev, luonengjun, cornelia.huck, stefanha,
denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On 03/16/2018 05:27 PM, Michael S. Tsirkin wrote:
> On Tue, Jan 09, 2018 at 06:05:41PM +0100, Halil Pasic wrote:
>>> +\item[\field{max_cipher_key_len}] is the maximum length of cipher key supported by the device.
>>
>> I can't find what happens if this limit isn't honored by the driver. Moreover
>> reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
>> such requests? I think in qemu implementation we fail the request.
>>
>> This question is only about niceness. We are already good enough, IMHO:
>> since the implementer of the driver can't be sure what is going to happen
>> if the driver disregards max_cipher_key_len it is already an implicit
>> SHOULD.
>
> I am not sure documenting undefined behaviour is always required.
I kind of agree. But I'm afraid I did not get through my point. It's
about clarity. The driver supplying a cipher key larger that
max_cipher_key_len isn't violating any driver normative statement.
I find it strange make obtaining a piece of configuration a driver
normative but have neither a driver normative that says the driver must
(or should) operate according to the same (at least in certain)
circumstances nor a device normative that implicitly educates the driver
implementer what happens if the driver is acting stupid (see below).
> We certainly do not do this for all other devices>
"""
5.2.6.2 Device Requirements: Device Operation
A device MUST set the status byte to VIRTIO_BLK_S_IOERR for a write request if the VIRTIO_BLK_F_RO feature if offered, and MUST NOT write any data.
"""
I was under the impression, that we sometimes express what is naively
a driver-requirement (e.g. thou shall not write to a read only
device) as a device-requirement. This has benefits in my opinion:
the driver implementer is educated about a certain behavior being a no-no
and hopefully leading to sane error handling (with a compliant device
sitting on the other side) --- instead of offending drivers landing beyond
the spec (in undefined behavior land) by violating a driver-normative.
> Reading a field being SHOULD seems reasonable: e.g.
> driver might read it once and cache it in memory.
I don't quite understand. Let me quote the normative section
+\drivernormative{\subsubsection}{Device configuration layout}{Device Types / Crypto Device / Device configuration layout}
+
+\begin{itemize*}
+\item The driver MUST read the \field{status} from the bottom bit of status to check whether the
+ VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
+\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD read \field{max_cipher_key_len} to discover the maximum length of cipher key
+ the device supports.
Does it mean it's OK for the driver (e.g. after a configuration change
notification to use a stale) \field{max_cipher_key_len} ) as it is SHOULD read
bit it's not OK to use a stale \field{max_dataqueues}?
AFAIU all configuration space stuff eligible for caching, but
under certain circumstances the cache invalidates and a re-read
is necessary.
>
> Halil, could you try to split your comments between requirements
> for more conformance clauses/clarifications as opposed to
> defects where it's wrong and does not match actual or
> expected behaviour?
Yes. I'm already trying to tag my comments. 'This question is only
about niceness. We are already good enough' was supposed to indicate
that this one is not requirement.
Do you mean putting these in separate emails?
>
> I think spec is better off with some documentation for this
> device than none at all like today.
>
If the rest community says it's good enough, I won't fight against
inclusion neither in the repo nor in the next Committee Specification.
I would %100 agree with you if this were normal documentation.
The problem with standards is that both correctness and completeness
are crucial. What is not part of the standard, is not part of the
standard and period.
Virtio is especially tricky as there is no versions of the standard.
What once was a compliant device/driver must be kept compliant when
we change the text. That is why this better something than nothing
does not entirely work for me.
Regards,
Halil
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [virtio-dev] Re: [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-03-16 18:18 ` [virtio-dev] Re: [Qemu-devel] " Halil Pasic
@ 2018-03-19 0:13 ` Michael S. Tsirkin
-1 siblings, 0 replies; 31+ messages in thread
From: Michael S. Tsirkin @ 2018-03-19 0:13 UTC (permalink / raw)
To: Halil Pasic
Cc: Longpeng(Mike),
qemu-devel, virtio-dev, luonengjun, cornelia.huck, stefanha,
denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On Fri, Mar 16, 2018 at 07:18:45PM +0100, Halil Pasic wrote:
>
>
> On 03/16/2018 05:27 PM, Michael S. Tsirkin wrote:
> > On Tue, Jan 09, 2018 at 06:05:41PM +0100, Halil Pasic wrote:
> >>> +\item[\field{max_cipher_key_len}] is the maximum length of cipher key supported by the device.
> >>
> >> I can't find what happens if this limit isn't honored by the driver. Moreover
> >> reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
> >> such requests? I think in qemu implementation we fail the request.
> >>
> >> This question is only about niceness. We are already good enough, IMHO:
> >> since the implementer of the driver can't be sure what is going to happen
> >> if the driver disregards max_cipher_key_len it is already an implicit
> >> SHOULD.
> >
> > I am not sure documenting undefined behaviour is always required.
>
> I kind of agree. But I'm afraid I did not get through my point. It's
> about clarity. The driver supplying a cipher key larger that
> max_cipher_key_len isn't violating any driver normative statement.
> I find it strange make obtaining a piece of configuration a driver
> normative
> but have neither a driver normative that says the driver must
> (or should) operate according to the same (at least in certain)
> circumstances
I agree with that. I think it would be clearer to say
that driver must not (or should not?) submit longer requests
than to say that it should read this field.
> nor a device normative that implicitly educates the driver
> implementer what happens if the driver is acting stupid (see below).
About not saying what happens if driver does something stupid,
we generally don't.
>
> > We certainly do not do this for all other devices>
>
> """
> 5.2.6.2 Device Requirements: Device Operation
>
> A device MUST set the status byte to VIRTIO_BLK_S_IOERR for a write request if the VIRTIO_BLK_F_RO feature if offered, and MUST NOT write any data.
> """
>
> I was under the impression, that we sometimes express what is naively
> a driver-requirement (e.g. thou shall not write to a read only
> device) as a device-requirement. This has benefits in my opinion:
> the driver implementer is educated about a certain behavior being a no-no
> and hopefully leading to sane error handling (with a compliant device
> sitting on the other side) --- instead of offending drivers landing beyond
> the spec (in undefined behavior land) by violating a driver-normative.
>
> > Reading a field being SHOULD seems reasonable: e.g.
> > driver might read it once and cache it in memory.
>
> I don't quite understand. Let me quote the normative section
>
> +\drivernormative{\subsubsection}{Device configuration layout}{Device Types / Crypto Device / Device configuration layout}
> +
> +\begin{itemize*}
> +\item The driver MUST read the \field{status} from the bottom bit of status to check whether the
> + VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
> +\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD read \field{max_cipher_key_len} to discover the maximum length of cipher key
> + the device supports.
>
> Does it mean it's OK for the driver (e.g. after a configuration change
> notification to use a stale) \field{max_cipher_key_len} ) as it is SHOULD read
> bit it's not OK to use a stale \field{max_dataqueues}?
>
> AFAIU all configuration space stuff eligible for caching, but
> under certain circumstances the cache invalidates and a re-read
> is necessary.
So you are saying why aren't max_dataqueues and
max_cipher_key_len consistent?
It's a valid point.
> >
> > Halil, could you try to split your comments between requirements
> > for more conformance clauses/clarifications as opposed to
> > defects where it's wrong and does not match actual or
> > expected behaviour?
>
> Yes. I'm already trying to tag my comments. 'This question is only
> about niceness. We are already good enough' was supposed to indicate
> that this one is not requirement.
to me most questions look like you have a rather specific wording in mind.
How about instead of asking questions you just propose a
specific fixed wording as your own patch?
That will make things converge faster.
> Do you mean putting these in separate emails?
That's up to you, wasn't very clear to me but maybe it's clear
enough to Mike.
> >
> > I think spec is better off with some documentation for this
> > device than none at all like today.
> >
>
>
> If the rest community says it's good enough, I won't fight against
> inclusion neither in the repo nor in the next Committee Specification.
>
> I would %100 agree with you if this were normal documentation.
> The problem with standards is that both correctness and completeness
> are crucial. What is not part of the standard, is not part of the
> standard and period.
I disagree here.
Standards evolve too. A requirement to be 100% correct isn't realistic.
Whoever implements the spec will come back to us and say
"hey I did exactly as standard says and it does not work"
and then we'll either fix the standard or say
"too bad, fix the hypervisor" or say "we weren't clear,
hypervisors implemented spec correctly but we meant something else,
let's add a feature bit so future ones will get it right".
> Virtio is especially tricky as there is no versions of the standard.
> What once was a compliant device/driver must be kept compliant when
> we change the text. That is why this better something than nothing
> does not entirely work for me.
>
> Regards,
> Halil
We can always add feature bits when we change behaviour in incompatible
ways.
--
MST
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-03-19 0:13 ` Michael S. Tsirkin
0 siblings, 0 replies; 31+ messages in thread
From: Michael S. Tsirkin @ 2018-03-19 0:13 UTC (permalink / raw)
To: Halil Pasic
Cc: Longpeng(Mike),
qemu-devel, virtio-dev, luonengjun, cornelia.huck, stefanha,
denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On Fri, Mar 16, 2018 at 07:18:45PM +0100, Halil Pasic wrote:
>
>
> On 03/16/2018 05:27 PM, Michael S. Tsirkin wrote:
> > On Tue, Jan 09, 2018 at 06:05:41PM +0100, Halil Pasic wrote:
> >>> +\item[\field{max_cipher_key_len}] is the maximum length of cipher key supported by the device.
> >>
> >> I can't find what happens if this limit isn't honored by the driver. Moreover
> >> reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
> >> such requests? I think in qemu implementation we fail the request.
> >>
> >> This question is only about niceness. We are already good enough, IMHO:
> >> since the implementer of the driver can't be sure what is going to happen
> >> if the driver disregards max_cipher_key_len it is already an implicit
> >> SHOULD.
> >
> > I am not sure documenting undefined behaviour is always required.
>
> I kind of agree. But I'm afraid I did not get through my point. It's
> about clarity. The driver supplying a cipher key larger that
> max_cipher_key_len isn't violating any driver normative statement.
> I find it strange make obtaining a piece of configuration a driver
> normative
> but have neither a driver normative that says the driver must
> (or should) operate according to the same (at least in certain)
> circumstances
I agree with that. I think it would be clearer to say
that driver must not (or should not?) submit longer requests
than to say that it should read this field.
> nor a device normative that implicitly educates the driver
> implementer what happens if the driver is acting stupid (see below).
About not saying what happens if driver does something stupid,
we generally don't.
>
> > We certainly do not do this for all other devices>
>
> """
> 5.2.6.2 Device Requirements: Device Operation
>
> A device MUST set the status byte to VIRTIO_BLK_S_IOERR for a write request if the VIRTIO_BLK_F_RO feature if offered, and MUST NOT write any data.
> """
>
> I was under the impression, that we sometimes express what is naively
> a driver-requirement (e.g. thou shall not write to a read only
> device) as a device-requirement. This has benefits in my opinion:
> the driver implementer is educated about a certain behavior being a no-no
> and hopefully leading to sane error handling (with a compliant device
> sitting on the other side) --- instead of offending drivers landing beyond
> the spec (in undefined behavior land) by violating a driver-normative.
>
> > Reading a field being SHOULD seems reasonable: e.g.
> > driver might read it once and cache it in memory.
>
> I don't quite understand. Let me quote the normative section
>
> +\drivernormative{\subsubsection}{Device configuration layout}{Device Types / Crypto Device / Device configuration layout}
> +
> +\begin{itemize*}
> +\item The driver MUST read the \field{status} from the bottom bit of status to check whether the
> + VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
> +\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD read \field{max_cipher_key_len} to discover the maximum length of cipher key
> + the device supports.
>
> Does it mean it's OK for the driver (e.g. after a configuration change
> notification to use a stale) \field{max_cipher_key_len} ) as it is SHOULD read
> bit it's not OK to use a stale \field{max_dataqueues}?
>
> AFAIU all configuration space stuff eligible for caching, but
> under certain circumstances the cache invalidates and a re-read
> is necessary.
So you are saying why aren't max_dataqueues and
max_cipher_key_len consistent?
It's a valid point.
> >
> > Halil, could you try to split your comments between requirements
> > for more conformance clauses/clarifications as opposed to
> > defects where it's wrong and does not match actual or
> > expected behaviour?
>
> Yes. I'm already trying to tag my comments. 'This question is only
> about niceness. We are already good enough' was supposed to indicate
> that this one is not requirement.
to me most questions look like you have a rather specific wording in mind.
How about instead of asking questions you just propose a
specific fixed wording as your own patch?
That will make things converge faster.
> Do you mean putting these in separate emails?
That's up to you, wasn't very clear to me but maybe it's clear
enough to Mike.
> >
> > I think spec is better off with some documentation for this
> > device than none at all like today.
> >
>
>
> If the rest community says it's good enough, I won't fight against
> inclusion neither in the repo nor in the next Committee Specification.
>
> I would %100 agree with you if this were normal documentation.
> The problem with standards is that both correctness and completeness
> are crucial. What is not part of the standard, is not part of the
> standard and period.
I disagree here.
Standards evolve too. A requirement to be 100% correct isn't realistic.
Whoever implements the spec will come back to us and say
"hey I did exactly as standard says and it does not work"
and then we'll either fix the standard or say
"too bad, fix the hypervisor" or say "we weren't clear,
hypervisors implemented spec correctly but we meant something else,
let's add a feature bit so future ones will get it right".
> Virtio is especially tricky as there is no versions of the standard.
> What once was a compliant device/driver must be kept compliant when
> we change the text. That is why this better something than nothing
> does not entirely work for me.
>
> Regards,
> Halil
We can always add feature bits when we change behaviour in incompatible
ways.
--
MST
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [virtio-dev] Re: [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-01-10 5:53 ` [virtio-dev] " Longpeng (Mike)
@ 2018-06-20 3:34 ` Michael S. Tsirkin
-1 siblings, 0 replies; 31+ messages in thread
From: Michael S. Tsirkin @ 2018-06-20 3:34 UTC (permalink / raw)
To: Longpeng (Mike)
Cc: Halil Pasic, qemu-devel, virtio-dev, luonengjun, cornelia.huck,
stefanha, denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi,
xin.zeng, brian.a.keating, liang.j.ma, john.griffin,
weidong.huang, agraf, jasowang, vincent.jardin, arei.gonglei,
wangxinxin.wang, jianjay.zhou
On Wed, Jan 10, 2018 at 01:53:09PM +0800, Longpeng (Mike) wrote:
> Hi Halil,
>
> We are fixing the Intel BUG these days, so I will go through your comments after
> we're done. Thanks.
All right - are you guys done with meltdown/spectre? I'd like us
to start finally getting parts of this in the spec.
This is already used in the field - let's get into spec
whatever is already out there.
Argue about future enhancements later.
--
MST
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-06-20 3:34 ` Michael S. Tsirkin
0 siblings, 0 replies; 31+ messages in thread
From: Michael S. Tsirkin @ 2018-06-20 3:34 UTC (permalink / raw)
To: Longpeng (Mike)
Cc: Halil Pasic, qemu-devel, virtio-dev, luonengjun, cornelia.huck,
stefanha, denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi,
xin.zeng, brian.a.keating, liang.j.ma, john.griffin,
weidong.huang, agraf, jasowang, vincent.jardin, arei.gonglei,
wangxinxin.wang, jianjay.zhou
On Wed, Jan 10, 2018 at 01:53:09PM +0800, Longpeng (Mike) wrote:
> Hi Halil,
>
> We are fixing the Intel BUG these days, so I will go through your comments after
> we're done. Thanks.
All right - are you guys done with meltdown/spectre? I'd like us
to start finally getting parts of this in the spec.
This is already used in the field - let's get into spec
whatever is already out there.
Argue about future enhancements later.
--
MST
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [virtio-dev] Re: [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-06-20 3:34 ` [virtio-dev] Re: [Qemu-devel] " Michael S. Tsirkin
(?)
@ 2018-06-20 6:15 ` Longpeng (Mike)
-1 siblings, 0 replies; 31+ messages in thread
From: Longpeng (Mike) @ 2018-06-20 6:15 UTC (permalink / raw)
To: Michael S. Tsirkin, arei.gonglei
Cc: Halil Pasic, qemu-devel, virtio-dev, luonengjun, cornelia.huck,
stefanha, denglingli, Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi,
xin.zeng, brian.a.keating, liang.j.ma, john.griffin,
weidong.huang, agraf, jasowang, vincent.jardin, wangxinxin.wang,
jianjay.zhou
On 2018/6/20 11:34, Michael S. Tsirkin wrote:
> On Wed, Jan 10, 2018 at 01:53:09PM +0800, Longpeng (Mike) wrote:
>> Hi Halil,
>>
>> We are fixing the Intel BUG these days, so I will go through your comments after
>> we're done. Thanks.
>
> All right - are you guys done with meltdown/spectre? I'd like us
> to start finally getting parts of this in the spec.
> This is already used in the field - let's get into spec
> whatever is already out there.
>
Some unexpected things (not only meltdown/spectre) have happened for these
months, I'm so sorry for the long delay.
We've noticed the recent virtio-crypto patchset in the maillist and we also
discussed the plan with DPDK-crypto guys, so I'll continue this work as soon as
possible.
> Argue about future enhancements later.
>
>
--
Regards,
Longpeng(Mike)
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-01-09 17:05 ` [virtio-dev] " Halil Pasic
@ 2018-07-20 12:01 ` Longpeng (Mike)
-1 siblings, 0 replies; 31+ messages in thread
From: Longpeng (Mike) @ 2018-07-20 12:01 UTC (permalink / raw)
To: Halil Pasic
Cc: qemu-devel, virtio-dev, mst, cornelia.huck, stefanha, denglingli,
Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On 2018/1/10 1:05, Halil Pasic wrote:
>
>
> On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
>> From: Gonglei <arei.gonglei@huawei.com>
>>
>> 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 <arei.gonglei@huawei.com>
>> Signed-off-by: Zhoujian <jianjay.zhou@huawei.com>
>> Signed-off-by: Longpeng(Mike) <longpeng2@huawei.com>
>> ---
>> acknowledgements.tex | 4 +
>> content.tex | 2 +
>> virtio-crypto.tex | 1525 ++++++++++++++++++++++++++++++++++++++++++++++++++
>> 3 files changed, 1531 insertions(+)
>> create mode 100644 virtio-crypto.tex
>>
>> diff --git a/acknowledgements.tex b/acknowledgements.tex
>> index 2d893d9..cdde247 100644
>> --- a/acknowledgements.tex
>> +++ b/acknowledgements.tex
>> @@ -16,10 +16,13 @@ Daniel Kiper, Oracle \newline
>> Geoff Brown, Machine-to-Machine Intelligence (M2MI) Corporation \newline
>> Gershon Janssen, Individual Member \newline
>> James Bottomley, Parallels IP Holdings GmbH \newline
>> +Jian Zhou, Huawei \newline
>> +Lei Gong, Huawei \newline
>> Luiz Capitulino, Red Hat \newline
>> Michael S. Tsirkin, Red Hat \newline
>> Paolo Bonzini, Red Hat \newline
>> Pawel Moll, ARM \newline
>> +Peng Long, Huawei \newline
>> Richard Sohn, Alcatel-Lucent \newline
>> Rusty Russell, IBM \newline
>> Sasha Levin, Oracle \newline
>> @@ -38,6 +41,7 @@ Brian Foley, ARM \newline
>> David Alan Gilbert, Red Hat \newline
>> Fam Zheng, Red Hat \newline
>> Gerd Hoffmann, Red Hat \newline
>> +Halil Pasic, IBM \newline
>> Jason Wang, Red Hat \newline
>> Laura Novich, Red Hat \newline
>> Patrick Durusau, Technical Advisory Board, OASIS \newline
>> diff --git a/content.tex b/content.tex
>> index c840588..d1d3b09 100644
>> --- a/content.tex
>> +++ b/content.tex
>> @@ -5819,6 +5819,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 these device-independent feature bits defined:
>> diff --git a/virtio-crypto.tex b/virtio-crypto.tex
>> new file mode 100644
>> index 0000000..4bd5b51
>> --- /dev/null
>> +++ b/virtio-crypto.tex
>> @@ -0,0 +1,1525 @@
>> +\section{Crypto Device}\label{sec:Device Types / Crypto Device}
>> +
>> +The virtio crypto device is a virtual cryptography device as well as a
>> +virtual cryptographic accelerator. The virtio crypto device provides the
>> +following crypto services: CIPHER, MAC, HASH, and AEAD. Virtio crypto
>> +devices have a single control queue and at least one data queue. Crypto
>> +operation requests are placed into a data queue, and serviced by the
>> +device. Some crypto operation requests are only valid in the context of a
>> +session. The role of the control queue is facilitating control operation
>> +requests. Sessions management is realized with control operation
>> +requests.
>> +
>> +\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}
>> +
>> +\begin{description}
>> +\item VIRTIO_CRYPTO_F_REVISION_1 (0) revision 1. Revision 1 has a specific
>> + request format and other enhancements (which result in some additional
>> + requirements).
>> +\item VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE (1) stateless mode requests are
>> + supported by the CIPHER service.
>> +\item VIRTIO_CRYPTO_F_HASH_STATELESS_MODE (2) stateless mode requests are
>> + supported by the HASH service.
>> +\item VIRTIO_CRYPTO_F_MAC_STATELESS_MODE (3) stateless mode requests are
>> + supported by the MAC service.
>> +\item VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE (4) stateless mode requests are
>> + supported by the AEAD service.
>> +\end{description}
>> +
>> +
>> +\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_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_HASH_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_MAC_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\end{description}
>> +
>> +\subsection{Supported crypto services}\label{sec:Device Types / Crypto Device / Supported crypto services}
>> +
>> +The following crypto services are defined:
>> +
>> +\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 designate bits used to indicate the which of crypto services are
>> +offered by the device as described in, 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 designate the algorithm in (CIPHER type) crypto
>> +operation requests, 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 designate the algorithm in (HASH type) crypto
>> +operation 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 designate the algorithm in (MAC type) crypto
>> +operation requests, 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 designate the algorithm in (DEAD type) crypto
>> +operation requests, 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 Currently, only one \field(status) bit is defined: VIRTIO_CRYPTO_S_HW_READY
>> + set indicates that the device is ready to process requests, this bit is read-only
>> + for the driver
>> +\begin{lstlisting}
>> +#define VIRTIO_CRYPTO_S_HW_READY (1 << 0)
>> +\end{lstlisting}
>> +
>> +\item[\field{max_dataqueues}] is the maximum number of data virtqueues that can
>> + be configured by the device. The driver MAY use only one data queue, or it
>> + can use more to achieve better performance.
>> +
>> +\item[\field{crypto_services}] crypto service offered, see \ref{sec:Device Types / Crypto Device / Supported crypto services}.
>> +
>> +\item[\field{cipher_algo_l}] CIPHER algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
>> +
>> +\item[\field{cipher_algo_h}] CIPHER algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
>> +
>> +\item[\field{hash_algo}] HASH algorithms bits, see \ref{sec:Device Types / Crypto Device / Supported crypto services / HASH services}.
>> +
>> +\item[\field{mac_algo_l}] MAC algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
>> +
>> +\item[\field{mac_algo_h}] MAC algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
>> +
>> +\item[\field{aead_algo}] AEAD algorithms bits, 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.
>
> I can't find what happens if this limit isn't honored by the driver. Moreover
> reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
> such requests? I think in qemu implementation we fail the request.
>
Yes, the request will fail.
I'll describe this in driver normative. How about the following:
The driver MUST guarantee the \filed{keylen} within the
\field{max_cipher_key_len} of the device configuration, otherwise the request
will fail.
The driver MUST guarantee the \filed{auth_key_len} within the
\field{max_auth_key_len} of the device configuration, otherwise the request will
fail.
> This question is only about niceness. We are already good enough, IMHO:
> since the implementer of the driver can't be sure what is going to happen
> if the driver disregards max_cipher_key_len it is already an implicit
> SHOULD.
>
>> +
>> +\item[\field{max_auth_key_len}] is the maximum length of authenticated key supported by the device.
>
> Same here.
>
OK.
>> +
>> +\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
>
> s/device/device.
>
OK.
> What a content of a request and how is its size calculated? Where is this defined.
>
In qemu, the size of the reuqest's content of SYM is "iv_len + aad_len + src_len
+ dst_len + hash_result_len". Furthermore, the content is the variable-length
parameters of data operation.
So how about:
\item[\field{max_size}] is the maximum size of the variable-length parameters of
data operation of each crypto request's content supported by the device.
> The question what happens if not honored applies similarly.
>
How about:
The driver MUST guarantee the size of the variable-length parameters of data
operation of each crypto request's content within the \field{max_size} of the
device configuration, otherwise the request will fail as the driver MUST reset
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 the \field{status} with valid flags, undefined flags MUST NOT be set.
>> +\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 for each service advertised by \field{crypto_services}.
>> + The device MUST NOT set the not defined algorithms bits.
>> +\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 \field{status} from the bottom bit of status to check whether the
>> + VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
>> +\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD ignore the not defined algorithms bits.
>> +\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*}
>
> Seems to like a common practice in the virtio spec to say SHOULD read some
> config space parameter in a driver normative but then having no driver normative
> about the operational implications of the parameter.
>
> While I do think that the reader is usually fully capable of inferring
> the operational requirement, I find it a bit strange: having the operational
> stuff explicit (and possibly needs to be read from the config space implicit)
> seems more straight forward to me.
>
> Anyway, you are consistent with the rest of the spec, so prefer keeping it
> like this.
>
>
>> +
>> +\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 configure 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}
>> +
>> +The operation of a virtio crypto device is driven by requests placed on the virtqueues.
>> +Requests consist of a queue-type specific header (specifying among others the operation)
>> +and an operation specific payload.
>> +
>> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated the device may support both session mode
>> +(See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation})
>> +and stateless mode operation requests.
>> +In stateless mode all operation parameters are supplied as a part of each request,
>> +while in session mode, some or all operation parameters are managed within the
>> +session. Stateless mode is guarded by feature bits 0-4 on a service level. If
>> +stateless mode is negotiated for a service, the service is available both in
>> +session and stateless mode; otherwise it's only available in session mode.
>
> How about the following?
>
> """
> If stateless mode is negotiated for a service, the service accepts both session mode and stateless
> requests; otherwise stateless mode requests are rejected (via operation status).
> """
>
> I prefer it because i think it makes clearer than session mode and stateless
> mode are concepts that apply on request and not on service (or let's say queue)
> level.
>
OK, make sense to me.
>> +
>> +\subsubsection{Operation Status}\label{sec:Device Types / Crypto Device / Device Operation / Operation status}
>> +The device MUST return a status code as part of the operation (both session
>> +operation and service operation) result. The valid operation status as follows:
>> +
>> +\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_NOSPC = 5,
>> + VIRTIO_CRYPTO_MAX
>> +};
>> +\end{lstlisting}
>> +
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK: success.
>> +\item VIRTIO_CRYPTO_BADMSG: authentication failed (only when AEAD decryption).
>> +\item VIRTIO_CRYPTO_NOTSUPP: operation or algorithm is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto operations.
>> +\item VIRTIO_CRYPTO_NOSPC: no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
>> + feature bit is negotiated).
>> +\item VIRTIO_CRYPTO_ERR: any failure not mentioned above occurs.
>> +\end{itemize*}
>> +
>
> Just thinking loud: We don't seem to be able to differentiate between device
> detected a driver (guest) bug, and something went wrong with the backend.
> I'm not sure differentiating between the two is useful in the first place.
>
Um, I get your point but other virtio devices also don't differentiate them :(
>> +\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}).
>> +
>> +The header for controlq is of the following form:
>> +\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;
>> + le32 reserved;
>> +};
>> +\end{lstlisting}
>> +
>> +The controlq request is composed of four parts:
>> +\begin{lstlisting}
>> +struct virtio_crypto_op_ctrl_req {
>> + /* Device read only portion */
>> +
>> + struct virtio_crypto_ctrl_header header;
>> +
>> +#define VIRTIO_CRYPTO_CTRLQ_OP_SPEC_HDR_LEGACY 56
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[flf_len];
>> +
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>> +
>> + /* Device write only portion */
>> +
>> + /* op result or completion status */
>> + u8 op_outcome[outcome_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{header} is a general header (see above).
>> +
>> +\field{op_flf} is the opcode (in \field{header}) specific fixed-length paramenters.
>> +
>> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit (see below).
>> +
>> +\field{op_vlf} is the opcode (in \field{header}) specific variable-length paramenters.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +\begin{note}
>> +The \field{vlf_len} of session-destroy operation and the hash-session-create
>> +operation is ZERO.
>> +\end{note}
>> +
>> +\begin{itemize*}
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_sym_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_sym_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_sym_create_session_vlf.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_hash_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_hash_create_session_flf if
>> + padded to 56 bytes if NOT negotiated.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_mac_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_mac_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_mac_create_session_vlf.
>> +\end{itemize*}
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_aead_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_aead_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_aead_create_session_vlf.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_DESTROY_SESSION
>> + or VIRTIO_CRYPTO_HASH_DESTROY_SESSION or VIRTIO_CRYPTO_MAC_DESTROY_SESSION or
>> + VIRTIO_CRYPTO_AEAD_DESTROY_SESSION then \field{op_flf} is struct
>> + virtio_crypto_destroy_session_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated and
>> + struct virtio_crypto_destroy_session_flf if padded to 56 bytes if NOT negotiated.
>> +\end{itemize*}
>> +
>> +\field{op_outcome} stores the result of operation and must be struct
>> +virtio_crypto_destroy_session_input for session-destroy operation or
>> +struct virtio_crypto_session_input.
>> +
>> +\field{outcome_len} is the size of the structure used.
>> +
>> +
>> +\paragraph{Session operation}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation}
>> +
>> +The session is a handle which describes the cryptographic parameters to be
>> +applied to a number of buffers.
>> +
>> +The following structure stores the result of session creation set by the device:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_session_input {
>> + /* Device write only portion */
>
> I think you cann drop this comment along with the following similar
> comments. We have already told whats device read only and what is
> device write only in virtio_crypto_op_ctrl_req.
>
> Restating it at each struct is redundant and IMHO just confusing. The
> R/W is determined by where does the struct sit in the request.
>
Agree, thanks.
>> + 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_flf {
>> + /* Device read only portion */
>> + le64 session_id;
>> +};
>> +
>> +struct virtio_crypto_destroy_session_input {
>> + /* Device write only portion */
>> + 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}
>> +
>> +The fixed-length paramenters of HASH session requests is as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_hash_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* See VIRTIO_CRYPTO_HASH_* above */
>> + le32 algo;
>> + /* hash result length */
>> + le32 hash_result_len;
>> +};
>> +\end{lstlisting}
>> +
>> +
>> +\subparagraph{Session operation: MAC session}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation / Session operation: MAC session}
>> +
>> +The fixed-length and the variable-length parameters of MAC session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_mac_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> +
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{auth_key} is specified in \field{auth_key_len} in the struct
>> +virtio_crypto_mac_create_session_flf.
>> +
>> +
>> +\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 could be the CIPHER algorithms request
>> +or the chain algorithms (chaining CIPHER and HASH/MAC) request.
>> +
>> +The fixed-length and the variable-length parameters of CIPHER session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_cipher_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> +
>> + /* The cipher key */
>> + u8 cipher_key[keylen];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{cipher_key} is specified in \field{keylen} in the struct
>> +virtio_crypto_cipher_session_flf.
>> +
>> +The fixed-length and the variable-length parameters of Chain session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_alg_chain_session_flf {
>> + /* Device read only portion */
>> +
>> +#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_flf cipher_hdr;
>> +
>> +#define VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE 16
>> + /* fixed length fields, algo specific */
>> + u8 algo_flf[VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE];
>> +
>> + /* length of the additional authenticated data (AAD) in bytes */
>> + le32 aad_len;
>> + le32 padding;
>> +};
>> +
>> +struct virtio_crypto_alg_chain_session_vlf {
>> + /* Device read only portion */
>> +
>> + /* The cipher key */
>> + u8 cipher_key[keylen];
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{hash_mode} decides the type used by \field{algo_flf}.
>> +
>> +\field{algo_flf} is fixed to 16 bytes and MUST contains or be one of
>> +the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_hash_create_session_flf
>> +\item struct virtio_crypto_mac_create_session_flf
>> +\end{itemize*}
>> +The data of unused part (if has) in \field{algo_flf} will be ignored.
>> +
>> +The length of \field{cipher_key} is specified in \field{keylen} in \field{cipher_hdr}.
>> +
>> +The length of \field{auth_key} is specified in \field{auth_key_len} in struct
>> +virtio_crypto_mac_create_session_flf.
>> +
>> +The fixed-length parameters of Symmetric session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_sym_create_session_flf {
>> + /* Device read only portion */
>> +
>> +#define VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE 48
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE];
>> +
>> +/* 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}
>> +
>> +\field{op_flf} is fixed to 48 bytes, MUST contains or be one of
>> +the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_cipher_session_flf
>> +\item struct virtio_crypto_alg_chain_session_flf
>> +\end{itemize*}
>> +The data of unused part (if has) in \field{op_flf} will be ignored.
>> +
>> +\field{op_type} decides the type used by \field{op_flf}.
>> +
>> +The variable-length parameters of Symmetric session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_sym_create_session_vlf {
>> + /* Device read only portion */
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{op_vlf} MUST contains or be one of the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_cipher_session_vlf
>> +\item struct virtio_crypto_alg_chain_session_vlf
>> +\end{itemize*}
>> +
>> +\field{op_type} in struct virtio_crypto_sym_create_session_flf decides the
>> +type used by \field{op_vlf}.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +
>> +
>> +\subparagraph{Session operation: AEAD session}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation / Session operation: AEAD session}
>> +
>> +The fixed-length and the variable-length parameters of AEAD session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_aead_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> + u8 key[key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{key} is specified in \field{key_len} in struct
>> +virtio_crypto_aead_create_session_flf.
>> +
>> +
>> +\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 \field{opcode} field based on service type: CIPHER, HASH, MAC, or AEAD.
>> +\item The driver MUST set the control general header, the opcode specific header,
>> + the opcode specific extra parameters and the opcode specific outcome buffer in turn.
>> + See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}.
>> +\item The driver MUST set the \field{reversed} field to zero.
>> +\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 use the corresponding opcode specific structure according to the
>> + \field{opcode} in the control general header.
>> +\item The device MUST extract extra parameters according to the structures used.
>> +\item The device MUST set the \field{status} field to one of the following values of enum
>> + VIRTIO_CRYPTO_STATUS after finish a session creation:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_NOSPC if no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
>> + feature bit is negotiated).
>> +\item VIRTIO_CRYPTO_ERR if failure not mentioned above occurs.
>> +\end{itemize*}
>> +\item The device MUST set the \field{session_id} field to a unique session identifier only
>> + if the status is set to VIRTIO_CRYPTO_OK.
>> +\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 following values of enum VIRTIO_CRYPTO_STATUS.
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
>> +\item VIRTIO_CRYPTO_ERR if any failure occurs.
>> +\end{itemize*}
>> +\end{itemize*}
>> +
>> +
>> +\subsubsection{Data Virtqueue}\label{sec:Device Types / Crypto Device / Device Operation / Data Virtqueue}
>> +
>> +The driver uses the data virtqueues to transmit crypto operation requests to the device,
>> +and completes the crypto operations.
>> +
>> +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_SESSION_MODE 1
>> + /* control flag to control the request */
>> + le32 flag;
>> + le32 padding;
>> +};
>> +\end{lstlisting}
>> +
>> +\begin{note}
>> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
>> +is not negotiated then <SERVICE> retuqests with the \field{flag} (in struct
>
>
> s/retuqests/requests
>
OK.
>> +virtio_crypto_op_header) is ZERO need to be rejected. If VIRTIO_CRYPTO_F_REVISION_1 is
>> +not negotiated the \field{flag} is ignored.
>> +\end{note}
>> +
>
> I think your formulation is a bit hard to understand.
>
> I would prefer:
> +\begin{note}
> +If VIRTIO_CRYPTO_F_REVISION_1 is not negotiated the \field{flag} is ignored.
> +
> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
> +is not negotiated, then the device should reject <SERVICE> requests if
> +VIRTIO_CRYPTO_FLAG_SESSION_MODE is not set (in \field{flag}).
> +\end{note}
> +
>
Much better, thanks. :)
>> +The dataq request is composed of four parts:
>> +\begin{lstlisting}
>> +struct virtio_crypto_op_data_req {
>> + /* Device read only portion */
>> +
>> + struct virtio_crypto_op_header header;
>> +
>> +#define VIRTIO_CRYPTO_DATAQ_OP_SPEC_HDR_LEGACY 48
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[flf_len];
>> +
>> + /* Device read && write portion */
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>
> Descriptors are either read or write. You need read && write (whatever the
> sematic is) because you throw things together that don't belong together.
>
> I would try to do the same as for the ctrl requests:
> + * Device write only portion */
> + u8 op_outcome;
>
> and describe the outcome on a per service basis. Also see my
> comments about the dst_data_len below.
>
>> +
>> + /* Device write only portion */
>> + struct virtio_crypto_inhdr inhdr;
>> +};
>> +\end{lstlisting}
>> +
>> +\field{header} is a general header (see above).
>> +
>> +\field{op_flf} is the opcode (in \field{header}) specific header.
>> +
>> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit
>> +(see below).
>> +
>> +\field{op_vlf} is the opcode (in \field{header}) specific parameters.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +
>> +\begin{itemize*}
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_ENCRYPT
>> + or VIRTIO_CRYPTO_CIPHER_DECRYPT then:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_sym_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_sym_data_vlf_stateless.
>
> What does this _data_ (in the name) symbolise?
The structure with "_data_" in the name is used by data operation (vs session
create/destroy operation).
>
>> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_sym_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_sym_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_sym_data_vlf.
>> + \end{itemize*}
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_hash_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_hash_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_hash_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_hash_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_hash_data_vlf.
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_mac_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_mac_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_mac_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_mac_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_mac_data_vlf.
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_ENCRYPT
>> + or VIRTIO_CRYPTO_AEAD_DECRYPT then:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_aead_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_aead_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_aead_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_aead_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_aead_data_vlf.
>> +\end{itemize*}
>> +
>> +\field{inhdr} is a unified input header that used to return the status of
>> +the operations, 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_data_flf {
>> + /* length of source data */
>> + le32 src_data_len;
>> + /* hash result length */
>> + le32 hash_result_len;
>> +};
>> +
>> +struct virtio_crypto_hash_data_vlf {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +Each data request uses the virtio_crypto_hash_data_flf structure and the
>> +virtio_crypto_hash_data_vlfto structure to store information used to run the
>> +HASH operations.
>> +
>> +\field{src_data} is the source data that will be processed.
>> +\field{src_data_len} is the length of source data.
>> +\field{hash_result} is the result data and \field{hash_result_len} is the length
>> +of it.
>> +
>> +Stateless mode HASH service requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_hash_data_flf_stateless {
>> + 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_vlf_stateless {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\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_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 ZERO and MUST set the fields in struct
>> + virtio_crypto_hash_data_flf_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_SESSION_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 The device MUST use the corresponding structure according to the \field{opcode}
>> + in the data general header.
>> +\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
>> + following values of enum VIRTIO_CRYPTO_STATUS:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if the operation success.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
>> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
>> +\end{itemize*}
>> +\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_data_flf {
>> + struct virtio_crypto_hash_data_flf hdr;
>> +};
>> +
>> +struct virtio_crypto_mac_data_vlf {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +Each request uses the virtio_crypto_mac_data_flf structure and the
>> +virtio_crypto_mac_data_vlf structure to store information used to run the
>> +MAC operations.
>> +
>> +\field{src_data} is the source data that will be processed.
>> +\field{src_data_len} is the length of source data.
>> +\field{hash_result} is the result data and \field{hash_result_len} is the length
>> +of it.
>> +
>> +Stateless mode MAC service requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_mac_data_flf_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_vlf_stateless {
>> + /* Device read only portion */
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{auth_key} is the authenticated key that will be used during the process.
>> +\field{auth_key_len} is the length of the key.
>> +
>> +\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_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 ZERO and MUST set the fields in struct
>> + virtio_crypto_mac_data_flf_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_SESSION_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_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
>> + following values of enum VIRTIO_CRYPTO_STATUS:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if the operation success.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
>> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
>> +\end{itemize*}
>> +\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_data_flf {
>> + /*
>> + * 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_vlf {
>> + /* Device read only portion */
>> +
>> + /*
>> + * 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 write only portion */
>> + /* Destination data */
>> + u8 dst_data[dst_data_len];
>
>
> I'm a bit puzzled about dst_data_len. I'm by no means a crypto expert,
> and that is probably the very reason of my discomfort.
>
> I've tried to figure out how dst_data_len is used and expected to find
> a place that checks, that at least a sufficiently large buffer was provided.
>
> I've also assumed that the src_data_len is likely to imply the dst_data_len
> for any given algorithm. Furthermore, I even hypothesised that the both
> lengths are the same. All based on what I remember about block ciphers.
>
> If that hypothesis is right, then I don't understand why do we need
> both src_data_len and dst_data_len.
>
> Since dst_data_len is device read only, the driver I figure the driver
> needs to know the exact length (since I cant figure out, based on this
> spec, how is it supposed to be told by the device which part of the
> buffer is the result and which part garbage). So the only sane usage
> I was able to come up with is to avoid the device overwritting other
> parts of the requests device writtable part because of a driver
> bug (wrong dst_data_len). But as I've said I could not find the corresponding
> code in qemu.
>
I'm sorry that I'm not a crypto expert too :(
For hash, hmac and aead serivce, there is no doubt that 'dst_len' can be
difference with the 'src_len'. Only the sym cipher serivice we cannot sure.
But I think we'd better not hypothesis they are the same, I found the Intel QAT
driver also use 'src_len' and 'dst_len' for SYM service:
'''
CpaPhysicalAddr srcBuffer;
/**< Physical address of the source buffer on which to operate.
* This is either:
*
* - The location of the data, of length srcBufferLen; or,
* - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then
* srcBuffer contains the location where a @ref CpaPhysBufferList is
* stored. In this case, the CpaPhysBufferList MUST be aligned
* on an 8-byte boundary.
* - For optimum performance, the buffer should only contain the data
* region that the cryptographic operation(s) must be performed on.
* Any additional data in the source buffer may be copied to the
* destination buffer and this copy may degrade performance.
*/
Cpa32U srcBufferLen;
/**< Length of source buffer, or @ref CPA_DP_BUFLIST. */
CpaPhysicalAddr dstBuffer;
/**< Physical address of the destination buffer on which to operate.
* This is either:
*
* - The location of the data, of length srcBufferLen; or,
* - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then
* srcBuffer contains the location where a @ref CpaPhysBufferList is
* stored. In this case, the CpaPhysBufferList MUST be aligned
* on an 8-byte boundary.
*
* For "in-place" operation, the dstBuffer may be identical to the
* srcBuffer.
*/
Cpa32U dstBufferLen;
/**< Length of destination buffer, or @ref CPA_DP_BUFLIST. */
'''
and
'''
/* Check that src buffer Len = dst buffer Len
Note this also checks that they are of the same type */
if (pRequest->srcBufferLen != pRequest->dstBufferLen)
{
LAC_INVALID_PARAM_LOG(
"Source and Destination buffer lengths need to be equal");
return CPA_STATUS_INVALID_PARAM;
}
'''
The qemu code should check if 'src_len' and 'dst_len' is the same.
> Anyway providing some more background for the guys only superficially
> involved with crypto (like me) would be appreciated.
>
> I will stop here for now. I read the rest real quick and I did not
> see anything major. I think we are slowly getting there.
>
> Regards,
> Halil
>
>
> .
>
--
Regards,
Longpeng(Mike)
^ permalink raw reply [flat|nested] 31+ messages in thread
* [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-07-20 12:01 ` Longpeng (Mike)
0 siblings, 0 replies; 31+ messages in thread
From: Longpeng (Mike) @ 2018-07-20 12:01 UTC (permalink / raw)
To: Halil Pasic
Cc: qemu-devel, virtio-dev, mst, cornelia.huck, stefanha, denglingli,
Jani.Kokkonen, Ola.Liljedahl, Varun.Sethi, xin.zeng,
brian.a.keating, liang.j.ma, john.griffin, weidong.huang, agraf,
jasowang, vincent.jardin, arei.gonglei, wangxinxin.wang,
jianjay.zhou
On 2018/1/10 1:05, Halil Pasic wrote:
>
>
> On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
>> From: Gonglei <arei.gonglei@huawei.com>
>>
>> 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 <arei.gonglei@huawei.com>
>> Signed-off-by: Zhoujian <jianjay.zhou@huawei.com>
>> Signed-off-by: Longpeng(Mike) <longpeng2@huawei.com>
>> ---
>> acknowledgements.tex | 4 +
>> content.tex | 2 +
>> virtio-crypto.tex | 1525 ++++++++++++++++++++++++++++++++++++++++++++++++++
>> 3 files changed, 1531 insertions(+)
>> create mode 100644 virtio-crypto.tex
>>
>> diff --git a/acknowledgements.tex b/acknowledgements.tex
>> index 2d893d9..cdde247 100644
>> --- a/acknowledgements.tex
>> +++ b/acknowledgements.tex
>> @@ -16,10 +16,13 @@ Daniel Kiper, Oracle \newline
>> Geoff Brown, Machine-to-Machine Intelligence (M2MI) Corporation \newline
>> Gershon Janssen, Individual Member \newline
>> James Bottomley, Parallels IP Holdings GmbH \newline
>> +Jian Zhou, Huawei \newline
>> +Lei Gong, Huawei \newline
>> Luiz Capitulino, Red Hat \newline
>> Michael S. Tsirkin, Red Hat \newline
>> Paolo Bonzini, Red Hat \newline
>> Pawel Moll, ARM \newline
>> +Peng Long, Huawei \newline
>> Richard Sohn, Alcatel-Lucent \newline
>> Rusty Russell, IBM \newline
>> Sasha Levin, Oracle \newline
>> @@ -38,6 +41,7 @@ Brian Foley, ARM \newline
>> David Alan Gilbert, Red Hat \newline
>> Fam Zheng, Red Hat \newline
>> Gerd Hoffmann, Red Hat \newline
>> +Halil Pasic, IBM \newline
>> Jason Wang, Red Hat \newline
>> Laura Novich, Red Hat \newline
>> Patrick Durusau, Technical Advisory Board, OASIS \newline
>> diff --git a/content.tex b/content.tex
>> index c840588..d1d3b09 100644
>> --- a/content.tex
>> +++ b/content.tex
>> @@ -5819,6 +5819,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 these device-independent feature bits defined:
>> diff --git a/virtio-crypto.tex b/virtio-crypto.tex
>> new file mode 100644
>> index 0000000..4bd5b51
>> --- /dev/null
>> +++ b/virtio-crypto.tex
>> @@ -0,0 +1,1525 @@
>> +\section{Crypto Device}\label{sec:Device Types / Crypto Device}
>> +
>> +The virtio crypto device is a virtual cryptography device as well as a
>> +virtual cryptographic accelerator. The virtio crypto device provides the
>> +following crypto services: CIPHER, MAC, HASH, and AEAD. Virtio crypto
>> +devices have a single control queue and at least one data queue. Crypto
>> +operation requests are placed into a data queue, and serviced by the
>> +device. Some crypto operation requests are only valid in the context of a
>> +session. The role of the control queue is facilitating control operation
>> +requests. Sessions management is realized with control operation
>> +requests.
>> +
>> +\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}
>> +
>> +\begin{description}
>> +\item VIRTIO_CRYPTO_F_REVISION_1 (0) revision 1. Revision 1 has a specific
>> + request format and other enhancements (which result in some additional
>> + requirements).
>> +\item VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE (1) stateless mode requests are
>> + supported by the CIPHER service.
>> +\item VIRTIO_CRYPTO_F_HASH_STATELESS_MODE (2) stateless mode requests are
>> + supported by the HASH service.
>> +\item VIRTIO_CRYPTO_F_MAC_STATELESS_MODE (3) stateless mode requests are
>> + supported by the MAC service.
>> +\item VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE (4) stateless mode requests are
>> + supported by the AEAD service.
>> +\end{description}
>> +
>> +
>> +\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_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_HASH_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_MAC_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\item[VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_REVISION_1.
>> +\end{description}
>> +
>> +\subsection{Supported crypto services}\label{sec:Device Types / Crypto Device / Supported crypto services}
>> +
>> +The following crypto services are defined:
>> +
>> +\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 designate bits used to indicate the which of crypto services are
>> +offered by the device as described in, 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 designate the algorithm in (CIPHER type) crypto
>> +operation requests, 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 designate the algorithm in (HASH type) crypto
>> +operation 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 designate the algorithm in (MAC type) crypto
>> +operation requests, 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 designate the algorithm in (DEAD type) crypto
>> +operation requests, 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 Currently, only one \field(status) bit is defined: VIRTIO_CRYPTO_S_HW_READY
>> + set indicates that the device is ready to process requests, this bit is read-only
>> + for the driver
>> +\begin{lstlisting}
>> +#define VIRTIO_CRYPTO_S_HW_READY (1 << 0)
>> +\end{lstlisting}
>> +
>> +\item[\field{max_dataqueues}] is the maximum number of data virtqueues that can
>> + be configured by the device. The driver MAY use only one data queue, or it
>> + can use more to achieve better performance.
>> +
>> +\item[\field{crypto_services}] crypto service offered, see \ref{sec:Device Types / Crypto Device / Supported crypto services}.
>> +
>> +\item[\field{cipher_algo_l}] CIPHER algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
>> +
>> +\item[\field{cipher_algo_h}] CIPHER algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.
>> +
>> +\item[\field{hash_algo}] HASH algorithms bits, see \ref{sec:Device Types / Crypto Device / Supported crypto services / HASH services}.
>> +
>> +\item[\field{mac_algo_l}] MAC algorithms bits 0-31, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
>> +
>> +\item[\field{mac_algo_h}] MAC algorithms bits 32-63, see \ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.
>> +
>> +\item[\field{aead_algo}] AEAD algorithms bits, 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.
>
> I can't find what happens if this limit isn't honored by the driver. Moreover
> reading it is only SHOULD. Is it undefined behavior or should the device reject/fail
> such requests? I think in qemu implementation we fail the request.
>
Yes, the request will fail.
I'll describe this in driver normative. How about the following:
The driver MUST guarantee the \filed{keylen} within the
\field{max_cipher_key_len} of the device configuration, otherwise the request
will fail.
The driver MUST guarantee the \filed{auth_key_len} within the
\field{max_auth_key_len} of the device configuration, otherwise the request will
fail.
> This question is only about niceness. We are already good enough, IMHO:
> since the implementer of the driver can't be sure what is going to happen
> if the driver disregards max_cipher_key_len it is already an implicit
> SHOULD.
>
>> +
>> +\item[\field{max_auth_key_len}] is the maximum length of authenticated key supported by the device.
>
> Same here.
>
OK.
>> +
>> +\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
>
> s/device/device.
>
OK.
> What a content of a request and how is its size calculated? Where is this defined.
>
In qemu, the size of the reuqest's content of SYM is "iv_len + aad_len + src_len
+ dst_len + hash_result_len". Furthermore, the content is the variable-length
parameters of data operation.
So how about:
\item[\field{max_size}] is the maximum size of the variable-length parameters of
data operation of each crypto request's content supported by the device.
> The question what happens if not honored applies similarly.
>
How about:
The driver MUST guarantee the size of the variable-length parameters of data
operation of each crypto request's content within the \field{max_size} of the
device configuration, otherwise the request will fail as the driver MUST reset
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 the \field{status} with valid flags, undefined flags MUST NOT be set.
>> +\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 for each service advertised by \field{crypto_services}.
>> + The device MUST NOT set the not defined algorithms bits.
>> +\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 \field{status} from the bottom bit of status to check whether the
>> + VIRTIO_CRYPTO_S_HW_READY is set, and the driver MUST reread it after device reset.
>> +\item The driver MUST NOT transmit any requests to the device if the VIRTIO_CRYPTO_S_HW_READY 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 SHOULD ignore the not defined algorithms bits.
>> +\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*}
>
> Seems to like a common practice in the virtio spec to say SHOULD read some
> config space parameter in a driver normative but then having no driver normative
> about the operational implications of the parameter.
>
> While I do think that the reader is usually fully capable of inferring
> the operational requirement, I find it a bit strange: having the operational
> stuff explicit (and possibly needs to be read from the config space implicit)
> seems more straight forward to me.
>
> Anyway, you are consistent with the rest of the spec, so prefer keeping it
> like this.
>
>
>> +
>> +\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 configure 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}
>> +
>> +The operation of a virtio crypto device is driven by requests placed on the virtqueues.
>> +Requests consist of a queue-type specific header (specifying among others the operation)
>> +and an operation specific payload.
>> +
>> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated the device may support both session mode
>> +(See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation})
>> +and stateless mode operation requests.
>> +In stateless mode all operation parameters are supplied as a part of each request,
>> +while in session mode, some or all operation parameters are managed within the
>> +session. Stateless mode is guarded by feature bits 0-4 on a service level. If
>> +stateless mode is negotiated for a service, the service is available both in
>> +session and stateless mode; otherwise it's only available in session mode.
>
> How about the following?
>
> """
> If stateless mode is negotiated for a service, the service accepts both session mode and stateless
> requests; otherwise stateless mode requests are rejected (via operation status).
> """
>
> I prefer it because i think it makes clearer than session mode and stateless
> mode are concepts that apply on request and not on service (or let's say queue)
> level.
>
OK, make sense to me.
>> +
>> +\subsubsection{Operation Status}\label{sec:Device Types / Crypto Device / Device Operation / Operation status}
>> +The device MUST return a status code as part of the operation (both session
>> +operation and service operation) result. The valid operation status as follows:
>> +
>> +\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_NOSPC = 5,
>> + VIRTIO_CRYPTO_MAX
>> +};
>> +\end{lstlisting}
>> +
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK: success.
>> +\item VIRTIO_CRYPTO_BADMSG: authentication failed (only when AEAD decryption).
>> +\item VIRTIO_CRYPTO_NOTSUPP: operation or algorithm is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto operations.
>> +\item VIRTIO_CRYPTO_NOSPC: no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
>> + feature bit is negotiated).
>> +\item VIRTIO_CRYPTO_ERR: any failure not mentioned above occurs.
>> +\end{itemize*}
>> +
>
> Just thinking loud: We don't seem to be able to differentiate between device
> detected a driver (guest) bug, and something went wrong with the backend.
> I'm not sure differentiating between the two is useful in the first place.
>
Um, I get your point but other virtio devices also don't differentiate them :(
>> +\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}).
>> +
>> +The header for controlq is of the following form:
>> +\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;
>> + le32 reserved;
>> +};
>> +\end{lstlisting}
>> +
>> +The controlq request is composed of four parts:
>> +\begin{lstlisting}
>> +struct virtio_crypto_op_ctrl_req {
>> + /* Device read only portion */
>> +
>> + struct virtio_crypto_ctrl_header header;
>> +
>> +#define VIRTIO_CRYPTO_CTRLQ_OP_SPEC_HDR_LEGACY 56
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[flf_len];
>> +
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>> +
>> + /* Device write only portion */
>> +
>> + /* op result or completion status */
>> + u8 op_outcome[outcome_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{header} is a general header (see above).
>> +
>> +\field{op_flf} is the opcode (in \field{header}) specific fixed-length paramenters.
>> +
>> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit (see below).
>> +
>> +\field{op_vlf} is the opcode (in \field{header}) specific variable-length paramenters.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +\begin{note}
>> +The \field{vlf_len} of session-destroy operation and the hash-session-create
>> +operation is ZERO.
>> +\end{note}
>> +
>> +\begin{itemize*}
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_sym_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_sym_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_sym_create_session_vlf.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_hash_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_hash_create_session_flf if
>> + padded to 56 bytes if NOT negotiated.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_mac_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_mac_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_mac_create_session_vlf.
>> +\end{itemize*}
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_CREATE_SESSION
>> + then \field{op_flf} is struct virtio_crypto_aead_create_session_flf if
>> + VIRTIO_CRYPTO_F_REVISION_1 is negotiated and struct virtio_crypto_aead_create_session_flf if
>> + padded to 56 bytes if NOT negotiated, and \field{op_vlf} is struct
>> + virtio_crypto_aead_create_session_vlf.
>> +\item If the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_DESTROY_SESSION
>> + or VIRTIO_CRYPTO_HASH_DESTROY_SESSION or VIRTIO_CRYPTO_MAC_DESTROY_SESSION or
>> + VIRTIO_CRYPTO_AEAD_DESTROY_SESSION then \field{op_flf} is struct
>> + virtio_crypto_destroy_session_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated and
>> + struct virtio_crypto_destroy_session_flf if padded to 56 bytes if NOT negotiated.
>> +\end{itemize*}
>> +
>> +\field{op_outcome} stores the result of operation and must be struct
>> +virtio_crypto_destroy_session_input for session-destroy operation or
>> +struct virtio_crypto_session_input.
>> +
>> +\field{outcome_len} is the size of the structure used.
>> +
>> +
>> +\paragraph{Session operation}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation}
>> +
>> +The session is a handle which describes the cryptographic parameters to be
>> +applied to a number of buffers.
>> +
>> +The following structure stores the result of session creation set by the device:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_session_input {
>> + /* Device write only portion */
>
> I think you cann drop this comment along with the following similar
> comments. We have already told whats device read only and what is
> device write only in virtio_crypto_op_ctrl_req.
>
> Restating it at each struct is redundant and IMHO just confusing. The
> R/W is determined by where does the struct sit in the request.
>
Agree, thanks.
>> + 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_flf {
>> + /* Device read only portion */
>> + le64 session_id;
>> +};
>> +
>> +struct virtio_crypto_destroy_session_input {
>> + /* Device write only portion */
>> + 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}
>> +
>> +The fixed-length paramenters of HASH session requests is as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_hash_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* See VIRTIO_CRYPTO_HASH_* above */
>> + le32 algo;
>> + /* hash result length */
>> + le32 hash_result_len;
>> +};
>> +\end{lstlisting}
>> +
>> +
>> +\subparagraph{Session operation: MAC session}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation / Session operation: MAC session}
>> +
>> +The fixed-length and the variable-length parameters of MAC session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_mac_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> +
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{auth_key} is specified in \field{auth_key_len} in the struct
>> +virtio_crypto_mac_create_session_flf.
>> +
>> +
>> +\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 could be the CIPHER algorithms request
>> +or the chain algorithms (chaining CIPHER and HASH/MAC) request.
>> +
>> +The fixed-length and the variable-length parameters of CIPHER session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_cipher_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> +
>> + /* The cipher key */
>> + u8 cipher_key[keylen];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{cipher_key} is specified in \field{keylen} in the struct
>> +virtio_crypto_cipher_session_flf.
>> +
>> +The fixed-length and the variable-length parameters of Chain session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_alg_chain_session_flf {
>> + /* Device read only portion */
>> +
>> +#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_flf cipher_hdr;
>> +
>> +#define VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE 16
>> + /* fixed length fields, algo specific */
>> + u8 algo_flf[VIRTIO_CRYPTO_ALG_CHAIN_SESS_OP_SPEC_HDR_SIZE];
>> +
>> + /* length of the additional authenticated data (AAD) in bytes */
>> + le32 aad_len;
>> + le32 padding;
>> +};
>> +
>> +struct virtio_crypto_alg_chain_session_vlf {
>> + /* Device read only portion */
>> +
>> + /* The cipher key */
>> + u8 cipher_key[keylen];
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{hash_mode} decides the type used by \field{algo_flf}.
>> +
>> +\field{algo_flf} is fixed to 16 bytes and MUST contains or be one of
>> +the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_hash_create_session_flf
>> +\item struct virtio_crypto_mac_create_session_flf
>> +\end{itemize*}
>> +The data of unused part (if has) in \field{algo_flf} will be ignored.
>> +
>> +The length of \field{cipher_key} is specified in \field{keylen} in \field{cipher_hdr}.
>> +
>> +The length of \field{auth_key} is specified in \field{auth_key_len} in struct
>> +virtio_crypto_mac_create_session_flf.
>> +
>> +The fixed-length parameters of Symmetric session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_sym_create_session_flf {
>> + /* Device read only portion */
>> +
>> +#define VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE 48
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[VIRTIO_CRYPTO_SYM_SESS_OP_SPEC_HDR_SIZE];
>> +
>> +/* 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}
>> +
>> +\field{op_flf} is fixed to 48 bytes, MUST contains or be one of
>> +the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_cipher_session_flf
>> +\item struct virtio_crypto_alg_chain_session_flf
>> +\end{itemize*}
>> +The data of unused part (if has) in \field{op_flf} will be ignored.
>> +
>> +\field{op_type} decides the type used by \field{op_flf}.
>> +
>> +The variable-length parameters of Symmetric session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_sym_create_session_vlf {
>> + /* Device read only portion */
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{op_vlf} MUST contains or be one of the following types:
>> +\begin{itemize*}
>> +\item struct virtio_crypto_cipher_session_vlf
>> +\item struct virtio_crypto_alg_chain_session_vlf
>> +\end{itemize*}
>> +
>> +\field{op_type} in struct virtio_crypto_sym_create_session_flf decides the
>> +type used by \field{op_vlf}.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +
>> +
>> +\subparagraph{Session operation: AEAD session}\label{sec:Device Types / Crypto Device / Device
>> +Operation / Control Virtqueue / Session operation / Session operation: AEAD session}
>> +
>> +The fixed-length and the variable-length parameters of AEAD session requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_aead_create_session_flf {
>> + /* Device read only portion */
>> +
>> + /* 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_vlf {
>> + /* Device read only portion */
>> + u8 key[key_len];
>> +};
>> +\end{lstlisting}
>> +
>> +The length of \field{key} is specified in \field{key_len} in struct
>> +virtio_crypto_aead_create_session_flf.
>> +
>> +
>> +\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 \field{opcode} field based on service type: CIPHER, HASH, MAC, or AEAD.
>> +\item The driver MUST set the control general header, the opcode specific header,
>> + the opcode specific extra parameters and the opcode specific outcome buffer in turn.
>> + See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}.
>> +\item The driver MUST set the \field{reversed} field to zero.
>> +\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 use the corresponding opcode specific structure according to the
>> + \field{opcode} in the control general header.
>> +\item The device MUST extract extra parameters according to the structures used.
>> +\item The device MUST set the \field{status} field to one of the following values of enum
>> + VIRTIO_CRYPTO_STATUS after finish a session creation:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_NOSPC if no free session ID (only when the VIRTIO_CRYPTO_F_REVISION_1
>> + feature bit is negotiated).
>> +\item VIRTIO_CRYPTO_ERR if failure not mentioned above occurs.
>> +\end{itemize*}
>> +\item The device MUST set the \field{session_id} field to a unique session identifier only
>> + if the status is set to VIRTIO_CRYPTO_OK.
>> +\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 following values of enum VIRTIO_CRYPTO_STATUS.
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if a session is created successfully.
>> +\item VIRTIO_CRYPTO_ERR if any failure occurs.
>> +\end{itemize*}
>> +\end{itemize*}
>> +
>> +
>> +\subsubsection{Data Virtqueue}\label{sec:Device Types / Crypto Device / Device Operation / Data Virtqueue}
>> +
>> +The driver uses the data virtqueues to transmit crypto operation requests to the device,
>> +and completes the crypto operations.
>> +
>> +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_SESSION_MODE 1
>> + /* control flag to control the request */
>> + le32 flag;
>> + le32 padding;
>> +};
>> +\end{lstlisting}
>> +
>> +\begin{note}
>> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
>> +is not negotiated then <SERVICE> retuqests with the \field{flag} (in struct
>
>
> s/retuqests/requests
>
OK.
>> +virtio_crypto_op_header) is ZERO need to be rejected. If VIRTIO_CRYPTO_F_REVISION_1 is
>> +not negotiated the \field{flag} is ignored.
>> +\end{note}
>> +
>
> I think your formulation is a bit hard to understand.
>
> I would prefer:
> +\begin{note}
> +If VIRTIO_CRYPTO_F_REVISION_1 is not negotiated the \field{flag} is ignored.
> +
> +If VIRTIO_CRYPTO_F_REVISION_1 is negotiated but VIRTIO_CRYPTO_F_<SERVICE>_STATELESS_MODE
> +is not negotiated, then the device should reject <SERVICE> requests if
> +VIRTIO_CRYPTO_FLAG_SESSION_MODE is not set (in \field{flag}).
> +\end{note}
> +
>
Much better, thanks. :)
>> +The dataq request is composed of four parts:
>> +\begin{lstlisting}
>> +struct virtio_crypto_op_data_req {
>> + /* Device read only portion */
>> +
>> + struct virtio_crypto_op_header header;
>> +
>> +#define VIRTIO_CRYPTO_DATAQ_OP_SPEC_HDR_LEGACY 48
>> + /* fixed length fields, opcode specific */
>> + u8 op_flf[flf_len];
>> +
>> + /* Device read && write portion */
>> + /* variable length fields, opcode specific */
>> + u8 op_vlf[vlf_len];
>
> Descriptors are either read or write. You need read && write (whatever the
> sematic is) because you throw things together that don't belong together.
>
> I would try to do the same as for the ctrl requests:
> + * Device write only portion */
> + u8 op_outcome;
>
> and describe the outcome on a per service basis. Also see my
> comments about the dst_data_len below.
>
>> +
>> + /* Device write only portion */
>> + struct virtio_crypto_inhdr inhdr;
>> +};
>> +\end{lstlisting}
>> +
>> +\field{header} is a general header (see above).
>> +
>> +\field{op_flf} is the opcode (in \field{header}) specific header.
>> +
>> +\field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit
>> +(see below).
>> +
>> +\field{op_vlf} is the opcode (in \field{header}) specific parameters.
>> +
>> +\field{vlf_len} is the size of the specific structure used.
>> +
>> +\begin{itemize*}
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_CIPHER_ENCRYPT
>> + or VIRTIO_CRYPTO_CIPHER_DECRYPT then:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_sym_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_sym_data_vlf_stateless.
>
> What does this _data_ (in the name) symbolise?
The structure with "_data_" in the name is used by data operation (vs session
create/destroy operation).
>
>> + \item If VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_sym_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_sym_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_sym_data_vlf.
>> + \end{itemize*}
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_HASH:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_hash_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_hash_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_HASH_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_hash_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_hash_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_hash_data_vlf.
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_MAC:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_mac_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_mac_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_MAC_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_mac_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_mac_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_mac_data_vlf.
>> +\item If the the opcode (in \field{header}) is VIRTIO_CRYPTO_AEAD_ENCRYPT
>> + or VIRTIO_CRYPTO_AEAD_DECRYPT then:
>> + \begin{itemize*}
>> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is negotiated, \field{op_flf} is
>> + struct virtio_crypto_aead_data_flf_stateless, and \field{op_vlf} is struct
>> + virtio_crypto_aead_data_vlf_stateless.
>> + \item If VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE is NOT negotiated, \field{op_flf}
>> + is struct virtio_crypto_aead_data_flf if VIRTIO_CRYPTO_F_REVISION_1 is negotiated
>> + and struct virtio_crypto_aead_data_flf if padded to 48 bytes if NOT negotiated,
>> + and \field{op_vlf} is struct virtio_crypto_aead_data_vlf.
>> +\end{itemize*}
>> +
>> +\field{inhdr} is a unified input header that used to return the status of
>> +the operations, 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_data_flf {
>> + /* length of source data */
>> + le32 src_data_len;
>> + /* hash result length */
>> + le32 hash_result_len;
>> +};
>> +
>> +struct virtio_crypto_hash_data_vlf {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +Each data request uses the virtio_crypto_hash_data_flf structure and the
>> +virtio_crypto_hash_data_vlfto structure to store information used to run the
>> +HASH operations.
>> +
>> +\field{src_data} is the source data that will be processed.
>> +\field{src_data_len} is the length of source data.
>> +\field{hash_result} is the result data and \field{hash_result_len} is the length
>> +of it.
>> +
>> +Stateless mode HASH service requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_hash_data_flf_stateless {
>> + 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_vlf_stateless {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\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_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 ZERO and MUST set the fields in struct
>> + virtio_crypto_hash_data_flf_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_SESSION_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 The device MUST use the corresponding structure according to the \field{opcode}
>> + in the data general header.
>> +\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
>> + following values of enum VIRTIO_CRYPTO_STATUS:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if the operation success.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
>> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
>> +\end{itemize*}
>> +\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_data_flf {
>> + struct virtio_crypto_hash_data_flf hdr;
>> +};
>> +
>> +struct virtio_crypto_mac_data_vlf {
>> + /* Device read only portion */
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +Each request uses the virtio_crypto_mac_data_flf structure and the
>> +virtio_crypto_mac_data_vlf structure to store information used to run the
>> +MAC operations.
>> +
>> +\field{src_data} is the source data that will be processed.
>> +\field{src_data_len} is the length of source data.
>> +\field{hash_result} is the result data and \field{hash_result_len} is the length
>> +of it.
>> +
>> +Stateless mode MAC service requests are as follows:
>> +
>> +\begin{lstlisting}
>> +struct virtio_crypto_mac_data_flf_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_vlf_stateless {
>> + /* Device read only portion */
>> + /* The authenticated key */
>> + u8 auth_key[auth_key_len];
>> + /* Source data */
>> + u8 src_data[src_data_len];
>> +
>> + /* Device write only portion */
>> + /* Hash result data */
>> + u8 hash_result[hash_result_len];
>> +};
>> +\end{lstlisting}
>> +
>> +\field{auth_key} is the authenticated key that will be used during the process.
>> +\field{auth_key_len} is the length of the key.
>> +
>> +\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_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 ZERO and MUST set the fields in struct
>> + virtio_crypto_mac_data_flf_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_SESSION_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_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
>> + following values of enum VIRTIO_CRYPTO_STATUS:
>> +\begin{itemize*}
>> +\item VIRTIO_CRYPTO_OK if the operation success.
>> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
>> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.
>> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
>> +\end{itemize*}
>> +\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_data_flf {
>> + /*
>> + * 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_vlf {
>> + /* Device read only portion */
>> +
>> + /*
>> + * 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 write only portion */
>> + /* Destination data */
>> + u8 dst_data[dst_data_len];
>
>
> I'm a bit puzzled about dst_data_len. I'm by no means a crypto expert,
> and that is probably the very reason of my discomfort.
>
> I've tried to figure out how dst_data_len is used and expected to find
> a place that checks, that at least a sufficiently large buffer was provided.
>
> I've also assumed that the src_data_len is likely to imply the dst_data_len
> for any given algorithm. Furthermore, I even hypothesised that the both
> lengths are the same. All based on what I remember about block ciphers.
>
> If that hypothesis is right, then I don't understand why do we need
> both src_data_len and dst_data_len.
>
> Since dst_data_len is device read only, the driver I figure the driver
> needs to know the exact length (since I cant figure out, based on this
> spec, how is it supposed to be told by the device which part of the
> buffer is the result and which part garbage). So the only sane usage
> I was able to come up with is to avoid the device overwritting other
> parts of the requests device writtable part because of a driver
> bug (wrong dst_data_len). But as I've said I could not find the corresponding
> code in qemu.
>
I'm sorry that I'm not a crypto expert too :(
For hash, hmac and aead serivce, there is no doubt that 'dst_len' can be
difference with the 'src_len'. Only the sym cipher serivice we cannot sure.
But I think we'd better not hypothesis they are the same, I found the Intel QAT
driver also use 'src_len' and 'dst_len' for SYM service:
'''
CpaPhysicalAddr srcBuffer;
/**< Physical address of the source buffer on which to operate.
* This is either:
*
* - The location of the data, of length srcBufferLen; or,
* - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then
* srcBuffer contains the location where a @ref CpaPhysBufferList is
* stored. In this case, the CpaPhysBufferList MUST be aligned
* on an 8-byte boundary.
* - For optimum performance, the buffer should only contain the data
* region that the cryptographic operation(s) must be performed on.
* Any additional data in the source buffer may be copied to the
* destination buffer and this copy may degrade performance.
*/
Cpa32U srcBufferLen;
/**< Length of source buffer, or @ref CPA_DP_BUFLIST. */
CpaPhysicalAddr dstBuffer;
/**< Physical address of the destination buffer on which to operate.
* This is either:
*
* - The location of the data, of length srcBufferLen; or,
* - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then
* srcBuffer contains the location where a @ref CpaPhysBufferList is
* stored. In this case, the CpaPhysBufferList MUST be aligned
* on an 8-byte boundary.
*
* For "in-place" operation, the dstBuffer may be identical to the
* srcBuffer.
*/
Cpa32U dstBufferLen;
/**< Length of destination buffer, or @ref CPA_DP_BUFLIST. */
'''
and
'''
/* Check that src buffer Len = dst buffer Len
Note this also checks that they are of the same type */
if (pRequest->srcBufferLen != pRequest->dstBufferLen)
{
LAC_INVALID_PARAM_LOG(
"Source and Destination buffer lengths need to be equal");
return CPA_STATUS_INVALID_PARAM;
}
'''
The qemu code should check if 'src_len' and 'dst_len' is the same.
> Anyway providing some more background for the guys only superficially
> involved with crypto (like me) would be appreciated.
>
> I will stop here for now. I read the rest real quick and I did not
> see anything major. I think we are slowly getting there.
>
> Regards,
> Halil
>
>
> .
>
--
Regards,
Longpeng(Mike)
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-07-20 12:01 ` [virtio-dev] " Longpeng (Mike)
@ 2018-07-26 16:55 ` Halil Pasic
-1 siblings, 0 replies; 31+ messages in thread
From: Halil Pasic @ 2018-07-26 16:55 UTC (permalink / raw)
To: Longpeng (Mike), Halil Pasic
Cc: virtio-dev, Ola.Liljedahl, brian.a.keating, wangxinxin.wang, mst,
liang.j.ma, jasowang, xin.zeng, qemu-devel, john.griffin, agraf,
arei.gonglei, stefanha, jianjay.zhou, cornelia.huck, Varun.Sethi,
Jani.Kokkonen, vincent.jardin, denglingli, weidong.huang
Sorry I did not have any time for this last days. And this
to make it worse this is a follow up to something that was
half a year ago. That means I have to re-familiarize myself
with the topic.
If I don't get around to answer in couple of weeks, feel
free to ping me.
Since from what I've seen most of the questions were of type
'Can we do it like this?', maybe sending out a new version
is the best. So people (like me) can read through the whole
thing and point out problems if any.
Regards,
Halil
On 07/20/2018 02:01 PM, Longpeng (Mike) wrote:
>
>
> On 2018/1/10 1:05, Halil Pasic wrote:
>
>>
>>
>> On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
>>> From: Gonglei <arei.gonglei@huawei.com>
^ permalink raw reply [flat|nested] 31+ messages in thread
* [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-07-26 16:55 ` Halil Pasic
0 siblings, 0 replies; 31+ messages in thread
From: Halil Pasic @ 2018-07-26 16:55 UTC (permalink / raw)
To: Longpeng (Mike), Halil Pasic
Cc: virtio-dev, Ola.Liljedahl, brian.a.keating, wangxinxin.wang, mst,
liang.j.ma, jasowang, xin.zeng, qemu-devel, john.griffin, agraf,
arei.gonglei, stefanha, jianjay.zhou, cornelia.huck, Varun.Sethi,
Jani.Kokkonen, vincent.jardin, denglingli, weidong.huang
Sorry I did not have any time for this last days. And this
to make it worse this is a follow up to something that was
half a year ago. That means I have to re-familiarize myself
with the topic.
If I don't get around to answer in couple of weeks, feel
free to ping me.
Since from what I've seen most of the questions were of type
'Can we do it like this?', maybe sending out a new version
is the best. So people (like me) can read through the whole
thing and point out problems if any.
Regards,
Halil
On 07/20/2018 02:01 PM, Longpeng (Mike) wrote:
>
>
> On 2018/1/10 1:05, Halil Pasic wrote:
>
>>
>>
>> On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
>>> From: Gonglei <arei.gonglei@huawei.com>
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-07-26 16:55 ` [virtio-dev] " Halil Pasic
@ 2018-07-27 0:59 ` Longpeng (Mike)
-1 siblings, 0 replies; 31+ messages in thread
From: Longpeng (Mike) @ 2018-07-27 0:59 UTC (permalink / raw)
To: Halil Pasic
Cc: Halil Pasic, virtio-dev, Ola.Liljedahl, brian.a.keating,
wangxinxin.wang, mst, liang.j.ma, jasowang, xin.zeng, qemu-devel,
john.griffin, agraf, arei.gonglei, stefanha, jianjay.zhou,
cornelia.huck, Varun.Sethi, Jani.Kokkonen, vincent.jardin,
denglingli, weidong.huang
On 2018/7/27 0:55, Halil Pasic wrote:
> Sorry I did not have any time for this last days. And this
> to make it worse this is a follow up to something that was
> half a year ago. That means I have to re-familiarize myself
> with the topic.
>
> If I don't get around to answer in couple of weeks, feel
> free to ping me.
>
> Since from what I've seen most of the questions were of type
> 'Can we do it like this?', maybe sending out a new version
> is the best. So people (like me) can read through the whole
> thing and point out problems if any.
>
Hi Halil,
I'll send v24, thanks :)
> Regards,
> Halil
>
> On 07/20/2018 02:01 PM, Longpeng (Mike) wrote:
>>
>>
>> On 2018/1/10 1:05, Halil Pasic wrote:
>>
>>>
>>>
>>> On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
>>>> From: Gonglei <arei.gonglei@huawei.com>
>
>
> .
>
--
Regards,
Longpeng(Mike)
^ permalink raw reply [flat|nested] 31+ messages in thread
* [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-07-27 0:59 ` Longpeng (Mike)
0 siblings, 0 replies; 31+ messages in thread
From: Longpeng (Mike) @ 2018-07-27 0:59 UTC (permalink / raw)
To: Halil Pasic
Cc: Halil Pasic, virtio-dev, Ola.Liljedahl, brian.a.keating,
wangxinxin.wang, mst, liang.j.ma, jasowang, xin.zeng, qemu-devel,
john.griffin, agraf, arei.gonglei, stefanha, jianjay.zhou,
cornelia.huck, Varun.Sethi, Jani.Kokkonen, vincent.jardin,
denglingli, weidong.huang
On 2018/7/27 0:55, Halil Pasic wrote:
> Sorry I did not have any time for this last days. And this
> to make it worse this is a follow up to something that was
> half a year ago. That means I have to re-familiarize myself
> with the topic.
>
> If I don't get around to answer in couple of weeks, feel
> free to ping me.
>
> Since from what I've seen most of the questions were of type
> 'Can we do it like this?', maybe sending out a new version
> is the best. So people (like me) can read through the whole
> thing and point out problems if any.
>
Hi Halil,
I'll send v24, thanks :)
> Regards,
> Halil
>
> On 07/20/2018 02:01 PM, Longpeng (Mike) wrote:
>>
>>
>> On 2018/1/10 1:05, Halil Pasic wrote:
>>
>>>
>>>
>>> On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
>>>> From: Gonglei <arei.gonglei@huawei.com>
>
>
> .
>
--
Regards,
Longpeng(Mike)
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [virtio-dev] Re: [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-07-26 16:55 ` [virtio-dev] " Halil Pasic
@ 2018-07-27 11:51 ` Michael S. Tsirkin
-1 siblings, 0 replies; 31+ messages in thread
From: Michael S. Tsirkin @ 2018-07-27 11:51 UTC (permalink / raw)
To: Halil Pasic
Cc: Longpeng (Mike),
Halil Pasic, virtio-dev, Ola.Liljedahl, brian.a.keating,
wangxinxin.wang, liang.j.ma, jasowang, xin.zeng, qemu-devel,
john.griffin, agraf, arei.gonglei, stefanha, jianjay.zhou,
cornelia.huck, Varun.Sethi, Jani.Kokkonen, vincent.jardin,
denglingli, weidong.huang
On Thu, Jul 26, 2018 at 06:55:44PM +0200, Halil Pasic wrote:
> Sorry I did not have any time for this last days. And this
> to make it worse this is a follow up to something that was
> half a year ago. That means I have to re-familiarize myself
> with the topic.
>
> If I don't get around to answer in couple of weeks, feel
> free to ping me.
>
> Since from what I've seen most of the questions were of type
> 'Can we do it like this?', maybe sending out a new version
> is the best. So people (like me) can read through the whole
> thing and point out problems if any.
>
> Regards,
> Halil
While two weeks for review is borderline reasonable as an exception, it
does trouble me that we are at v23, for something that is used
in the field so it's not like we can just change things at will.
So I hope everyone concerned makes an effort to try to converge on a spec
ASAP.
> On 07/20/2018 02:01 PM, Longpeng (Mike) wrote:
> >
> >
> > On 2018/1/10 1:05, Halil Pasic wrote:
> >
> > >
> > >
> > > On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
> > > > From: Gonglei <arei.gonglei@huawei.com>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [virtio-dev] Re: [Qemu-devel] [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-07-27 11:51 ` Michael S. Tsirkin
0 siblings, 0 replies; 31+ messages in thread
From: Michael S. Tsirkin @ 2018-07-27 11:51 UTC (permalink / raw)
To: Halil Pasic
Cc: Longpeng (Mike),
Halil Pasic, virtio-dev, Ola.Liljedahl, brian.a.keating,
wangxinxin.wang, liang.j.ma, jasowang, xin.zeng, qemu-devel,
john.griffin, agraf, arei.gonglei, stefanha, jianjay.zhou,
cornelia.huck, Varun.Sethi, Jani.Kokkonen, vincent.jardin,
denglingli, weidong.huang
On Thu, Jul 26, 2018 at 06:55:44PM +0200, Halil Pasic wrote:
> Sorry I did not have any time for this last days. And this
> to make it worse this is a follow up to something that was
> half a year ago. That means I have to re-familiarize myself
> with the topic.
>
> If I don't get around to answer in couple of weeks, feel
> free to ping me.
>
> Since from what I've seen most of the questions were of type
> 'Can we do it like this?', maybe sending out a new version
> is the best. So people (like me) can read through the whole
> thing and point out problems if any.
>
> Regards,
> Halil
While two weeks for review is borderline reasonable as an exception, it
does trouble me that we are at v23, for something that is used
in the field so it's not like we can just change things at will.
So I hope everyone concerned makes an effort to try to converge on a spec
ASAP.
> On 07/20/2018 02:01 PM, Longpeng (Mike) wrote:
> >
> >
> > On 2018/1/10 1:05, Halil Pasic wrote:
> >
> > >
> > >
> > > On 12/30/2017 10:35 AM, Longpeng(Mike) wrote:
> > > > From: Gonglei <arei.gonglei@huawei.com>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [virtio-dev] Re: [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-07-27 11:51 ` [virtio-dev] Re: [Qemu-devel] " Michael S. Tsirkin
@ 2018-08-01 20:21 ` Halil Pasic
-1 siblings, 0 replies; 31+ messages in thread
From: Halil Pasic @ 2018-08-01 20:21 UTC (permalink / raw)
To: Michael S. Tsirkin
Cc: denglingli, virtio-dev, Halil Pasic, Ola.Liljedahl,
brian.a.keating, Jani.Kokkonen, xin.zeng, wangxinxin.wang,
liang.j.ma, qemu-devel, john.griffin, agraf, arei.gonglei,
stefanha, jianjay.zhou, cornelia.huck, Varun.Sethi,
Longpeng (Mike),
vincent.jardin, jasowang, weidong.huang
On 07/27/2018 01:51 PM, Michael S. Tsirkin wrote:
> On Thu, Jul 26, 2018 at 06:55:44PM +0200, Halil Pasic wrote:
>> Sorry I did not have any time for this last days. And this
>> to make it worse this is a follow up to something that was
>> half a year ago. That means I have to re-familiarize myself
>> with the topic.
>>
>> If I don't get around to answer in couple of weeks, feel
>> free to ping me.
>>
>> Since from what I've seen most of the questions were of type
>> 'Can we do it like this?', maybe sending out a new version
>> is the best. So people (like me) can read through the whole
>> thing and point out problems if any.
>>
>> Regards,
>> Halil
>
>
> While two weeks for review is borderline reasonable as an exception, it
> does trouble me that we are at v23, for something that is used
> in the field so it's not like we can just change things at will.
> So I hope everyone concerned makes an effort to try to converge on a spec
> ASAP.
>
What I tried to say: I'm busy with other stuff, and I'm not too
happy to resume a complex topic after 6 months hiatus.
The series is now at v24 and has apparently no acks or r-bs. I don't think
I'm the only one to blame for that.
It seems, I won't have the time to do a conscientious review in a
timely fashion. If the rest of the bunch thinks what we have is good
enough, I am happy to abstain when voting on this -- and avoiding
holding it up any further.
Regards,
Halil
^ permalink raw reply [flat|nested] 31+ messages in thread
* [virtio-dev] Re: [Qemu-devel] [virtio-dev] Re: [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-08-01 20:21 ` Halil Pasic
0 siblings, 0 replies; 31+ messages in thread
From: Halil Pasic @ 2018-08-01 20:21 UTC (permalink / raw)
To: Michael S. Tsirkin
Cc: denglingli, virtio-dev, Halil Pasic, Ola.Liljedahl,
brian.a.keating, Jani.Kokkonen, xin.zeng, wangxinxin.wang,
liang.j.ma, qemu-devel, john.griffin, agraf, arei.gonglei,
stefanha, jianjay.zhou, cornelia.huck, Varun.Sethi,
Longpeng (Mike),
vincent.jardin, jasowang, weidong.huang
On 07/27/2018 01:51 PM, Michael S. Tsirkin wrote:
> On Thu, Jul 26, 2018 at 06:55:44PM +0200, Halil Pasic wrote:
>> Sorry I did not have any time for this last days. And this
>> to make it worse this is a follow up to something that was
>> half a year ago. That means I have to re-familiarize myself
>> with the topic.
>>
>> If I don't get around to answer in couple of weeks, feel
>> free to ping me.
>>
>> Since from what I've seen most of the questions were of type
>> 'Can we do it like this?', maybe sending out a new version
>> is the best. So people (like me) can read through the whole
>> thing and point out problems if any.
>>
>> Regards,
>> Halil
>
>
> While two weeks for review is borderline reasonable as an exception, it
> does trouble me that we are at v23, for something that is used
> in the field so it's not like we can just change things at will.
> So I hope everyone concerned makes an effort to try to converge on a spec
> ASAP.
>
What I tried to say: I'm busy with other stuff, and I'm not too
happy to resume a complex topic after 6 months hiatus.
The series is now at v24 and has apparently no acks or r-bs. I don't think
I'm the only one to blame for that.
It seems, I won't have the time to do a conscientious review in a
timely fashion. If the rest of the bunch thinks what we have is good
enough, I am happy to abstain when voting on this -- and avoiding
holding it up any further.
Regards,
Halil
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [Qemu-devel] [virtio-dev] Re: [v23 1/2] virtio-crypto: Add virtio crypto device specification
2018-08-01 20:21 ` [virtio-dev] " Halil Pasic
@ 2018-08-02 1:56 ` Longpeng (Mike)
-1 siblings, 0 replies; 31+ messages in thread
From: Longpeng (Mike) @ 2018-08-02 1:56 UTC (permalink / raw)
To: Halil Pasic, Michael S. Tsirkin, arei.gonglei, stefanha
Cc: denglingli, virtio-dev, Halil Pasic, Ola.Liljedahl,
brian.a.keating, Jani.Kokkonen, xin.zeng, wangxinxin.wang,
liang.j.ma, qemu-devel, john.griffin, agraf, jianjay.zhou,
cornelia.huck, Varun.Sethi, vincent.jardin, jasowang,
weidong.huang
Hi Halil,
On 2018/8/2 4:21, Halil Pasic wrote:
>
>
> On 07/27/2018 01:51 PM, Michael S. Tsirkin wrote:
>> On Thu, Jul 26, 2018 at 06:55:44PM +0200, Halil Pasic wrote:
>>> Sorry I did not have any time for this last days. And this
>>> to make it worse this is a follow up to something that was
>>> half a year ago. That means I have to re-familiarize myself
>>> with the topic.
>>>
>>> If I don't get around to answer in couple of weeks, feel
>>> free to ping me.
>>>
>>> Since from what I've seen most of the questions were of type
>>> 'Can we do it like this?', maybe sending out a new version
>>> is the best. So people (like me) can read through the whole
>>> thing and point out problems if any.
>>>
>>> Regards,
>>> Halil
>>
>>
>> While two weeks for review is borderline reasonable as an exception, it
>> does trouble me that we are at v23, for something that is used
>> in the field so it's not like we can just change things at will.
>> So I hope everyone concerned makes an effort to try to converge on a spec
>> ASAP.
>>
>
> What I tried to say: I'm busy with other stuff, and I'm not too
> happy to resume a complex topic after 6 months hiatus.
>
> The series is now at v24 and has apparently no acks or r-bs. I don't think
> I'm the only one to blame for that.
>
> It seems, I won't have the time to do a conscientious review in a
> timely fashion. If the rest of the bunch thinks what we have is good
> enough, I am happy to abstain when voting on this -- and avoiding
> holding it up any further.
>
Thanks for your conscientious reviews on previous versions and your suggestions
are really useful to make the spec better. I'm sorry that I should be to blame
for the half a year hiatus, not you.
I've do some offline discussions with Gonglei and Intel guys, it seems that
there is no big arguments on v23 and the following small problems can be fixed
by follow-up patches.
I hope guys who care about this spec could post your opinion, I'll suggest
Gonglei to start a vote for the spec if no.
> Regards,
> Halil
>
>
> .
>
--
Regards,
Longpeng(Mike)
^ permalink raw reply [flat|nested] 31+ messages in thread
* [virtio-dev] Re: [Qemu-devel] [virtio-dev] Re: [v23 1/2] virtio-crypto: Add virtio crypto device specification
@ 2018-08-02 1:56 ` Longpeng (Mike)
0 siblings, 0 replies; 31+ messages in thread
From: Longpeng (Mike) @ 2018-08-02 1:56 UTC (permalink / raw)
To: Halil Pasic, Michael S. Tsirkin, arei.gonglei, stefanha
Cc: denglingli, virtio-dev, Halil Pasic, Ola.Liljedahl,
brian.a.keating, Jani.Kokkonen, xin.zeng, wangxinxin.wang,
liang.j.ma, qemu-devel, john.griffin, agraf, jianjay.zhou,
cornelia.huck, Varun.Sethi, vincent.jardin, jasowang,
weidong.huang
Hi Halil,
On 2018/8/2 4:21, Halil Pasic wrote:
>
>
> On 07/27/2018 01:51 PM, Michael S. Tsirkin wrote:
>> On Thu, Jul 26, 2018 at 06:55:44PM +0200, Halil Pasic wrote:
>>> Sorry I did not have any time for this last days. And this
>>> to make it worse this is a follow up to something that was
>>> half a year ago. That means I have to re-familiarize myself
>>> with the topic.
>>>
>>> If I don't get around to answer in couple of weeks, feel
>>> free to ping me.
>>>
>>> Since from what I've seen most of the questions were of type
>>> 'Can we do it like this?', maybe sending out a new version
>>> is the best. So people (like me) can read through the whole
>>> thing and point out problems if any.
>>>
>>> Regards,
>>> Halil
>>
>>
>> While two weeks for review is borderline reasonable as an exception, it
>> does trouble me that we are at v23, for something that is used
>> in the field so it's not like we can just change things at will.
>> So I hope everyone concerned makes an effort to try to converge on a spec
>> ASAP.
>>
>
> What I tried to say: I'm busy with other stuff, and I'm not too
> happy to resume a complex topic after 6 months hiatus.
>
> The series is now at v24 and has apparently no acks or r-bs. I don't think
> I'm the only one to blame for that.
>
> It seems, I won't have the time to do a conscientious review in a
> timely fashion. If the rest of the bunch thinks what we have is good
> enough, I am happy to abstain when voting on this -- and avoiding
> holding it up any further.
>
Thanks for your conscientious reviews on previous versions and your suggestions
are really useful to make the spec better. I'm sorry that I should be to blame
for the half a year hiatus, not you.
I've do some offline discussions with Gonglei and Intel guys, it seems that
there is no big arguments on v23 and the following small problems can be fixed
by follow-up patches.
I hope guys who care about this spec could post your opinion, I'll suggest
Gonglei to start a vote for the spec if no.
> Regards,
> Halil
>
>
> .
>
--
Regards,
Longpeng(Mike)
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 31+ messages in thread
end of thread, other threads:[~2018-08-02 1:57 UTC | newest]
Thread overview: 31+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-12-30 9:35 [Qemu-devel] [v23 0/2] virtio-crypto: virtio crypto device specification Longpeng(Mike)
2017-12-30 9:35 ` [Qemu-devel] [v23 1/2] virtio-crypto: Add " Longpeng(Mike)
2018-01-09 17:05 ` Halil Pasic
2018-01-09 17:05 ` [virtio-dev] " Halil Pasic
2018-01-09 17:41 ` Michael S. Tsirkin
2018-01-09 17:41 ` [virtio-dev] " Michael S. Tsirkin
2018-01-10 5:53 ` Longpeng (Mike)
2018-01-10 5:53 ` [virtio-dev] " Longpeng (Mike)
2018-06-20 3:34 ` [Qemu-devel] [virtio-dev] " Michael S. Tsirkin
2018-06-20 3:34 ` [virtio-dev] Re: [Qemu-devel] " Michael S. Tsirkin
2018-06-20 6:15 ` [Qemu-devel] [virtio-dev] " Longpeng (Mike)
2018-03-16 16:27 ` Michael S. Tsirkin
2018-03-16 16:27 ` [virtio-dev] Re: [Qemu-devel] " Michael S. Tsirkin
2018-03-16 18:18 ` [Qemu-devel] [virtio-dev] " Halil Pasic
2018-03-16 18:18 ` [virtio-dev] Re: [Qemu-devel] " Halil Pasic
2018-03-19 0:13 ` [Qemu-devel] [virtio-dev] " Michael S. Tsirkin
2018-03-19 0:13 ` [virtio-dev] Re: [Qemu-devel] " Michael S. Tsirkin
2018-07-20 12:01 ` Longpeng (Mike)
2018-07-20 12:01 ` [virtio-dev] " Longpeng (Mike)
2018-07-26 16:55 ` Halil Pasic
2018-07-26 16:55 ` [virtio-dev] " Halil Pasic
2018-07-27 0:59 ` Longpeng (Mike)
2018-07-27 0:59 ` [virtio-dev] " Longpeng (Mike)
2018-07-27 11:51 ` [Qemu-devel] [virtio-dev] " Michael S. Tsirkin
2018-07-27 11:51 ` [virtio-dev] Re: [Qemu-devel] " Michael S. Tsirkin
2018-08-01 20:21 ` [Qemu-devel] [virtio-dev] " Halil Pasic
2018-08-01 20:21 ` [virtio-dev] " Halil Pasic
2018-08-02 1:56 ` Longpeng (Mike)
2018-08-02 1:56 ` [virtio-dev] " Longpeng (Mike)
2017-12-30 9:35 ` [Qemu-devel] [v23 2/2] virtio-crypto: Add conformance clauses Longpeng(Mike)
2017-12-30 9:35 ` [virtio-dev] " Longpeng(Mike)
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.