From patchwork Mon Aug 1 09:20:20 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Gonglei (Arei)" X-Patchwork-Id: 9254057 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 446EA6075F for ; Mon, 1 Aug 2016 09:33:24 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3077C28335 for ; Mon, 1 Aug 2016 09:33:24 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 22FED28464; Mon, 1 Aug 2016 09:33:24 +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 DDB1028335 for ; Mon, 1 Aug 2016 09:33:21 +0000 (UTC) Received: from localhost ([::1]:48698 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bU9b7-00037D-0D for patchwork-qemu-devel@patchwork.kernel.org; Mon, 01 Aug 2016 05:33:21 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:40139) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bU9Q1-0001yH-Il for qemu-devel@nongnu.org; Mon, 01 Aug 2016 05:21:57 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bU9Px-00043R-83 for qemu-devel@nongnu.org; Mon, 01 Aug 2016 05:21:52 -0400 Received: from szxga01-in.huawei.com ([58.251.152.64]:12051) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bU9Pv-00043G-HM for qemu-devel@nongnu.org; Mon, 01 Aug 2016 05:21:49 -0400 Received: from 172.24.1.47 (EHLO szxeml430-hub.china.huawei.com) ([172.24.1.47]) by szxrg01-dlp.huawei.com (MOS 4.3.7-GA FastPath queued) with ESMTP id DOQ81926; Mon, 01 Aug 2016 17:20:37 +0800 (CST) Received: from localhost (10.177.18.62) by szxeml430-hub.china.huawei.com (10.82.67.185) with Microsoft SMTP Server id 14.3.235.1; Mon, 1 Aug 2016 17:20:26 +0800 From: Gonglei To: , Date: Mon, 1 Aug 2016 17:20:20 +0800 Message-ID: <1470043221-37728-2-git-send-email-arei.gonglei@huawei.com> X-Mailer: git-send-email 2.6.3.windows.1 In-Reply-To: <1470043221-37728-1-git-send-email-arei.gonglei@huawei.com> References: <1470043221-37728-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.0A0B0202.579F1468.0126, 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: d1563b9a0c30a54ffd40204631d27813 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 v6 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: Ola.Liljedahl@arm.com, brian.a.keating@intel.com, mst@redhat.com, xin.zeng@intel.com, hanweidong@huawei.com, luonengjun@huawei.com, peter.huangpeng@huawei.com, john.griffin@intel.com, Gonglei , liang.j.ma@intel.com, stefanha@redhat.com, cornelia.huck@de.ibm.com, Varun.Sethi@freescale.com, Jani.Kokkonen@huawei.com, denglingli@chinamobile.com, weidong.huang@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). The virtio crypto device can provide five crypto services: CIPHER, MAC, HASH, AEAD, KDF, ASYM, PRIMITIVE. In this patch, CIPHER, MAC, HASH, AEAD services are introduced. 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 --- content.tex | 2 + virtio-crypto.tex | 793 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 795 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..9465de3 --- /dev/null +++ b/virtio-crypto.tex @@ -0,0 +1,793 @@ +\section{Crypto Device}\label{sec:Device Types / Crypto Device} + +The virtio crypto device is a virtual crypto device (ie. hardware +crypto accelerator card). The encryption and decryption requests of +are placed in the data queue, and handled by the real hardware crypto +accelerators finally. The second queue is the control queue, which +is used to create or destroy session for symmetric algorithms, and +to control some advanced features in the future. The virtio crypto +device can provide seven crypto services: CIPHER, MAC, HASH, AEAD, +KDF, ASYM, PRIMITIVE. + +\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} (\field{max_dataqueues} >= 1). + +\subsection{Feature bits}\label{sec:Device Types / Crypto Device / Feature bits} + None currently defined + +\subsection{Device configuration layout}\label{sec:Device Types / Crypto Device / Device configuration layout} + +Thirteen driver-read-only configuration fields are currently defined. + +\begin{lstlisting} +struct virtio_crypto_config { + le32 version; + le16 status; + le16 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 asym_algo; + le32 kdf_algo; + le32 aead_algo; + le32 primitive_algo; +}; +\end{lstlisting} + +The first driver-read-only field, \field{version} specifies the virtio crypto's +version, which is reserved for back-compatibility in future.It's currently +defined for the version field: + +\begin{lstlisting} +#define VIRTIO_CRYPTO_VERSION_1 (1) +\end{lstlisting} + +One read-only bit (for the device) is currently defined for the \field{status} +field: VIRTIO_CRYPTO_S_HW_READY. + +\begin{lstlisting} +#define VIRTIO_CRYPTO_S_HW_READY (1 << 0) +\end{lstlisting} + +The following driver-read-only field, \field{max_dataqueuess} specifies the +maximum number of data virtqueues (dataq1\ldots dataqN). The crypto_services +shows the crypto services the virtio crypto supports. The service currently +defined are: + +\begin{lstlisting} +#define VIRTIO_CRYPTO_NO_SERVICE (0) /* cipher services */ +#define VIRTIO_CRYPTO_SERVICE_CIPHER (1) /* cipher services */ +#define VIRTIO_CRYPTO_SERVICE_HASH (2) /* hash service */ +#define VIRTIO_CRYPTO_SERVICE_MAC (3) /* MAC (Message Authentication Codes) service */ +#define VIRTIO_CRYPTO_SERVICE_AEAD (4) /* AEAD(Authenticated Encryption with Associated Data) service */ +\end{lstlisting} + +The last driver-read-only fields specify detailed algorithms mask which +the device offered for corresponding service. The below CIPHER algorithms +are defined currently: + +\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 below HASH algorithms are defined currently: + +\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 below MAC algorithms are defined currently: + +\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_CMAC_KASUMI_F9 27 +#define VIRTIO_CRYPTO_MAC_CMAC_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 below AEAD algorithms are defined currently: + +\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} + +\subsubsection{Device Requirements: Device configuration layout}\label{sec:Device Types / Crypto Device / Device configuration layout / Device Requirements: Device configuration layout} + +\begin{itemize*} +\item The device MUST set \field{version} in version filed. +\item The device MUST set \field{max_dataqueues} to between 1 and 65535 inclusive. +\item The device SHOULD set \field{status} according to the status of the hardware-backed implementation. +\item The device MUST set \field{crypto_services} according to the crypto services which the device offered. +\item The device MUST set detailed algorithms mask according to crypto_services field. +\end{itemize*} + +\subsubsection{Driver Requirements: Device configuration layout}\label{sec:Device Types / Crypto Device / Device configuration layout / Driver Requirements: 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. +\item The driver MAY read \field{max_dataqueues} field to discover how many 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 detail algorithms field according to crypto_services field. +\end{itemize*} + +\subsection{Device Initialization}{Device Types / Crypto Device / Device Initialization} + +The driver SHOULD perform a typical initialization routine like so: + +\begin{enumerate} +\item Identify and initialize data virtqueue, up to \field{max_dataqueues}. +\item Identify the control virtqueue. +\item Identify the ready status of hardware-backend comes from the \field{status}. +\item Read the supported crypto services from bits of \field{crypto_servies}. +\item Read the supported algorithms according to \field{crypto_services} field. +\end{enumerate} + +\subsection{Device Operation}\label{sec:Device Types / Crypto Device / Device Operation} + +Packets can be transmitted by placing them in both the controlq and dataq. +The packet are consisted of general header and services specific request, +Where 'general header' is for all crypto request, 'service specific request' +is composed of operation parameter + input data + output data in generally. +Operation parameters are algorithm-specific parameters, input data is the +data should be operated , output data is the "operation result + result buffer". +The general header of controlq: + +\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; + /* control flag to control the request */ + u8 flag; + /* data virtqeueu id */ + le16 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; + /* control flag to control the request */ + u8 flag; + /* data virtqeueu id */ + le16 queue_id; + /* session_id should be service-specific algorithms */ + le64 session_id; +}; +\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 finish the non-data plane operations, such as session +operations (see \ref{sec:Device Types / Crypto Device / Device Operation / 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 sym_destroy_session; + } u; +}; +\end{lstlisting} + +The header is the general header, the union is algorithm-specific type, +which is set by the driver. All the properties in the union will be shown as follow. + +\subsubsection{Session operation}\label{sec:Device Types / Crypto Device / Device Operation / Session operation} + +The symmetric algorithms have 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 setup data, including the cipher algorithm and mode, + the key and its length, and the direction (encrypt or decrypt). +\item The hash/mac setup 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} + +\paragraph{Session operation: HASH session}\label{sec:Device Types / Crypto Device / Device Operation / Session operation / Session operation: HASH session} + +The packet of HASH session is: + +\begin{lstlisting} +struct virtio_crypto_sym_session_input { + u8 status; + le64 session_id; +}; + +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 { + struct virtio_crypto_hash_session_para parameter; + /* + * in header guest physical address, See struct virtio_crypto_sym_session_input + * above + */ + le64 inhdr_addr; +}; +\end{lstlisting} + +\paragraph{Session operation: MAC session}\label{sec:Device Types / Crypto Device / Device +Operation / Session operation / Session operation: MAC session} + +The packet of MAC session is: + +\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; +}; +struct virtio_crypto_mac_create_session_req { + struct virtio_crypto_mac_session_para parameter; + /* + * in header guest physical address, See struct virtio_crypto_sym_session_input + * above + */ + le64 inhdr_addr; +}; +\end{lstlisting} + +\paragraph{Session operation: Symmetric algorithms session}\label{sec:Device Types / Crypto Device / Device +Operation / Session operation / Session operation: Symmetric algorithms session} + +The symmetric session include both ciphers (CIPHER service) and chain +algorithms (chain cipher and hash/mac). The packet of symmetric session is: + +\begin{lstlisting} +struct virtio_crypto_cipher_session_para { +/* See VIRTIO_CRYPTO_CIPHER* above */ + le32 algo; + /* length of key */ + le32 keylen; + /* encrypt or decrypt */ + u8 op; +}; +struct virtio_crypto_sym_create_session_req { +/* 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 + u8 op_type; + + union { + struct virtio_crypto_cipher_session_para cipher_param; + struct virtio_crypto_alg_chain_param { +#define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_HASH_THEN_CIPHER 1 +#define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_CIPHER_THEN_HASH 2 + u8 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 + u8 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; + } chain; + } sym; + + /* + * in header guest physical address, See struct virtio_crypto_sym_session_input + * above + */ + le64 inhdr_addr; +}; +\end{lstlisting} + +\paragraph{Session operation: AEAD session}\label{sec:Device Types / Crypto Device / Device +Operation / Session operation / Session operation: AEAD session} + +The packet of AEAD session is: + +\begin{lstlisting} +struct virtio_crypto_aead_session_para { + /* See VIRTIO_CRYPTO_AEAD_* above*/ + u8 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 */ + u8 op; +}; +struct virtio_crypto_aead_create_session_req { + struct virtio_crypto_aead_session_para parameter; + /* + * in header guest physical address, See struct virtio_crypto_sym_session_input + * above + */ + le64 inhdr_addr; +}; +\end{lstlisting} + +\paragraph{Session operation: create session}\label{sec:Device Types / Crypto Device / Device +Operation / Session operation / Session operation: create session} + +A request of creating a session including the following information: + +\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 sym_destroy_session; + } u; +}; +\end{lstlisting} + +\subparagraph{Driver Requirements: Session operation: create session}\label{sec:Device Types / Crypto Device / Device +Operation / Session operation / Session operation: create session / Driver Requirements: Session operation: create session} + +The driver MUST set the control general header and corresponding property +of union in structure virtio_crypto_op_ctrl_req. See \ref{sec:Device Types / Crypto Device / Device Operation}. +Take the example of MAC service, the driver MUST set VIRTIO_CRYPTO_MAC_CREATE_SESSION +for \field{opcode} field in struct virtio_crypto_op_ctrl_req, and set the \field{queue_id} +to show dataq used. + +\subparagraph{Device Requirements: Session operation: create session}\label{sec:Device Types / Crypto Device / Device +Operation / Session operation / Session operation: create session / Device Requirements: Session operation: create session} + +The device MUST return a session identifier to the driver when the device +finishes the processing of session creation. The session creation request +MUST end by a GPA of tailer: \field{inhdr_addr} field in struct virtio_crypto_*_create_session_req +of each crypto service. The \field{inhdr_addr} field point to the below structure: + +\begin{lstlisting} +struct virtio_crypto_sym_session_input { + u8 status; + le64 session_id; +}; +\end{lstlisting} + +Both status and session_id are written by the device: either VIRTIO_CRYPTO_OP_OK for success, +VIRTIO_CRYPTO_OP_ERR for creation failed or device error, VIRTIO_CRYPTO_OP_NOTSUPP for not support, +VIRTIO_CRYPTO_OP_INVSESS for invalid session id when executing crypto operations. + +\begin{lstlisting} +#define VIRTIO_CRYPTO_OP_OK 0 +#define VIRTIO_CRYPTO_OP_ERR 1 +#define VIRTIO_CRYPTO_OP_BADMSG 2 +#define VIRTIO_CRYPTO_OP_NOTSUPP 3 +#define VIRTIO_CRYPTO_OP_INVSESS 4 +\end{lstlisting} + +\paragraph{Session operation: destroy session}\label{sec:Device Types / Crypto Device / Device +Operation / Session operation / Session operation: destroy session} + +A request which destroy a session including the following information: + +\begin{lstlisting} +struct virtio_crypto_destroy_session_req { + le64 session_id; /* OUT parameter */ + u8 status; /* IN parameter */ +}; +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 sym_destroy_session; + } u; +}; +\end{lstlisting} + +\subparagraph{Driver Requirements: Session operation: destroy session}\label{sec:Device Types / Crypto Device / Device +Operation / Session operation / Session operation: destroy session / Driver Requirements: Session operation: destroy session} + +The driver MUST set the control general header and corresponding property +of union in struct virtio_crypto_op_ctrl_req. See \ref{sec:Device Types / Crypto Device / Device Operation}. +Take the example of MAC service, the driver MUST set VIRTIO_CRYPTO_MAC_DESTROY_SESSION +for \field{opcode} field in struct virtio_crypto_op_ctrl_req, and set the \field{queue_id} shows dataq used. +The driver MUST set the \field{session_id} which MUST be a valid value which assigned by the +device when a session was created. + +\subparagraph{Device Requirements: Session operation: destroy session}\label{sec:Device Types / Crypto Device / Device +Operation / Session operation / Session operation: destroy session / Device Requirements: Session operation: destroy session} + +Status is written by the device: either VIRTIO_CRYPTO_OP_OK for success, VIRTIO_CRYPTO_OP_ERR for failure or device error. + +\subsubsection{Crypto operation}\label{sec:Device Types / Crypto Device / Device Operation / Crypto operation} + +The driver uses the dataq to finish the data plane operations (such as crypto operation). +The packet of dataq: + +\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, the union is algorithm-specific type, +which are set by the driver. All the properties in the union will be shown as follow. + +\paragraph{Crypto operation: HASH operation}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: HASH operation} + +\begin{lstlisting} +struct virtio_crypto_sym_crypt_op_inhdr { + u8 status; +}; + +struct virtio_crypto_hash_para { + /* length of source data */ + le32 src_data_len; +}; + +struct virtio_crypto_hash_input { + le64 digest_result_addr; /* digest result guest physical address */ + /* + * in header guest physical address, See struct virtio_crypto_sym_crypt_op_inhdr + * above + */ + le64 inhdr_addr; +}; + +struct virtio_crypto_hash_output { + le64 src_data_addr; /* source data guest physical address */ +}; + +struct virtio_crypto_hash_data_req { + struct virtio_crypto_hash_para parameter; + struct virtio_crypto_hash_input idata; + struct virtio_crypto_hash_output odata; +}; +\end{lstlisting} + +Both input and output parameters store the guest physical address (GPA) only so +that each data operation request only occupies one entry of the Vring descriptor +table, which improves the throughput of data transferring for HASH crypto service. +The struct virtio_crypto_hash_para store the corresponding parameters, such as +\field{src_data_len}. The length and GPA can determine the specific content in +the guest memory. + +\subparagraph{Driver Requirements: Crypto operation: HASH operation}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: HASH operation / Driver Requirements: Crypto operation: HASH operation} + +The driver MUST set the \field{opcode}, \field{session_id} in struct virtio_crypto_op_header. +The \field{opcode} is set to VIRTIO_CRYPTO_HASH, \field{session_id} MUST be a valid value +which assigned by the device when a session was created. +The driver SHOULD set the \field{queue_id} field to show dataq used in struct virtio_crypto_op_header. +The driver MUST fill out all fields in struct virtio_crypto_hash_data_req, including \field{parameter}, +\field{idata} and \field{odata} sub structures. + +Note: \field{inhdr_addr} is a GPA pointed the struct virtio_crypto_sym_crypt_op_inhdr +which allocated by the driver. + +\subparagraph{Device Requirements: Crypto operation: HASH operation}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: HASH operation / Device Requirements: Crypto operation: HASH operation} + +The device MUST copy the result of hash operation recorded by \field{digest_result_addr} +filed in struct virtio_crypto_hash_input. +The device MUST set the status recorded by \field{inhdr_addr field} in strut virtio_crypto_hash_input +which point struct virtio_crypto_sym_crypt_op_inhdr: either VIRTIO_CRYPTO_OP_OK for success, +VIRTIO_CRYPTO_OP_ERR for creation failed or device error, VIRTIO_CRYPTO_OP_NOTSUPP for not support. + +\paragraph{Crypto operation: MAC operation}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: MAC operation} + +\begin{lstlisting} +struct virtio_crypto_mac_para { + struct virtio_crypto_hash_para hash_para; +}; + +struct virtio_crypto_mac_input { + struct virtio_crypto_hash_input hash_input; +}; + +struct virtio_crypto_mac_output { + struct virtio_crypto_hash_output hash_output; +}; + +struct virtio_crypto_mac_data_req { + struct virtio_crypto_mac_para parameter; + struct virtio_crypto_mac_input idata; + struct virtio_crypto_mac_output odata; +}; +\end{lstlisting} + +Both input and output parameters store the guest physical address (GPA) only so +that each data operation request only occupies one entry of the Vring descriptor +table, which improves the throughput of data transferring for MAC crypto service. +The struct virtio_crypto_mac_para store the corresponding parameters, such as +\field{src_data_len}. The length and GPA can determine the specific content in the guest memory. + +\subparagraph{Driver Requirements: Crypto operation: MAC operation}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: MAC operation / Driver Requirements: Crypto operation: MAC operation} + +Refer to the hash operation. +The driver MUST set the \field{opcode} field to VIRTIO_CRYPTO_MAC. + +\subparagraph{Device Requirements: Crypto operation: MAC operation}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: MAC operation / Device Requirements: Crypto operation: MAC operation} + +Refer to the hash operation. + +\paragraph{Crypto operation: Symmetric algorithms operation}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: Symmetric algorithms operation} + +\begin{lstlisting} +struct virtio_crypto_cipher_para { + le32 iv_len; + /* length of source data */ + le32 src_data_len; + /* length of dst data */ + le32 dst_data_len; +}; +struct virtio_crypto_cipher_input { + le64 dst_data_addr; /* destination data guest physical address */ + /* + * in header guest physical address, See struct virtio_crypto_sym_crypt_op_inhdr + * above + */ + le64 inhdr_addr; +}; + +struct virtio_crypto_cipher_output { + le64 iv_addr; /* iv guest physical address */ + le64 src_data_addr; /* source data guest physical address */ +}; +struct virtio_crypto_cipher_data_req { + struct virtio_crypto_cipher_para parameter; + struct virtio_crypto_cipher_input idata; + struct virtio_crypto_cipher_output odata; +}; +struct virtio_crypto_sym_data_req { + struct virtio_crypto_cipher_data_req cipher_req; + union { + struct virtio_crypto_hash_data_req hash_req; + struct virtio_crypto_mac_data_req mac_req; + } u; +}; +\end{lstlisting} + +Both input and output parameters store the guest physical address (GPA) only so that +each data operation request only occupies one entry of the Vring descriptor table, +which improves the throughput of data transferring for symmetric algorithms. +The struct virtio_crypto_cipher_para store the corresponding parameters, +such as \field{src_data_len}. The length and GPA can determine the specific content in the guest memory. + +\subparagraph{Driver Requirements: Crypto operation: Symmetric algorithms encryption}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: Symmetric algorithms operation / Driver Requirements: Crypto operation: Symmetric algorithms encryption} + +Refer to the hash operation. +The driver MUST set the opcode field to VIRTIO_CRYPTO_CIPHER_ENCRYPT. +The driver MUST fill out the fields in struct virtio_crypto_sym_data_req according to +the operation type of the session. For example, if the created session is based +on VIRTIO_CRYPTO_SYM_OP_CIPHER, that means the driver just SHOULD fill out fields +of struct virtio_crypto_cipher_data_req in struct virtio_crypto_sym_data_req. +If the created session is VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING type and +VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH mode, that means the driver SHOULD fill out +fields of both struct virtio_crypto_cipher_data_req and struct +virtio_crypto_mac_data_req mac_req in struct virtio_crypto_sym_data_req. + +\subparagraph{Device Requirements: Crypto operation: Symmetric algorithms encryption}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: Symmetric algorithms operation / Device Requirements: Crypto operation: Symmetric algorithms encryption} + +The device MUST parse the virtio_crypto_sym_data_req according to the session_id in general header. +For example, The device SHOULD only parsed 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. +The driver SHOULD parse fields of both struct virtio_crypto_cipher_data_req and struct +virtio_crypto_mac_data_req mac_req in struct virtio_crypto_sym_data_req if the created +session is VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING operation type and VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH mode. + +The device MUST copy the result of encryption operation recorded by \filed{dst_data_addr} filed in struct virtio_crypto_cipher_input in plain cipher mode. +The device MUST copy the result of hash operation recorded by \filed{digest_result_addr} filed in struct virtio_crypto_hash_input in chain hash/mac mode. +The device MUST set the status recorded by \filed{inhdr_addr} field in strut virtio_crypto_cipher_input which point +struct virtio_crypto_sym_crypt_op_inhdr: either VIRTIO_CRYPTO_OP_OK for success, VIRTIO_CRYPTO_OP_ERR for creation +failed or device error, VIRTIO_CRYPTO_OP_NOTSUPP for not support. + +\subparagraph{Device Requirements: Crypto operation: Steps of encryption}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: Symmetric algorithms operation / Device Requirements: Crypto operation: Steps of encryption} + +Step1: Create a session: +\begin{enumerate} +\item The driver fills out the context message, including algorithm name, key, keylen etc; +\item The driver sends a context message to the backend device by controlq; +\item The device creates a session using the message transmitted by controlq; +\item Return the session id to the driver. +\end{enumerate} + +Step2: Execute the detail encryption operation: +\begin{enumerate} +\item The driver fills out the encrypt requests; +\item Put the requests into dataq and kick the virtqueue; +\item The device executes the encryption operation according the requests' arguments; +\item The device returns the encryption result to the driver by dataq; +\item The driver callback handle the result and over. +\end{enumerate} + +Note: the driver MAY support both synchronous and asynchronous encryption. Then the performance +is poor in synchronous operation because frequent context switching and virtualization overhead. +The driver SHOULD by preference use asynchronous encryption. + +\paragraph{Crypto operation: AEAD operation}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: AEAD operation} + +\begin{lstlisting} +struct virtio_crypto_aead_para { + 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 { + le64 dst_data_addr; /* destination data guest physical address */ + le64 digest_result_addr; /* digest result guest physical address */ + /* + * in header guest physical address, See struct virtio_crypto_sym_crypt_op_inhdr + * above + */ + le64 inhdr_addr; +}; + +struct virtio_crypto_aead_output { + le64 iv_addr; /* iv guest physical address */ + le64 src_data_addr; /* source data guest physical address */ + le64 add_data_addr; /* additional auth data guest physical address */ +}; +struct virtio_crypto_aead_data_req { + struct virtio_crypto_aead_para parameter; + struct virtio_crypto_aead_input idata; + struct virtio_crypto_aead_output odata; +}; +\end{lstlisting} + +Both input and output parameters store the guest physical address (GPA) only so that +each data operation request only occupies one entry of the Vring descriptor table, +which improves the throughput of data transferring for AEAD crypto service. The +struct virtio_crypto_aead_para store the corresponding parameters, such as \field{src_data_len}. +The length and GPA can determine the specific content in the guest memory. + +\subparagraph{Driver Requirements: Crypto operation: AEAD encryption}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: AEAD operation / Driver Requirements: Crypto operation: AEAD encryption} + +Refer to the symmetric algorithms encryption operation. +The driver MUST set the \field{opcode} field to VIRTIO_CRYPTO_AEAD_ENCRYPT. + +\subparagraph{Device Requirements: Crypto operation: AEAD encryption}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: AEAD operation / Device Requirements: Crypto operation: AEAD encryption} + +Refer to the symmetric algorithms encryption operation. + +\subparagraph{Driver Requirements: Crypto operation: AEAD decryption}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: AEAD operation / Driver Requirements: Crypto operation: AEAD decryption} + +Refer to the symmetric algorithms encryption operation. +The driver MUST set the \field{opcode} field to VIRTIO_CRYPTO_AEAD_DECRYPT. + +\subparagraph{Device Requirements: Crypto operation: AEAD decryption}\label{sec:Device Types / Crypto Device / Device +Operation / Crypto operation / Crypto operation: AEAD operation / Device Requirements: Crypto operation: AEAD decryption} + +The device MUST verify and return the verify result to the driver. +If the verify result is not correct, VIRTIO_CRYPTO_OP_BADMSG (bad message) +MUST be returned the driver.