From patchwork Wed Sep 28 09:08:24 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Gonglei (Arei)" X-Patchwork-Id: 9353593 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id A83D360756 for ; Wed, 28 Sep 2016 09:28:58 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 951992938A for ; Wed, 28 Sep 2016 09:28:58 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 88A9E29447; Wed, 28 Sep 2016 09:28:58 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 63D152938A for ; Wed, 28 Sep 2016 09:28:55 +0000 (UTC) Received: from localhost ([::1]:57158 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bpBAb-0006JW-V1 for patchwork-qemu-devel@patchwork.kernel.org; Wed, 28 Sep 2016 05:28:54 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:51262) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bpAyB-0001t6-3e for qemu-devel@nongnu.org; Wed, 28 Sep 2016 05:16:08 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bpAy4-0004RY-WB for qemu-devel@nongnu.org; Wed, 28 Sep 2016 05:16:02 -0400 Received: from szxga01-in.huawei.com ([58.251.152.64]:45824) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bpAy1-0004ON-0j for qemu-devel@nongnu.org; Wed, 28 Sep 2016 05:15:56 -0400 Received: from 172.24.1.60 (EHLO szxeml425-hub.china.huawei.com) ([172.24.1.60]) by szxrg01-dlp.huawei.com (MOS 4.3.7-GA FastPath queued) with ESMTP id DRR33553; Wed, 28 Sep 2016 17:08:40 +0800 (CST) Received: from localhost (10.177.18.62) by szxeml425-hub.china.huawei.com (10.82.67.180) with Microsoft SMTP Server id 14.3.235.1; Wed, 28 Sep 2016 17:08:31 +0800 From: Gonglei To: , Date: Wed, 28 Sep 2016 17:08:24 +0800 Message-ID: <1475053705-400172-2-git-send-email-arei.gonglei@huawei.com> X-Mailer: git-send-email 2.6.3.windows.1 In-Reply-To: <1475053705-400172-1-git-send-email-arei.gonglei@huawei.com> References: <1475053705-400172-1-git-send-email-arei.gonglei@huawei.com> MIME-Version: 1.0 X-Originating-IP: [10.177.18.62] X-CFilter-Loop: Reflected X-Mirapoint-Virus-RAPID-Raw: score=unknown(0), refid=str=0001.0A010202.57EB889C.0061, ss=1, re=0.000, recu=0.000, reip=0.000, cl=1, cld=1, fgs=0, ip=0.0.0.0, so=2013-06-18 04:22:30, dmn=2013-03-21 17:37:32 X-Mirapoint-Loop-Id: e2de54b6171ab507a27f07ca02eca518 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 58.251.152.64 Subject: [Qemu-devel] [PATCH v11 1/2] virtio-crypto: Add virtio crypto device specification X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: weidong.huang@huawei.com, mst@redhat.com, john.griffin@intel.com, Shiqing.Fan@huawei.com, jianjay.zhou@huawei.com, Varun.Sethi@freescale.com, denglingli@chinamobile.com, hanweidong@huawei.com, agraf@suse.de, Gonglei , nmorey@kalray.eu, vincent.jardin@6wind.com, Ola.Liljedahl@arm.com, luonengjun@huawei.com, xin.zeng@intel.com, peter.huangpeng@huawei.com, liang.j.ma@intel.com, stefanha@redhat.com, cornelia.huck@de.ibm.com, Jani.Kokkonen@huawei.com, brian.a.keating@intel.com, claudio.fontana@huawei.com, mike.caraman@nxp.com, wu.wubin@huawei.com Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP 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 CC: Michael S. Tsirkin CC: Cornelia Huck CC: Stefan Hajnoczi CC: Lingli Deng CC: Jani Kokkonen CC: Ola Liljedahl CC: Varun Sethi CC: Zeng Xin CC: Keating Brian CC: Ma Liang J CC: Griffin John CC: Hanweidong CC: Mihai Claudiu Caraman --- content.tex | 2 + virtio-crypto.tex | 1034 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1036 insertions(+) create mode 100644 virtio-crypto.tex diff --git a/content.tex b/content.tex index 4b45678..ab75f78 100644 --- a/content.tex +++ b/content.tex @@ -5750,6 +5750,8 @@ descriptor for the \field{sense_len}, \field{residual}, \field{status_qualifier}, \field{status}, \field{response} and \field{sense} fields. +\input{virtio-crypto.tex} + \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} Currently there are three device-independent feature bits defined: diff --git a/virtio-crypto.tex b/virtio-crypto.tex new file mode 100644 index 0000000..9aa24f6 --- /dev/null +++ b/virtio-crypto.tex @@ -0,0 +1,1034 @@ +\section{Crypto Device}\label{sec:Device Types / Crypto Device} + +The virtio crypto device is a virtual cryptography device as well as a kind of +virtual hardware accelerator for virtual machines. The encryption and +decryption requests are placed in the data queue and are ultimately handled by the +backend crypto accelerators. The second queue is the control queue used to create +or destroy sessions for symmetric algorithms and will control some advanced +features in the future. The virtio crypto device provides the following crypto +services: CIPHER, MAC, HASH, and AEAD. + + +\subsection{Device ID}\label{sec:Device Types / Crypto Device / Device ID} + +20 + +\subsection{Virtqueues}\label{sec:Device Types / Crypto Device / Virtqueues} + +\begin{description} +\item[0] dataq1 +\item[\ldots] +\item[N-1] dataqN +\item[N] controlq +\end{description} + +N is set by \field{max_dataqueues}. + +\subsection{Feature bits}\label{sec:Device Types / Crypto Device / Feature bits} + +Undefined currently. + +\subsection{Device configuration layout}\label{sec:Device Types / Crypto Device / Device configuration layout} + +The following driver-read-only configuration fields are defined: + +\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; + le32 reserve; +}; +\end{lstlisting} + +The value of the \field{status} field is VIRTIO_CRYPTO_S_HW_READY or VIRTIO_CRYPTO_S_STARTED. + +\begin{lstlisting} +#define VIRTIO_CRYPTO_S_HW_READY (1 << 0) +#define VIRTIO_CRYPTO_S_STARTED (1 << 1) +\end{lstlisting} + +The following driver-read-only fields include \field{max_dataqueues}, which specifies the +maximum number of data virtqueues (dataq1\ldots dataqN), and \field{crypto_services}, +which indicates the crypto services the virtio crypto supports. + +The following 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 last driver-read-only fields specify detailed algorithms masks +the device offers for corresponding 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 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 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 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} + +\begin{note} +Any other value is reserved for future use. +\end{note} + +\devicenormative{\subsubsection}{Device configuration layout}{Device Types / Crypto Device / Device configuration layout} + +\begin{itemize*} +\item The device MUST set \field{max_dataqueues} to between 1 and 65535 inclusive. +\item The device MUST set \field{status} based on the status of the hardware-backed implementation. +\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 offer. +\item The device MUST set detailed algorithms masks based on the \field{crypto_services} field. +\end{itemize*} + +\drivernormative{\subsubsection}{Device configuration layout}{Device Types / Crypto Device / Device configuration layout} + +\begin{itemize*} +\item The driver MUST read the ready \field{status} from the bottom bit of status to check whether the hardware-backed + implementation is ready or not, and the driver MUST reread it after the device reset. +\item The driver MUST NOT transmit any packets to the device if the ready \field{status} is not set. +\item The driver MAY read \field{max_dataqueues} field to discover the number of data queues the device supports. +\item The driver MUST read \field{crypto_services} field to discover which services the device is able to offer. +\item The driver MUST read the detailed algorithms fields based on \field{crypto_services} field. +\end{itemize*} + +\subsection{Device Initialization}\label{sec:Device Types / Crypto Device / Device Initialization} + +\drivernormative{\subsubsection}{Device Initialization}{Device Types / Crypto Device / Device Initialization} + +\begin{itemize*} +\item The driver MUST identify and initialize the control virtqueue. +\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*} + +\devicenormative{\subsubsection}{Device Initialization}{Device Types / Crypto Device / Device Initialization} + +\begin{itemize*} +\item The device MUST be configured with at least one accelerator which executes backend crypto operations. +\item The device MUST write the \field{crypto_services} field based on the capacities of the backend accelerator. +\end{itemize*} + +\subsection{Device Operation}\label{sec:Device Types / Crypto Device / Device Operation} + +Packets can be transmitted by placing them in both the controlq and dataq. +Packets consist of a general header and a service-specific request. +Where 'general header' is for all crypto requests, and 'service specific requests' +are composed of operation parameter + output data + input data in general. +Operation parameters are algorithm-specific parameters, output data is the +data that should be utilized in operations, and input data is equal to +"operation result + result buffer". + +The general header for controlq is as follows: + +\begin{lstlisting} +#define VIRTIO_CRYPTO_OPCODE(service, op) ((service << 8) | (op)) + +struct virtio_crypto_ctrl_header { +#define VIRTIO_CRYPTO_CIPHER_CREATE_SESSION \ + VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_CIPHER, 0x02) +#define VIRTIO_CRYPTO_CIPHER_DESTROY_SESSION \ + VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_CIPHER, 0x03) +#define VIRTIO_CRYPTO_HASH_CREATE_SESSION \ + VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_HASH, 0x02) +#define VIRTIO_CRYPTO_HASH_DESTROY_SESSION \ + VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_HASH, 0x03) +#define VIRTIO_CRYPTO_MAC_CREATE_SESSION \ + VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_MAC, 0x02) +#define VIRTIO_CRYPTO_MAC_DESTROY_SESSION \ + VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_MAC, 0x03) +#define VIRTIO_CRYPTO_AEAD_CREATE_SESSION \ + VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_AEAD, 0x02) +#define VIRTIO_CRYPTO_AEAD_DESTROY_SESSION \ + VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_AEAD, 0x03) + le32 opcode; + le32 algo; + le32 flag; + /* data virtqueue id */ + le32 queue_id; +}; +\end{lstlisting} + +The general header of dataq: + +\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; + /* session_id should be service-specific algorithms */ + le64 session_id; + /* control flag to control the request */ + le32 flag; + le32 padding; +}; +\end{lstlisting} + +The device can set the operation status as follows: VIRTIO_CRYPTO_OK: success; +VIRTIO_CRYPTO_ERR: failure or device error; VIRTIO_CRYPTO_NOTSUPP: not supported; +VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto operations. + +\begin{lstlisting} +#define VIRTIO_CRYPTO_OK 0 +#define VIRTIO_CRYPTO_ERR 1 +#define VIRTIO_CRYPTO_BADMSG 2 +#define VIRTIO_CRYPTO_NOTSUPP 3 +#define VIRTIO_CRYPTO_INVSESS 4 +\end{lstlisting} + +\subsubsection{Control Virtqueue}\label{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue} + +The driver uses the control virtqueue to send control commands to the +device which handles the non-data plane operations, such as session +operations (See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation}). + +The packet of controlq: + +\begin{lstlisting} +struct virtio_crypto_op_ctrl_req { + struct virtio_crypto_ctrl_header header; + + union { + struct virtio_crypto_sym_create_session_req sym_create_session; + struct virtio_crypto_hash_create_session_req hash_create_session; + struct virtio_crypto_mac_create_session_req mac_create_session; + struct virtio_crypto_aead_create_session_req aead_create_session; + struct virtio_crypto_destroy_session_req destroy_session; + } u; +}; +\end{lstlisting} + +The header is the general header, and the union is of the algorithm-specific type, +which is set by the driver. All the properties in the union are shown as follows. + +\paragraph{Session operation}\label{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation} + +The symmetric algorithms involve the concept of sessions. A session is a +handle which describes the cryptographic parameters to be applied to +a number of buffers. The data within a session handle includes the following: + +\begin{enumerate} +\item The operation (CIPHER, HASH/MAC or both, and if both, the order in + which the algorithms should be applied). +\item The CIPHER set data, including the CIPHER algorithm and mode, + the key and its length, and the direction (encrypt or decrypt). +\item The HASH/MAC set data, including the HASH algorithm or MAC algorithm, + and digest result length (to allow for truncation). +\begin{itemize*} +\item Authenticated mode can refer to MAC, which requires that the key and + its length are also specified. +\item For nested mode, the inner and outer prefix data and length are specified, + as well as the outer HASH algorithm. +\end{itemize*} +\end{enumerate} + +The following structure stores the result of session creation set by the device: + +\begin{lstlisting} +struct virtio_crypto_session_input { + /* Device-writable part */ + le64 session_id; + le32 status; + le32 padding; +}; +\end{lstlisting} + +A request to destroy a session includes the following information: + +\begin{lstlisting} +struct virtio_crypto_destroy_session_req { + /* Device-readable part */ + le64 session_id; + /* Device-writable part */ + le32 status; + le32 padding; +}; +\end{lstlisting} + +\subparagraph{Session operation: HASH session}\label{sec:Device Types / Crypto Device / Device +Operation / Control Virtqueue / Session operation / Session operation: HASH session} + +The packet of HASH session is as follows: + +\begin{lstlisting} +struct virtio_crypto_hash_session_para { + /* See VIRTIO_CRYPTO_HASH_* above */ + le32 algo; + /* hash result length */ + le32 hash_result_len; +}; +struct virtio_crypto_hash_create_session_req { + /* Device-readable part */ + struct virtio_crypto_hash_session_para para; + /* Device-writable part */ + struct virtio_crypto_session_input input; +}; +\end{lstlisting} + +\subparagraph{Session operation: MAC session}\label{sec:Device Types / Crypto Device / Device +Operation / Control Virtqueue / Session operation / Session operation: MAC session} + +The packet of MAC session is as follows: + +\begin{lstlisting} +struct virtio_crypto_mac_session_para { + /* See VIRTIO_CRYPTO_MAC_* above */ + le32 algo; + /* hash result length */ + le32 hash_result_len; + /* length of authenticated key */ + le32 auth_key_len; + le32 padding; +}; +struct virtio_crypto_mac_session_output { + le64 auth_key_addr; /* guest key physical address */ +}; + +struct virtio_crypto_mac_create_session_req { + /* Device-readable part */ + struct virtio_crypto_mac_session_para para; + struct virtio_crypto_mac_session_output out; + /* Device-writable part */ + struct virtio_crypto_session_input input; +}; +\end{lstlisting} + +\subparagraph{Session operation: Symmetric algorithms session}\label{sec:Device Types / Crypto Device / Device +Operation / Control Virtqueue / Session operation / Session operation: Symmetric algorithms session} + +The request of symmetric session includes two parts, CIPHER algorithms and chain +algorithms (chaining CIPHER and HASH/MAC). The packet for CIPHER session is as follows: + +\begin{lstlisting} +struct virtio_crypto_cipher_session_para { + /* See VIRTIO_CRYPTO_CIPHER* above */ + le32 algo; + /* length of key */ + le32 keylen; +#define VIRTIO_CRYPTO_OP_ENCRYPT 1 +#define VIRTIO_CRYPTO_OP_DECRYPT 2 + /* encrypt or decrypt */ + le32 op; + le32 padding; +}; + +struct virtio_crypto_cipher_session_output { + le64 key_addr; /* guest key physical address */ +}; + +struct virtio_crypto_cipher_session_req { + struct virtio_crypto_cipher_session_para para; + struct virtio_crypto_cipher_session_output out; + struct virtio_crypto_session_input input; +}; +\end{lstlisting} + +The packet for algorithm chaining is as follows: + +\begin{lstlisting} +struct virtio_crypto_alg_chain_session_para { +#define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_HASH_THEN_CIPHER 1 +#define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_CIPHER_THEN_HASH 2 + le32 alg_chain_order; +/* Plain hash */ +#define VIRTIO_CRYPTO_SYM_HASH_MODE_PLAIN 1 +/* Authenticated hash (mac) */ +#define VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH 2 +/* Nested hash */ +#define VIRTIO_CRYPTO_SYM_HASH_MODE_NESTED 3 + le32 hash_mode; + struct virtio_crypto_cipher_session_para cipher_param; + union { + struct virtio_crypto_hash_session_para hash_param; + struct virtio_crypto_mac_session_para mac_param; + } u; + /* length of the additional authenticated data (AAD) in bytes */ + le32 aad_len; + le32 padding; +}; + +struct virtio_crypto_alg_chain_session_output { + struct virtio_crypto_cipher_session_output cipher; + struct virtio_crypto_mac_session_output mac; +}; + +struct virtio_crypto_alg_chain_session_req { + struct virtio_crypto_alg_chain_session_para para; + struct virtio_crypto_alg_chain_session_output out; + struct virtio_crypto_session_input input; +}; +\end{lstlisting} + +The packet for symmetric algorithm is as follows: + +\begin{lstlisting} +struct virtio_crypto_sym_create_session_req { + union { + struct virtio_crypto_cipher_session_req cipher; + struct virtio_crypto_alg_chain_session_req chain; + } u; + + /* Device-readable part */ + +/* No operation */ +#define VIRTIO_CRYPTO_SYM_OP_NONE 0 +/* Cipher only operation on the data */ +#define VIRTIO_CRYPTO_SYM_OP_CIPHER 1 +/* Chain any cipher with any hash or mac operation. The order + depends on the value of alg_chain_order param */ +#define VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING 2 + le32 op_type; + le32 padding; +}; +\end{lstlisting} + +\subparagraph{Session operation: AEAD session}\label{sec:Device Types / Crypto Device / Device +Operation / Control Virtqueue / Session operation / Session operation: AEAD session} + +The packet for AEAD session is as follows: + +\begin{lstlisting} +struct virtio_crypto_aead_session_para { + /* See VIRTIO_CRYPTO_AEAD_* above */ + le32 algo; + /* length of key */ + le32 key_len; + /* digest result length */ + le32 digest_result_len; + /* The length of the additional authenticated data (AAD) in bytes */ + le32 aad_len; + /* encrypt or decrypt, See above VIRTIO_CRYPTO_* */ + le32 op; + le32 padding; +}; + +struct virtio_crypto_aead_session_output { + le64 key_addr; /* guest key physical address */ +}; + +struct virtio_crypto_aead_create_session_req { + struct virtio_crypto_aead_session_para para; + struct virtio_crypto_aead_session_output out; + struct virtio_crypto_session_input input; +}; +\end{lstlisting} + +\drivernormative{\subparagraph}{Session operation: create session}{Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: create session} + +\begin{itemize*} +\item The driver MUST set the control general header and corresponding properties of the union in structure virtio_crypto_op_ctrl_req. See \ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}. +\item The driver MUST set \field{opcode} field based on service type: CIPHER, HASH, MAC, or AEAD. +\item The driver MUST set \field{queue_id} field to show used dataq. +\end{itemize*} + +\devicenormative{\subparagraph}{Session operation: create session}{Device Types / Crypto Device / Device +Operation / Control Virtqueue / Session operation / Session operation: create session} + +\begin{itemize*} +\item The device MUST set \field{session_id} field as a session identifier return to the driver when the device finishes processing session creation. +\item The device MUST set \field{status} field: VIRTIO_CRYPTO_OK: success; VIRTIO_CRYPTO_ERR: creation failed or device error; VIRTIO_CRYPTO_NOTSUPP: not supported; VIRTIO_CRYPTO_INVSESS: invalid session ID when the crypto operation is implemented. +\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 \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 which assigned by the device when a session is 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 \field{status} field: VIRTIO_CRYPTO_OK: success; VIRTIO_CRYPTO_ERR: failure or device error. +\end{itemize*} + +\subsubsection{Data Virtqueue}\label{sec:Device Types / Crypto Device / Device Operation / Data Virtqueue} + +The driver uses the data virtqueue to transmit the requests of crypto operation to the device, +and completes the data plane operations (such as crypto operation). + +The packet of dataq is as follows: + +\begin{lstlisting} +struct virtio_crypto_op_data_req { + struct virtio_crypto_op_header header; + + union { + struct virtio_crypto_sym_data_req sym_req; + struct virtio_crypto_hash_data_req hash_req; + struct virtio_crypto_mac_data_req mac_req; + struct virtio_crypto_aead_data_req aead_req; + } u; +}; +\end{lstlisting} + +The header is the general header and the union is of the algorithm-specific type, +which is set by the driver. All properties in the union are shown as follows. + +There is a unified idata structure for all symmetric algorithms, including CIPHER, HASH, MAC, and AEAD. + +The structure is defined as follows: + +\begin{lstlisting} +struct virtio_crypto_sym_input { + /* destination data, it's useless for plain HASH and MAC */ + struct virtio_crypto_iovec dst_data; + /* digest result guest address, it's useless for plain cipher algos */ + le64 digest_result_addr; + /* digest result length which is the same with session para above */ + le32 digest_result_len; + + le32 status; +}; +\end{lstlisting} + +\paragraph{Scatter-Gather Support}\label{sec:Device Types / Crypto Device / Device Operation / Data Virtqueue / Scatter-Gather Support} + +For scatter/gather list support, a buffer can be represented by virtio_crypto_iovec structure. + +The structure is defined as follows: + +\begin{lstlisting} +struct virtio_crypto_iovec { + /* Guest physical address */ + le64 addr; + /* Length of guest physical address */ + le32 len; +/* This marks a buffer as continuing via the next field */ +#define VIRTIO_CRYPTO_IOVEC_F_NEXT 1 + /* The flags as indicated above VIRTIO_CRYPTO_IOVEC_F_*. */ + le32 flags; + /* Pointer to next struct virtio_crypto_iovec if flags & NEXT */ + le64 next_iovec; +}; +\end{lstlisting} + +\field{addr} field specifies the guest physical address. \field{len} field specifies the length of guest physical address \field{addr}. +\field{flags} field is a flag used to identify the buffer is a scatter/gather list or not. +\field{next_iovec} field is a guest physical address which pointer to next struct virtio_crypto_iovec if \field{flags} is +set to VIRTIO_CRYPTO_IOVEC_F_NEXT. + +\drivernormative{\subparagraph}{Scatter-Gather Support}{Device Types / Crypto Device / Device Operation / Data Virtqueue / Scatter-Gather Support} + +\begin{itemize*} +\item The driver MUST allocate the guest memory pointed by \field{addr} field. +\item The driver MUST guarantee the guest memory pointed by \field{addr} is physically-contiguous. +\item The driver MUST specify the length of \field{addr} in \field{len} field. +\item The driver MUST set \field{flags} to VIRTIO_CRYPTO_IOVEC_F_NEXT and set the \field{next_iovec} if the buffer is of a scatter/gather list and not the last entry of the scatter/gather list. +\item The driver MUST set \field{flags} to ~VIRTIO_CRYPTO_IOVEC_F_NEXT if it's a single buffer or the last entry of one scatter/gather list. +\end{itemize*} + +\devicenormative{\subparagraph}{Scatter-Gather Support}{Device Types / Crypto Device / Device Operation / Data Virtqueue / Scatter-Gather Support} + +\begin{itemize*} +\item The device MUST handle the case of single buffer or a scatter/gather list followed by a single struct virtio_crypto_iovec with \field{flags}\&VIRTIO_CRYPTO_IOVEC_F_NEXT. +\end{itemize*} + +\subsubsection{HASH Service Operation}\label{sec:Device Types / Crypto Device / Device Operation / HASH Service Operation} + +\begin{lstlisting} +struct virtio_crypto_hash_input { + struct virtio_crypto_sym_input input; +}; + +struct virtio_crypto_hash_output { + /* source data */ + struct virtio_crypto_iovec src_data; + le32 padding; +}; + +struct virtio_crypto_hash_data_req { + /* Device-readable part */ + struct virtio_crypto_hash_output odata; + /* Device-writable part */ + struct virtio_crypto_hash_input idata; +}; +\end{lstlisting} + +Each data request uses virtio_crypto_hash_data_req structure to store information +used to run the HASH operations. The request only occupies one entry +in the Vring Descriptor Table in the virtio crypto device's dataq, which improves +the throughput of data transmitted for the HASH service, so that the virtio crypto +device can be better accelerated. + +The information includes the source data guest physical address stored by \field{src_data}.\field{addr}, +length of source data stored by \field{src_data}.\field{len}, and the digest result guest physical address +stored by \field{digest_result_addr} used to save the results of the HASH operations. +The address and length can determine exclusive content in the guest memory. + +\begin{note} +The guest memory is always guaranteed to be allocated and physically-contiguous +pointed by \field{digest_result_addr} in struct virtio_crypto_hash_input and +\field{src_data}.\field{addr} in struct virtio_crypto_hash_output is of single buffer. + +If the source data is a scatter/gather list, then each entry of scatter/gather list is always guaranteed to be physically-contiguous. +\end{note} + +\drivernormative{\paragraph}{HASH Service Operation}{Device Types / Crypto Device / Device Operation / HASH Service Operation} + +\begin{itemize*} +\item The driver MUST set the \field{session_id} in struct virtio_crypto_op_header to a valid value which assigned by the device when a session is created. +\item The driver MUST set \field{opcode} in struct virtio_crypto_op_header to VIRTIO_CRYPTO_HASH. +\item The driver MUST set the \field{queue_id} field to show used dataq in struct virtio_crypto_op_header. +\item The driver MUST specify all fields in struct virtio_crypto_hash_data_req, including \field{para}, \field{odata} and \field{idata} sub structures. +\item The driver MUST set \field{src_data}.\field{flag} to VIRTIO_CRYPTO_IOVEC_F_NEXT and set the \field{src_data}.\field{next_iovec} if the source data is of a scatter/gather list. +\item The driver MUST set \field{src_data}.\field{flag} to ~VIRTIO_CRYPTO_IOVEC_F_NEXT if it's a single buffer or the last entry of one scatter/gather list. +\end{itemize*} + +\devicenormative{\paragraph}{HASH Service Operation}{Device Types / Crypto Device / Device Operation / HASH Service Operation} + +\begin{itemize*} +\item The device MUST copy the results of HASH operations to the guest memory recorded by \field{digest_result_addr} field in struct virtio_crypto_hash_input. +\item The device MUST set \field{status} in strut virtio_crypto_hash_input: VIRTIO_CRYPTO_OK: success; VIRTIO_CRYPTO_ERR: creation failed or device error; VIRTIO_CRYPTO_NOTSUPP: not support. +\end{itemize*} + +\subsubsection{MAC Service Operation}\label{sec:Device Types / Crypto Device / Device Operation / MAC Service Operation} + +\begin{lstlisting} +struct virtio_crypto_mac_input { + struct virtio_crypto_sym_input input; +}; + +struct virtio_crypto_mac_output { + struct virtio_crypto_hash_output hash_output; +}; + +struct virtio_crypto_mac_data_req { + /* Device-readable part */ + struct virtio_crypto_mac_output odata; + /* Device-writable part */ + struct virtio_crypto_mac_input idata; +}; +\end{lstlisting} + +Each data request uses virtio_crypto_mac_data_req structure to store information +used to run the MAC operations. The request only occupies one entry +in the Vring Descriptor Table in the virtio crypto device's dataq, which improves +the throughput of data transmitted for the MAC service, so that the virtio crypto +device can get the better result of acceleration. + +The information includes the source data guest physical address stored by \field{hash_output}.\field{src_data}.\field{addr}, +the length of source data stored by \field{hash_output}.\field{src_data}.\field{len}, and the digest result guest physical address +stored by \field{digest_result_addr} used to save the results of the MAC operations. + +The address and length can determine exclusive content in the guest memory. + +\begin{note} +The guest memory is always guaranteed to be allocated and physically-contiguous +pointed by \field{digest_result_addr} in struct virtio_crypto_sym_input and +\field{hash_output}.\field{src_data}.\field{addr} in struct virtio_crypto_mac_output is of single buffer. + +If the source data is a scatter/gather list, then each entry of scatter/gather list is always guaranteed to be physically-contiguous. +\end{note} + +\drivernormative{\paragraph}{MAC Service Operation}{Device Types / Crypto Device / Device Operation / MAC Service Operation} + +\begin{itemize*} +\item The driver MUST set the \field{session_id} in struct virtio_crypto_op_header to a valid value which assigned by the device when a session is created. +\item The driver MUST set \field{opcode} in struct virtio_crypto_op_header to VIRTIO_CRYPTO_MAC. +\item The driver MUST set the \field{queue_id} field to show used dataq in struct virtio_crypto_op_header. +\item The driver MUST specify all fields in struct virtio_crypto_hash_data_req, including \field{para}, \field{odata} and \field{idata} sub structures. +\item The driver MUST set \field{hash_output}.\field{src_data}.\field{flag} to VIRTIO_CRYPTO_IOVEC_F_NEXT and set the \field{hash_output}.\field{src_data}.\field{next_iovec} if the source data is of a scatter/gather list. +\item The driver MUST set \field{hash_output}.\field{src_data}.\field{flag} to ~VIRTIO_CRYPTO_IOVEC_F_NEXT if it's a single buffer or the last entry of one scatter/gather list. +\end{itemize*} + +\devicenormative{\paragraph}{MAC Service Operation}{Device Types / Crypto Device / Device Operation / MAC Service Operation} + +\begin{itemize*} +\item The device MUST copy the results of MAC operations to the guest memory recorded by \field{digest_result_addr} field in struct virtio_crypto_mac_input. +\item The device MUST set \field{status} in strut virtio_crypto_mac_input: VIRTIO_CRYPTO_OK: success; VIRTIO_CRYPTO_ERR: creation failed or device error; VIRTIO_CRYPTO_NOTSUPP: not support. +\end{itemize*} + +\subsubsection{Symmetric algorithms Operation}\label{sec:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation} + +The packet of plain CIPHER service is as follows: + +\begin{lstlisting} +struct virtio_crypto_cipher_para { + /* + * Byte Length of valid IV data pointed to by the below iv_addr. + * + * - 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 dst data */ + le32 dst_data_len; + le32 padding; +}; + +struct virtio_crypto_cipher_input { + struct virtio_crypto_sym_input input; +}; + +struct virtio_crypto_cipher_output { + /* + * Initialization Vector or Counter Guest Address. + * + * - 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. + */ + le64 iv_addr; + /* source data */ + struct virtio_crypto_iovec src_data; +}; + +struct virtio_crypto_cipher_data_req { + /* Device-readable part */ + struct virtio_crypto_cipher_para para; + struct virtio_crypto_cipher_output odata; + /* Device-writable part */ + struct virtio_crypto_cipher_input idata; +}; +\end{lstlisting} + +The packet of algorithm chaining is as follows: + +\begin{lstlisting} +struct virtio_crypto_alg_chain_data_para { + struct virtio_crypto_cipher_para cipher; +}; + +struct virtio_crypto_alg_chain_data_output { + /* Device-writable part */ + struct virtio_crypto_cipher_output cipher; + + /* Device-readable part */ + /* additional auth data guest address */ + struct virtio_crypto_iovec add_data; +}; + +struct virtio_crypto_alg_chain_data_input { + struct virtio_crypto_sym_input input; +}; + +struct virtio_crypto_alg_chain_data_req { + /* Device-readable part */ + struct virtio_crypto_alg_chain_data_para para; + struct virtio_crypto_alg_chain_data_output odata; + /* Device-writable part */ + struct virtio_crypto_alg_chain_data_input idata; +}; +\end{lstlisting} + +The packet of symmetric algorithm is as follows: + +\begin{lstlisting} +struct virtio_crypto_sym_data_req { + union { + struct virtio_crypto_cipher_data_req cipher; + struct virtio_crypto_alg_chain_data_req chain; + } u; + + /* Device-readable part */ + + /* See above VIRTIO_CRYPTO_SYM_OP_* */ + le32 op_type; + le32 padding; +}; +\end{lstlisting} + +Each data request uses the virtio_crypto_cipher_data_req structure to store information +used to run the CIPHER operations. The request only occupies one entry +in the Vring Descriptor Table in the virtio crypto device's dataq, which improves +the throughput of data transmitted for the CIPHER service, so that the virtio crypto +device can get the better result of acceleration. + +In the first virtio_crypto_cipher_para structure, \field{iv_len} specifies the length of the initialization vector or counter, +\field{src_data_len} specifies the length of the source data, and \field{dst_data_len} specifies the +length of the destination data. + +In the following virtio_crypto_cipher_input structure, \field{dst_data_addr} specifies the destination +data guest physical address used to store the results of the CIPHER operations, and \field{status} specifies +the CIPHER operation status. + +In the virtio_crypto_cipher_output structure, \field{iv_addr} specifies the guest physical address of initialization vector, +\field{src_data}.\field{addr} specifies the source data guest physical address. + +The addresses and length can determine exclusive content in the guest memory. + +\begin{note} +The guest memory is always guaranteed to be allocated and physically-contiguous +pointed by \field{dst_data}.\field{addr} in struct virtio_crypto_cipher_input, +\field{iv_addr} and \field{src_data}.\field{addr} in struct virtio_crypto_cipher_output is of single buffer. + +If the source data or destination data is a scatter/gather list, then each entry of scatter/gather list is always guaranteed to be physically-contiguous. +\end{note} + +\drivernormative{\paragraph}{Symmetric algorithms Operation}{Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation} + +\begin{itemize*} +\item The driver MUST set the \field{session_id} in struct virtio_crypto_op_header to a valid value which assigned by the device when a session is created. +\item The driver MUST set \field{opcode} in struct virtio_crypto_op_header to VIRTIO_CRYPTO_CIPHER_ENCRYPT or VIRTIO_CRYPTO_CIPHER_DECRYPT. +\item The driver MUST set the \field{queue_id} field to show used dataq in struct virtio_crypto_op_header. +\item The driver MUST specify the fields in struct virtio_crypto_sym_data_req, including \field{para}, \field{odata} and \field{idata} sub structures based on the operation type of session. +\item The driver MUST specify the fields of struct virtio_crypto_cipher_data_req in struct virtio_crypto_sym_data_req if the created session is based on VIRTIO_CRYPTO_SYM_OP_CIPHER. +\item The driver MUST specify the fields of both struct virtio_crypto_cipher_data_req and struct virtio_crypto_mac_data_req in struct virtio_crypto_sym_data_req if the created session +\item is of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING type and in the VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH mode. +\item The driver MUST set \field{src_data}.\field{flag} to VIRTIO_CRYPTO_IOVEC_F_NEXT and set the \field{src_data}.\field{next_iovec} if the source data is of a scatter/gather list. +\item The driver MUST set \field{src_data}.\field{flag} to ~VIRTIO_CRYPTO_IOVEC_F_NEXT if it's a single buffer or the last entry of one scatter/gather list. +\end{itemize*} + +\devicenormative{\paragraph}{Symmetric algorithms Operation}{Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation} + +\begin{itemize*} +\item The device MUST parse the virtio_crypto_sym_data_req based on the \field{opcode} in general header. +\item The device SHOULD only parse fields of struct virtio_crypto_cipher_data_req in struct virtio_crypto_sym_data_req if the created session is VIRTIO_CRYPTO_SYM_OP_CIPHER type. +\item The device MUST parse fields of both struct virtio_crypto_cipher_data_req and struct virtio_crypto_mac_data_req in struct virtio_crypto_sym_data_req if the created +session is of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING operation type and in the VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH mode. +\item The device MUST copy the result of cryptographic operation to the guest memory recorded by \field{dst_data}.\field{addr} field in struct virtio_crypto_cipher_input in plain CIPHER mode. +\item The device MUST copy the result of HASH/MAC operation to the guest memory recorded by \field{digest_result_addr} field in struct virtio_crypto_alg_chain_data_input is of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING type. +\item The device MUST set the \field{status} field in strut virtio_crypto_cipher_input or virtio_crypto_alg_chain_data_input structure: +VIRTIO_CRYPTO_OK: success; VIRTIO_CRYPTO_ERR: creation failed or device error; VIRTIO_CRYPTO_NOTSUPP: not supported. +\end{itemize*} + +\paragraph{Steps of Operation}\label{sec:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation / Steps of Operation} + +\subparagraph{Step1: Create session}\label{sec:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation / Steps of Operation / Step1: Create session} + +\begin{enumerate} +\item The driver specifies information in struct virtio_crypto_op_ctrl_req, including the algorithm name, key, keylen etc; +\item The driver adds the request of session creation into the controlq's Vring Descriptor Table; +\item The driver kicks the device; +\item The device receives the request from controlq; +\item The device parses information about the request, and determines the information concerning the backend crypto accelerator; +\item The device packs information based on the APIs of the backend crypto accelerator; +\item The device invokes the session creation APIs of the backend crypto accelerator to create a session; +\item The device returns the session id to the driver. +\end{enumerate} + +\subparagraph{Step2: Execute cryptographic operation}\label{sec:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation / Steps of Operation / Step2: Execute cryptographic operation} + +\begin{enumerate} +\item The driver specifies information in struct virtio_crypto_op_data_req, including struct virtio_crypto_op_header and struct virtio_crypto_sym_data_req, see \ref{sec:Device Types / Crypto Device / Device + Operation / Symmetric algorithms Operation}; +\item The driver adds the request for cryptographic operation into the dataq's Vring Descriptor Table; +\item The driver kicks the device (Or the device actively polls the dataq's Vring Descriptor Table); +\item The device receives the request from dataq; +\item The device parses information about the request, and determines the identification information for the backend crypto accelerator. For example, converting guest physical addresses to host physical addresses; +\item The device packs identification information based on the API of the backend crypto accelerator; +\item The device invokes the cryptographic APIs of the backend crypto accelerator; +\item The backend crypto accelerator executes the cryptographic operation implicitly; +\item The device receives the cryptographic results from the backend crypto accelerator (synchronous or asynchronous); +\item The device sets the \field{status} in struct virtio_crypto_cipher_input; +\item The device updates and flushes the Used Ring to return the cryptographic results to the driver; +\item The device notifies the driver (Or the driver actively polls the dataq's Used Ring); +\item The driver saves the cryptographic result. +\end{enumerate} + +\begin{note} +\begin{itemize*} +\item The driver MAY support both synchronous and asynchronous cryptographic operation. Then the performance + is poor in synchronous operation since frequent context switching and virtualization overhead. + The driver should by preference use asynchronous cryptographic operation. +\item For better performance, the device should by preference use vhost scheme (user space or kernel space) + as the backend crypto accelerator in the real production environment. +\end{itemize*} +\end{note} + +\subsubsection{AEAD Service Operation}\label{sec:Device Types / Crypto Device / Device Operation / AEAD Service Operation} + +\begin{lstlisting} +struct virtio_crypto_aead_para { + /* + * Byte Length of valid IV data pointed to by the below iv_addr parameter. + * + * - For GCM mode, this is either 12 (for 96-bit IVs) or 16, in which + * case iv_addr 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 */ + le32 dst_data_len; +}; + +struct virtio_crypto_aead_input { + struct virtio_crypto_sym_input input; +}; + +struct virtio_crypto_aead_output { + /* + * Initialization Vector Guest Address. + * + * - 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_addr[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. + */ + le64 iv_addr; + /* source data */ + struct virtio_crypto_iovec src_data; + /* additional auth data guest address */ + struct virtio_crypto_iovec add_data; +}; + +struct virtio_crypto_aead_data_req { + /* Device-readable part */ + struct virtio_crypto_aead_para para; + struct virtio_crypto_aead_output odata; + /* Device-writable part */ + struct virtio_crypto_aead_input idata; +}; +\end{lstlisting} + +Each data request uses virtio_crypto_aead_data_req structure to store information +used to implement the CIPHER operations. The request only occupies one entry +in the Vring Descriptor Table in the virtio crypto device's dataq, which improves +the throughput of data transmitted for the AEAD service, so that the virtio crypto +device can be better accelerated. + +In the first virtio_crypto_aead_para structure, \field{iv_len} specifies the length of the initialization vector; +\field{aad_len} specifies the length of additional authentication data, \field{src_data_len} specifies the +length of the source data; \field{dst_data_len} specifies the length of the destination data. + +In the following virtio_crypto_aead_input structure, \field{dst_data}.\field{addr} specifies destination +data guest physical address used to store the results of the CIPHER operations; \field{digest_result_addr} specifies +the digest result guest physical address used to store the results of the HASH/MAC operations; \field{status} specifies +the status of AEAD operation. + +In the virtio_crypto_aead_output structure, \field{iv_addr} specifies the guest physical address of initialization vector, +\field{src_data}.\field{addr} specifies the source data guest physical address, \field{add_data}.\field{addr} specifies the guest physical address +of additional authentication data. + +The addresses and length can determine exclusive content in the guest memory. + +\begin{note} +The guest memory MUST be guaranteed to be allocated and physically-contiguous +pointed by \field{dst_data}.\field{addr} and \field{digest_result_addr} in struct virtio_crypto_aead_input, +\field{iv_addr}, \field{add_data}.\field{addr} and \field{src_data}.\field{addr} in struct virtio_crypto_aead_output is of single buffer. + +If the source data, destination data or additional authentication data is a scatter/gather list, then each entry of scatter/gather list is always guaranteed to be physically-contiguous. +\end{note} + +\drivernormative{\paragraph}{AEAD Service Operation}{Device Types / Crypto Device / Device Operation / AEAD Service Operation} + +\begin{itemize*} +\item The driver MUST set the \field{session_id} in struct virtio_crypto_op_header to a valid value which assigned by the device when a session is created. +\item The driver MUST set \field{opcode} in struct virtio_crypto_op_header to VIRTIO_CRYPTO_AEAD_ENCRYPT or VIRTIO_CRYPTO_AEAD_DECRYPT. +\item The driver MUST set the \field{queue_id} field to show used dataq in struct virtio_crypto_op_header. +\item The driver MUST specify the fields in struct virtio_crypto_aead_data_req, including \field{para}, \field{odata} and \field{idata} sub structures. +\item The driver MUST set \field{src_data}.\field{flag} to VIRTIO_CRYPTO_IOVEC_F_NEXT and set the \field{src_data}.\field{next_iovec} if the source data is of a scatter/gather list. +\item The driver MUST set \field{src_data}.\field{flag} to ~VIRTIO_CRYPTO_IOVEC_F_NEXT if it's a single buffer or the last entry of one scatter/gather list. +\end{itemize*} + +\devicenormative{\paragraph}{AEAD Service Operation}{Device Types / Crypto Device / Device Operation / AEAD Service Operation} + +\begin{itemize*} +\item The device MUST parse the virtio_crypto_aead_data_req based on the \field{opcode} in general header. +\item The device MUST copy the result of cryptographic operation to the guest memory recorded by \field{dst_data}.\field{addr} field in struct virtio_crypto_aead_input. +\item The device MUST copy the digest result to the guest memory recorded by \field{digest_result_addr} field in struct virtio_crypto_aead_input. +\item The device MUST set the \field{status} field in strut virtio_crypto_aead_input: VIRTIO_CRYPTO_OK: success; VIRTIO_CRYPTO_ERR: creation failed or device error; VIRTIO_CRYPTO_NOTSUPP: not supported. +\item When the \field{opcode} is VIRTIO_CRYPTO_AEAD_DECRYPT, the device MUST verify and return the verification result to the driver, and if the verification result is incorrect, VIRTIO_CRYPTO_BADMSG (bad message) MUST be returned to the driver. +\end{itemize*} \ No newline at end of file