Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/812209/?format=api
{ "id": 812209, "url": "http://patchwork.ozlabs.org/api/patches/812209/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/patch/1505092362-10544-2-git-send-email-longpeng2@huawei.com/", "project": { "id": 14, "url": "http://patchwork.ozlabs.org/api/projects/14/?format=api", "name": "QEMU Development", "link_name": "qemu-devel", "list_id": "qemu-devel.nongnu.org", "list_email": "qemu-devel@nongnu.org", "web_url": "", "scm_url": "", "webscm_url": "", "list_archive_url": "", "list_archive_url_format": "", "commit_url_format": "" }, "msgid": "<1505092362-10544-2-git-send-email-longpeng2@huawei.com>", "list_archive_url": null, "date": "2017-09-11T01:12:41", "name": "[REPOST,v19,1/2] virtio-crypto: Add virtio crypto device specification", "commit_ref": null, "pull_url": null, "state": "new", "archived": false, "hash": "79fb5da18247432c67246f8dca7aac28e8d8bccb", "submitter": { "id": 69776, "url": "http://patchwork.ozlabs.org/api/people/69776/?format=api", "name": "Longpeng (Mike, Cloud Infrastructure Service Product Dept.)", "email": "longpeng2@huawei.com" }, "delegate": null, "mbox": "http://patchwork.ozlabs.org/project/qemu-devel/patch/1505092362-10544-2-git-send-email-longpeng2@huawei.com/mbox/", "series": [ { "id": 2427, "url": "http://patchwork.ozlabs.org/api/series/2427/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/list/?series=2427", "date": "2017-09-11T01:12:42", "name": "virtio-crypto: virtio crypto device specification", "version": 19, "mbox": "http://patchwork.ozlabs.org/series/2427/mbox/" } ], "comments": "http://patchwork.ozlabs.org/api/patches/812209/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/812209/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org>", "X-Original-To": "incoming@patchwork.ozlabs.org", "Delivered-To": "patchwork-incoming@bilbo.ozlabs.org", "Authentication-Results": "ozlabs.org;\n\tspf=pass (mailfrom) smtp.mailfrom=nongnu.org\n\t(client-ip=2001:4830:134:3::11; helo=lists.gnu.org;\n\tenvelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n\treceiver=<UNKNOWN>)", "Received": [ "from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11])\n\t(using TLSv1 with cipher AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby ozlabs.org (Postfix) with ESMTPS id 3xr9CJ6Ch7z9s4s\n\tfor <incoming@patchwork.ozlabs.org>;\n\tMon, 11 Sep 2017 11:22:36 +1000 (AEST)", "from localhost ([::1]:54876 helo=lists.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.71) (envelope-from\n\t<qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org>)\n\tid 1drDQm-0004M8-Ca\n\tfor incoming@patchwork.ozlabs.org; Sun, 10 Sep 2017 21:22:35 -0400", "from eggs.gnu.org ([2001:4830:134:3::10]:37625)\n\tby lists.gnu.org with esmtp (Exim 4.71)\n\t(envelope-from <longpeng2@huawei.com>) id 1drDLE-0000Ko-HM\n\tfor qemu-devel@nongnu.org; Sun, 10 Sep 2017 21:16:56 -0400", "from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)\n\t(envelope-from <longpeng2@huawei.com>) id 1drDL8-00074G-A0\n\tfor qemu-devel@nongnu.org; Sun, 10 Sep 2017 21:16:48 -0400", "from szxga05-in.huawei.com ([45.249.212.191]:2260)\n\tby eggs.gnu.org with esmtps (TLS1.0:RSA_ARCFOUR_SHA1:16) (Exim 4.71)\n\t(envelope-from <longpeng2@huawei.com>) id 1drDL6-0006xP-L7\n\tfor qemu-devel@nongnu.org; Sun, 10 Sep 2017 21:16:42 -0400", "from 172.30.72.60 (EHLO DGGEMS406-HUB.china.huawei.com)\n\t([172.30.72.60])\n\tby dggrg05-dlp.huawei.com (MOS 4.4.6-GA FastPath queued)\n\twith ESMTP id DHB06301; Mon, 11 Sep 2017 09:13:00 +0800 (CST)", "from localhost (10.177.246.209) by DGGEMS406-HUB.china.huawei.com\n\t(10.3.19.206) with Microsoft SMTP Server id 14.3.301.0;\n\tMon, 11 Sep 2017 09:12:52 +0800" ], "From": "\"Longpeng(Mike)\" <longpeng2@huawei.com>", "To": "<qemu-devel@nongnu.org>, <virtio-dev@lists.oasis-open.org>", "Date": "Mon, 11 Sep 2017 09:12:41 +0800", "Message-ID": "<1505092362-10544-2-git-send-email-longpeng2@huawei.com>", "X-Mailer": "git-send-email 1.8.4.msysgit.0", "In-Reply-To": "<1505092362-10544-1-git-send-email-longpeng2@huawei.com>", "References": "<1505092362-10544-1-git-send-email-longpeng2@huawei.com>", "MIME-Version": "1.0", "Content-Type": "text/plain", "X-Originating-IP": "[10.177.246.209]", "X-CFilter-Loop": "Reflected", "X-Mirapoint-Virus-RAPID-Raw": "score=unknown(0),\n\trefid=str=0001.0A0B0201.59B5E31D.0024, ss=1, re=0.000, recu=0.000,\n\treip=0.000, cl=1, cld=1, fgs=0, ip=0.0.0.0,\n\tso=2014-11-16 11:51:01, dmn=2013-03-21 17:37:32", "X-Mirapoint-Loop-Id": "6659636d608d18bb0d86d6c3914822c4", "X-detected-operating-system": "by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic]\n\t[fuzzy]", "X-Received-From": "45.249.212.191", "Subject": "[Qemu-devel] [PATCH REPOST v19 1/2] virtio-crypto: Add virtio\n\tcrypto device specification", "X-BeenThere": "qemu-devel@nongnu.org", "X-Mailman-Version": "2.1.21", "Precedence": "list", "List-Id": "<qemu-devel.nongnu.org>", "List-Unsubscribe": "<https://lists.nongnu.org/mailman/options/qemu-devel>,\n\t<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>", "List-Archive": "<http://lists.nongnu.org/archive/html/qemu-devel/>", "List-Post": "<mailto:qemu-devel@nongnu.org>", "List-Help": "<mailto:qemu-devel-request@nongnu.org?subject=help>", "List-Subscribe": "<https://lists.nongnu.org/mailman/listinfo/qemu-devel>,\n\t<mailto:qemu-devel-request@nongnu.org?subject=subscribe>", "Cc": "weidong.huang@huawei.com, mst@redhat.com, jasowang@redhat.com,\n\tjohn.griffin@intel.com, Varun.Sethi@freescale.com,\n\tdenglingli@chinamobile.com, arei.gonglei@hotmail.com,\n\tagraf@suse.de, arei.gonglei@huawei.com,\n\t\"Longpeng\\(Mike\\)\" <longpeng2@huawei.com>,\n\tvincent.jardin@6wind.com, Ola.Liljedahl@arm.com,\n\tluonengjun@huawei.com, xin.zeng@intel.com, liang.j.ma@intel.com,\n\tstefanha@redhat.com, Jani.Kokkonen@huawei.com,\n\tpasic@linux.vnet.ibm.com, brian.a.keating@intel.com,\n\twangxinxin.wang@huawei.com, cohuck@redhat.com, mike.caraman@nxp.com", "Errors-To": "qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org", "Sender": "\"Qemu-devel\"\n\t<qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org>" }, "content": "From: Gonglei <arei.gonglei@huawei.com>\n\nThe virtio crypto device is a virtual crypto device (ie. hardware\ncrypto accelerator card). Currently, the virtio crypto device provides\nthe following crypto services: CIPHER, MAC, HASH, and AEAD.\n\nIn this patch, CIPHER, MAC, HASH, AEAD services are introduced.\n\nVIRTIO-153\n\nSigned-off-by: Gonglei <arei.gonglei@huawei.com>\nSigned-off-by: Longpeng(Mike) <longpeng2@huawei.com>\n---\n acknowledgements.tex | 3 +\n content.tex | 2 +\n virtio-crypto.tex | 1479 ++++++++++++++++++++++++++++++++++++++++++++++++++\n 3 files changed, 1484 insertions(+)\n create mode 100644 virtio-crypto.tex", "diff": "diff --git a/acknowledgements.tex b/acknowledgements.tex\nindex 6c86d12..c4b6844 100644\n--- a/acknowledgements.tex\n+++ b/acknowledgements.tex\n@@ -26,6 +26,8 @@ Sasha Levin,\tOracle\t\\newline\n Sergey Tverdyshev,\tThales e-Security\t\\newline\n Stefan Hajnoczi,\tRed Hat\t\\newline\n Tom Lyon,\tSamya Systems, Inc.\t\\newline\n+Lei Gong,\tHuawei\t\\newline\n+Peng Long,\tHuawei\t\\newline\n \\end{oasistitlesection}\n \n The following non-members have provided valuable feedback on this\n@@ -43,4 +45,5 @@ Laura Novich, Red Hat\t\\newline\n Patrick Durusau,\tTechnical Advisory Board, OASIS\t\\newline\n Thomas Huth,\tIBM\t\\newline\n Yan Vugenfirer, Red Hat / Daynix\t\\newline\n+Halil Pasic,\tIBM\t\\newline\n \\end{oasistitlesection}\ndiff --git a/content.tex b/content.tex\nindex d989d98..7710f8c 100644\n--- a/content.tex\n+++ b/content.tex\n@@ -5641,6 +5641,8 @@ descriptor for the \\field{sense_len}, \\field{residual},\n \\field{status_qualifier}, \\field{status}, \\field{response} and\n \\field{sense} fields.\n \n+\\input{virtio-crypto.tex}\n+\n \\chapter{Reserved Feature Bits}\\label{sec:Reserved Feature Bits}\n \n Currently there are three device-independent feature bits defined:\ndiff --git a/virtio-crypto.tex b/virtio-crypto.tex\nnew file mode 100644\nindex 0000000..1e75cbc\n--- /dev/null\n+++ b/virtio-crypto.tex\n@@ -0,0 +1,1479 @@\n+\\section{Crypto Device}\\label{sec:Device Types / Crypto Device}\n+\n+The virtio crypto device is a virtual cryptography device as well as a\n+virtual cryptographic accelerator. The virtio crypto device provides the\n+following crypto services: CIPHER, MAC, HASH, and AEAD. Virtio crypto\n+devices have a single control queue and at least one data queue. Crypto\n+operation requests are placed into a data queue, and serviced by the\n+device. Some crypto operation requests are only valid in the context of a\n+session. The role of the control queue is facilitating control operation\n+requests. Sessions management is realized with control operation\n+requests.\n+\n+\\subsection{Device ID}\\label{sec:Device Types / Crypto Device / Device ID}\n+\n+20\n+\n+\\subsection{Virtqueues}\\label{sec:Device Types / Crypto Device / Virtqueues}\n+\n+\\begin{description}\n+\\item[0] dataq1\n+\\item[\\ldots]\n+\\item[N-1] dataqN\n+\\item[N] controlq\n+\\end{description}\n+\n+N is set by \\field{max_dataqueues}.\n+\n+\\subsection{Feature bits}\\label{sec:Device Types / Crypto Device / Feature bits}\n+\n+\\begin{description}\n+\\item VIRTIO_CRYPTO_F_MUX_MODE (0) multiplexing mode is available.\n+\\item VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE (1) stateless mode is available for CIPHER service.\n+\\item VIRTIO_CRYPTO_F_HASH_STATELESS_MODE (2) stateless mode is available for HASH service.\n+\\item VIRTIO_CRYPTO_F_MAC_STATELESS_MODE (3) stateless mode is available for MAC service.\n+\\item VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE (4) stateless mode is available for AEAD service.\n+\\end{description}\n+\n+\\subsubsection{Feature bit requirements}\\label{sec:Device Types / Crypto Device / Feature bits}\n+\n+Some crypto feature bits require other crypto feature bits\n+(see \\ref{drivernormative:Basic Facilities of a Virtio Device / Feature Bits}):\n+\n+\\begin{description}\n+\\item[VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_MUX_MODE.\n+\\item[VIRTIO_CRYPTO_F_HASH_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_MUX_MODE.\n+\\item[VIRTIO_CRYPTO_F_MAC_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_MUX_MODE.\n+\\item[VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE] Requires VIRTIO_CRYPTO_F_MUX_MODE.\n+\\end{description}\n+\n+\\subsection{Supported crypto services}\\label{sec:Device Types / Crypto Device / Supported crypto services}\n+\n+The following crypto services are defined:\n+\n+\\begin{lstlisting}\n+/* CIPHER service */\n+#define VIRTIO_CRYPTO_SERVICE_CIPHER 0\n+/* HASH service */\n+#define VIRTIO_CRYPTO_SERVICE_HASH 1\n+/* MAC (Message Authentication Codes) service */\n+#define VIRTIO_CRYPTO_SERVICE_MAC 2\n+/* AEAD (Authenticated Encryption with Associated Data) service */\n+#define VIRTIO_CRYPTO_SERVICE_AEAD 3\n+\\end{lstlisting}\n+\n+The above constants designate bits used to indicate the which of crypto services are\n+offered by the device as described in, see \\ref{sec:Device Types / Crypto Device / Device configuration layout}.\n+\n+\\subsubsection{CIPHER services}\\label{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}\n+\n+The following CIPHER algorithms are defined:\n+\n+\\begin{lstlisting}\n+#define VIRTIO_CRYPTO_NO_CIPHER 0\n+#define VIRTIO_CRYPTO_CIPHER_ARC4 1\n+#define VIRTIO_CRYPTO_CIPHER_AES_ECB 2\n+#define VIRTIO_CRYPTO_CIPHER_AES_CBC 3\n+#define VIRTIO_CRYPTO_CIPHER_AES_CTR 4\n+#define VIRTIO_CRYPTO_CIPHER_DES_ECB 5\n+#define VIRTIO_CRYPTO_CIPHER_DES_CBC 6\n+#define VIRTIO_CRYPTO_CIPHER_3DES_ECB 7\n+#define VIRTIO_CRYPTO_CIPHER_3DES_CBC 8\n+#define VIRTIO_CRYPTO_CIPHER_3DES_CTR 9\n+#define VIRTIO_CRYPTO_CIPHER_KASUMI_F8 10\n+#define VIRTIO_CRYPTO_CIPHER_SNOW3G_UEA2 11\n+#define VIRTIO_CRYPTO_CIPHER_AES_F8 12\n+#define VIRTIO_CRYPTO_CIPHER_AES_XTS 13\n+#define VIRTIO_CRYPTO_CIPHER_ZUC_EEA3 14\n+\\end{lstlisting}\n+\n+The above constants have two usages:\n+\\begin{enumerate}\n+\\item As bit numbers, used to tell the driver which CIPHER algorithms\n+are supported by the device, see \\ref{sec:Device Types / Crypto Device / Device configuration layout}.\n+\\item As values, used to tell the device which CIPHER algorithm\n+a crypto request from the driver requires, see \\ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation}.\n+\\end{enumerate}\n+\n+\\subsubsection{HASH services}\\label{sec:Device Types / Crypto Device / Supported crypto services / HASH services}\n+\n+The following HASH algorithms are defined:\n+\n+\\begin{lstlisting}\n+#define VIRTIO_CRYPTO_NO_HASH 0\n+#define VIRTIO_CRYPTO_HASH_MD5 1\n+#define VIRTIO_CRYPTO_HASH_SHA1 2\n+#define VIRTIO_CRYPTO_HASH_SHA_224 3\n+#define VIRTIO_CRYPTO_HASH_SHA_256 4\n+#define VIRTIO_CRYPTO_HASH_SHA_384 5\n+#define VIRTIO_CRYPTO_HASH_SHA_512 6\n+#define VIRTIO_CRYPTO_HASH_SHA3_224 7\n+#define VIRTIO_CRYPTO_HASH_SHA3_256 8\n+#define VIRTIO_CRYPTO_HASH_SHA3_384 9\n+#define VIRTIO_CRYPTO_HASH_SHA3_512 10\n+#define VIRTIO_CRYPTO_HASH_SHA3_SHAKE128 11\n+#define VIRTIO_CRYPTO_HASH_SHA3_SHAKE256 12\n+\\end{lstlisting}\n+\n+The above constants have two usages:\n+\\begin{enumerate}\n+\\item As bit numbers, used to tell the driver which HASH algorithms\n+are supported by the device, see \\ref{sec:Device Types / Crypto Device / Device configuration layout}.\n+\\item As values, used to tell the device which HASH algorithm\n+a crypto request from the driver requires, see \\ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation}.\n+\\end{enumerate}\n+\n+\\subsubsection{MAC services}\\label{sec:Device Types / Crypto Device / Supported crypto services / MAC services}\n+\n+The following MAC algorithms are defined:\n+\n+\\begin{lstlisting}\n+#define VIRTIO_CRYPTO_NO_MAC 0\n+#define VIRTIO_CRYPTO_MAC_HMAC_MD5 1\n+#define VIRTIO_CRYPTO_MAC_HMAC_SHA1 2\n+#define VIRTIO_CRYPTO_MAC_HMAC_SHA_224 3\n+#define VIRTIO_CRYPTO_MAC_HMAC_SHA_256 4\n+#define VIRTIO_CRYPTO_MAC_HMAC_SHA_384 5\n+#define VIRTIO_CRYPTO_MAC_HMAC_SHA_512 6\n+#define VIRTIO_CRYPTO_MAC_CMAC_3DES 25\n+#define VIRTIO_CRYPTO_MAC_CMAC_AES 26\n+#define VIRTIO_CRYPTO_MAC_KASUMI_F9 27\n+#define VIRTIO_CRYPTO_MAC_SNOW3G_UIA2 28\n+#define VIRTIO_CRYPTO_MAC_GMAC_AES 41\n+#define VIRTIO_CRYPTO_MAC_GMAC_TWOFISH 42\n+#define VIRTIO_CRYPTO_MAC_CBCMAC_AES 49\n+#define VIRTIO_CRYPTO_MAC_CBCMAC_KASUMI_F9 50\n+#define VIRTIO_CRYPTO_MAC_XCBC_AES 53\n+#define VIRTIO_CRYPTO_MAC_ZUC_EIA3 54\n+\\end{lstlisting}\n+\n+The above constants have two usages:\n+\\begin{enumerate}\n+\\item As bit numbers, used to tell the driver which MAC algorithms\n+are supported by the device, see \\ref{sec:Device Types / Crypto Device / Device configuration layout}.\n+\\item As values, used to tell the device which MAC algorithm\n+a crypto request from the driver requires, see \\ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation}.\n+\\end{enumerate}\n+\n+\\subsubsection{AEAD services}\\label{sec:Device Types / Crypto Device / Supported crypto services / AEAD services}\n+\n+The following AEAD algorithms are defined:\n+\n+\\begin{lstlisting}\n+#define VIRTIO_CRYPTO_NO_AEAD 0\n+#define VIRTIO_CRYPTO_AEAD_GCM 1\n+#define VIRTIO_CRYPTO_AEAD_CCM 2\n+#define VIRTIO_CRYPTO_AEAD_CHACHA20_POLY1305 3\n+\\end{lstlisting}\n+\n+The above constants have two usages:\n+\\begin{enumerate}\n+\\item As bit numbers, used to tell the driver which AEAD algorithms\n+are supported by the device, see \\ref{sec:Device Types / Crypto Device / Device configuration layout}.\n+\\item As values, used to tell the device what AEAD algorithm\n+a crypto request from the driver requires, see \\ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation}.\n+\\end{enumerate}\n+\n+\\subsection{Device configuration layout}\\label{sec:Device Types / Crypto Device / Device configuration layout}\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_config {\n+ le32 status;\n+ le32 max_dataqueues;\n+ le32 crypto_services;\n+ /* Detailed algorithms mask */\n+ le32 cipher_algo_l;\n+ le32 cipher_algo_h;\n+ le32 hash_algo;\n+ le32 mac_algo_l;\n+ le32 mac_algo_h;\n+ le32 aead_algo;\n+ /* Maximum length of cipher key in bytes */\n+ le32 max_cipher_key_len;\n+ /* Maximum length of authenticated key in bytes */\n+ le32 max_auth_key_len;\n+ le32 reserved;\n+ /* Maximum size of each crypto request's content in bytes */\n+ le64 max_size;\n+};\n+\\end{lstlisting}\n+\n+\\begin{description}\n+\\item[\\field{status}] is used to show whether the device is ready to work or\n+ not, it can be either zero or have one or more flags. Only one read-only\n+\tbit (for the driver) is currently defined for the \\field{status} field: VIRTIO_CRYPTO_S_HW_READY:\n+\\begin{lstlisting}\n+#define VIRTIO_CRYPTO_S_HW_READY (1 << 0)\n+\\end{lstlisting}\n+\n+\\item[\\field{max_dataqueues}] is the maximum number of data virtqueues exposed by\n+ the device. The driver MAY use only one data queue,\n+ or it can use more to achieve better performance.\n+\n+\\item[\\field{crypto_services}] crypto service offered, see \\ref{sec:Device Types / Crypto Device / Supported crypto services}.\n+\n+\\item[\\field{cipher_algo_l}] CIPHER algorithms bits 0-31, see \\ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.\n+\n+\\item[\\field{cipher_algo_h}] CIPHER algorithms bits 32-63, see \\ref{sec:Device Types / Crypto Device / Supported crypto services / CIPHER services}.\n+\n+\\item[\\field{hash_algo}] HASH algorithms bits, see \\ref{sec:Device Types / Crypto Device / Supported crypto services / HASH services}.\n+\n+\\item[\\field{mac_algo_l}] MAC algorithms bits 0-31, see \\ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.\n+\n+\\item[\\field{mac_algo_h}] MAC algorithms bits 32-63, see \\ref{sec:Device Types / Crypto Device / Supported crypto services / MAC services}.\n+\n+\\item[\\field{aead_algo}] AEAD algorithms bits, see \\ref{sec:Device Types / Crypto Device / Supported crypto services / AEAD services}.\n+\n+\\item[\\field{max_cipher_key_len}] is the maximum length of cipher key supported by the device.\n+\n+\\item[\\field{max_auth_key_len}] is the maximum length of authenticated key supported by the device.\n+\n+\\item[\\field{reserved}] is reserved for future use.\n+\n+\\item[\\field{max_size}] is the maximum size of each crypto request's content supported by the device\n+\\end{description}\n+\n+\\begin{note}\n+Unless explicitly stated otherwise all lengths and sizes are in bytes.\n+\\end{note}\n+\n+\\devicenormative{\\subsubsection}{Device configuration layout}{Device Types / Crypto Device / Device configuration layout}\n+\n+\\begin{itemize*}\n+\\item The device MUST set \\field{max_dataqueues} to between 1 and 65535 inclusive.\n+\\item The device MUST set the \\field{status} flag based on the status of the crypto\n+ accelerator, Non-valid flags MUST NOT be set.\n+\\item The device MUST accept and handle requests after \\field{status} is set to VIRTIO_CRYPTO_S_HW_READY.\n+\\item The device MUST set \\field{crypto_services} based on the crypto services the device offers.\n+\\item The device MUST set detailed algorithms masks for each service advertised by \\field{crypto_services}.\n+ The device MUST NOT set the not defined algorithms bits.\n+\\item The device MUST set \\field{max_size} to show the maximum size of crypto request the device supports.\n+\\item The device MUST set \\field{max_cipher_key_len} to show the maximum length of cipher key if the\n+ device supports CIPHER service.\n+\\item The device MUST set \\field{max_auth_key_len} to show the maximum length of authenticated key if\n+ the device supports MAC service.\n+\\end{itemize*}\n+\n+\\drivernormative{\\subsubsection}{Device configuration layout}{Device Types / Crypto Device / Device configuration layout}\n+\n+\\begin{itemize*}\n+\\item The driver MUST read the ready \\field{status} from the bottom bit of status to check whether the\n+ crypto accelerator is ready or not, and the driver MUST reread it after device reset.\n+\\item The driver MUST NOT transmit any requests to the device if the ready \\field{status} is not set.\n+\\item The driver MUST read \\field{max_dataqueues} field to discover the number of data queues the device supports.\n+\\item The driver MUST read \\field{crypto_services} field to discover which services the device is able to offer.\n+\\item The driver SHOULD ignore the not defined algorithms bits.\n+\\item The driver MUST read the detailed algorithms fields based on \\field{crypto_services} field.\n+\\item The driver SHOULD read \\field{max_size} to discover the maximum size of crypto request the device supports.\n+\\item The driver SHOULD read \\field{max_cipher_key_len} to discover the maximum length of cipher key\n+ the device supports.\n+\\item The driver SHOULD read \\field{max_auth_key_len} to discover the maximum length of authenticated\n+ key the device supports.\n+\\end{itemize*}\n+\n+\\subsection{Device Initialization}\\label{sec:Device Types / Crypto Device / Device Initialization}\n+\n+\\drivernormative{\\subsubsection}{Device Initialization}{Device Types / Crypto Device / Device Initialization}\n+\n+\\begin{itemize*}\n+\\item The driver MUST identify and initialize all virtqueues.\n+\\item The driver MUST read the supported crypto services from bits of \\field{crypto_services}.\n+\\item The driver MUST read the supported algorithms based on \\field{crypto_services} field.\n+\\end{itemize*}\n+\n+\\subsection{Device Operation}\\label{sec:Device Types / Crypto Device / Device Operation}\n+\n+Requests can be transmitted by placing them in the controlq or dataq.\n+Requests consist of a queue-type specific header specifying among\n+others the operation, and an operation specific payload.\n+The payload is generally composed of operation parameters, output data, and input data.\n+Operation parameters are algorithm-specific parameters, output data is the\n+data that should be utilized in operations, and input data is equal to\n+\"operation result + result data\".\n+\n+The device can support both session mode (See \\ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation}) and stateless mode.\n+In stateless mode all operation parameters are supplied as a part\n+of each request, while in session mode, some or all operation parameters\n+are managed within the session. Stateless mode is guarded by\n+feature bits 0-4 on a service level. If stateless mode is negotiated\n+for a service, the service is available both in session and\n+stateless mode; otherwise it's only available in session mode.\n+\n+The device can set the operation status as follows:\n+\n+\\begin{lstlisting}\n+enum VIRTIO_CRYPTO_STATUS {\n+ VIRTIO_CRYPTO_OK = 0,\n+ VIRTIO_CRYPTO_ERR = 1,\n+ VIRTIO_CRYPTO_BADMSG = 2,\n+ VIRTIO_CRYPTO_NOTSUPP = 3,\n+ VIRTIO_CRYPTO_INVSESS = 4,\n+ VIRTIO_CRYPTO_NOSPC = 5,\n+ VIRTIO_CRYPTO_MAX\n+};\n+\\end{lstlisting}\n+\n+\\begin{itemize*}\n+\\item VIRTIO_CRYPTO_OK: success.\n+\\item VIRTIO_CRYPTO_BADMSG: authentication failed (only when AEAD decryption).\n+\\item VIRTIO_CRYPTO_NOTSUPP: operation or algorithm is unsupported.\n+\\item VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto operations.\n+\\item VIRTIO_CRYPTO_NOSPC: no free session ID (only when the VIRTIO_CRYPTO_F_MUX_MODE\n+ feature bit is negotiated).\n+\\item VIRTIO_CRYPTO_ERR: any failure not mentioned above occurs.\n+\\end{itemize*}\n+\n+\\subsubsection{Control Virtqueue}\\label{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}\n+\n+The driver uses the control virtqueue to send control commands to the\n+device, such as session operations (See \\ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation}).\n+\n+The header for controlq is of the following form:\n+\\begin{lstlisting}\n+#define VIRTIO_CRYPTO_OPCODE(service, op) (((service) << 8) | (op))\n+\n+struct virtio_crypto_ctrl_header {\n+#define VIRTIO_CRYPTO_CIPHER_CREATE_SESSION \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_CIPHER, 0x02)\n+#define VIRTIO_CRYPTO_CIPHER_DESTROY_SESSION \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_CIPHER, 0x03)\n+#define VIRTIO_CRYPTO_HASH_CREATE_SESSION \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_HASH, 0x02)\n+#define VIRTIO_CRYPTO_HASH_DESTROY_SESSION \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_HASH, 0x03)\n+#define VIRTIO_CRYPTO_MAC_CREATE_SESSION \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_MAC, 0x02)\n+#define VIRTIO_CRYPTO_MAC_DESTROY_SESSION \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_MAC, 0x03)\n+#define VIRTIO_CRYPTO_AEAD_CREATE_SESSION \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_AEAD, 0x02)\n+#define VIRTIO_CRYPTO_AEAD_DESTROY_SESSION \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_AEAD, 0x03)\n+ le32 opcode;\n+ /* algo should be service-specific algorithms */\n+ le32 algo;\n+ le32 flag;\n+ /* data virtqueue id */\n+ le32 queue_id;\n+};\n+\\end{lstlisting}\n+\n+The format of the controlq request depends on the VIRTIO_CRYPTO_F_MUX_MODE feature bit:\n+\n+\\begin{itemize*}\n+\\item If the VIRTIO_CRYPTO_F_MUX_MODE feature bit is NOT negotiated the controlq request is\n+ a fixed-size structure of form:\n+\\begin{lstlisting}\n+struct virtio_crypto_op_ctrl_req {\n+ struct virtio_crypto_ctrl_header header;\n+\n+ union {\n+ struct virtio_crypto_sym_create_session_req sym_create_session;\n+ struct virtio_crypto_hash_create_session_req hash_create_session;\n+ struct virtio_crypto_mac_create_session_req mac_create_session;\n+ struct virtio_crypto_aead_create_session_req aead_create_session;\n+ struct virtio_crypto_destroy_session_req destroy_session;\n+ } u;\n+};\n+\\end{lstlisting}\n+The header is the general header, and the union is of the algorithm-specific type or the\n+virtio_crypto_destroy_session_req structure, which is set by the driver. All the properties\n+in the union are shown as follows.\n+\n+\\item If the VIRTIO_CRYPTO_F_MUX_MODE feature bit is negotiated the controlq request is composed\n+ of two parts, the additional paramenters are preceded by the general header.\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_op_ctrl_req_mux {\n+ struct virtio_crypto_ctrl_header header;\n+\n+ /* additional paramenter */\n+ u8 additional_para[addl_para_len];\n+};\n+\\end{lstlisting}\n+\n+The additional paramenters are stored in a virtio_crypto_destroy_session_req structure or\n+in a algorithm-specific structure:\n+\\begin{itemize*}\n+\\item struct virtio_crypto_sym_create_session_req\n+\\item struct virtio_crypto_hash_create_session_req\n+\\item struct virtio_crypto_mac_create_session_req\n+\\item struct virtio_crypto_aead_create_session_req\n+\\end{itemize*}\n+All of the structures above are shown as follows.\n+\\end{itemize*}\n+\n+\\paragraph{Session operation}\\label{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation}\n+\n+The session is a\n+handle which describes the cryptographic parameters to be applied to\n+a number of buffers.\n+\n+The following structure stores the result of session creation set by the device:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_session_input {\n+ /* Device-writable part */\n+ le64 session_id;\n+ le32 status;\n+ le32 padding;\n+};\n+\\end{lstlisting}\n+\n+A request to destroy a session includes the following information:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_destroy_session_req {\n+ /* Device-readable part */\n+ le64 session_id;\n+ /* Device-writable part */\n+ le32 status;\n+ le32 padding;\n+};\n+\\end{lstlisting}\n+\n+\\subparagraph{Session operation: HASH session}\\label{sec:Device Types / Crypto Device / Device\n+Operation / Control Virtqueue / Session operation / Session operation: HASH session}\n+\n+HASH session requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_hash_session_para {\n+ /* See VIRTIO_CRYPTO_HASH_* above */\n+ le32 algo;\n+ /* hash result length */\n+ le32 hash_result_len;\n+};\n+struct virtio_crypto_hash_create_session_req {\n+ /* Device-readable part */\n+ struct virtio_crypto_hash_session_para para;\n+ /* Device-writable part */\n+ struct virtio_crypto_session_input input;\n+};\n+\\end{lstlisting}\n+\n+The information required by HASH session creation is stored in the virtio_crypto_hash_create_session_req\n+structure, including the hash parameters stored in \\field{para}. \\field{input} stores the result of this operation.\n+\n+\\subparagraph{Session operation: MAC session}\\label{sec:Device Types / Crypto Device / Device\n+Operation / Control Virtqueue / Session operation / Session operation: MAC session}\n+\n+MAC session requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_mac_session_para {\n+ /* See VIRTIO_CRYPTO_MAC_* above */\n+ le32 algo;\n+ /* hash result length */\n+ le32 hash_result_len;\n+ /* length of authenticated key */\n+ le32 auth_key_len;\n+ le32 padding;\n+};\n+\n+struct virtio_crypto_mac_create_session_req {\n+ /* Device-readable part */\n+ struct virtio_crypto_mac_session_para para;\n+ /* The authenticated key */\n+ u8 auth_key[auth_key_len];\n+\n+ /* Device-writable part */\n+ struct virtio_crypto_session_input input;\n+};\n+\\end{lstlisting}\n+\n+The information required by MAC session creation is stored in the virtio_crypto_mac_create_session_req\n+structure, including the mac parameters stored in \\field{para} and the authenticated key in \\field{auth_key}.\n+\\field{input} stores the result of this operation.\n+\n+\\subparagraph{Session operation: Symmetric algorithms session}\\label{sec:Device Types / Crypto Device / Device\n+Operation / Control Virtqueue / Session operation / Session operation: Symmetric algorithms session}\n+\n+The request of symmetric session includes two parts, CIPHER algorithms and chain\n+algorithms (chaining CIPHER and HASH/MAC).\n+\n+CIPHER session requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_cipher_session_para {\n+ /* See VIRTIO_CRYPTO_CIPHER* above */\n+ le32 algo;\n+ /* length of key */\n+ le32 keylen;\n+#define VIRTIO_CRYPTO_OP_ENCRYPT 1\n+#define VIRTIO_CRYPTO_OP_DECRYPT 2\n+ /* encryption or decryption */\n+ le32 op;\n+ le32 padding;\n+};\n+\n+struct virtio_crypto_cipher_session_req {\n+ /* Device-readable part */\n+ struct virtio_crypto_cipher_session_para para;\n+ /* The cipher key */\n+ u8 cipher_key[keylen];\n+\n+ /* Device-writable part */\n+ struct virtio_crypto_session_input input;\n+};\n+\\end{lstlisting}\n+\n+Algorithm chaining requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_alg_chain_session_para {\n+#define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_HASH_THEN_CIPHER 1\n+#define VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_CIPHER_THEN_HASH 2\n+ le32 alg_chain_order;\n+/* Plain hash */\n+#define VIRTIO_CRYPTO_SYM_HASH_MODE_PLAIN 1\n+/* Authenticated hash (mac) */\n+#define VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH 2\n+/* Nested hash */\n+#define VIRTIO_CRYPTO_SYM_HASH_MODE_NESTED 3\n+ le32 hash_mode;\n+ struct virtio_crypto_cipher_session_para cipher_param;\n+ union {\n+ struct virtio_crypto_hash_session_para hash_param;\n+ struct virtio_crypto_mac_session_para mac_param;\n+ } u;\n+ /* length of the additional authenticated data (AAD) in bytes */\n+ le32 aad_len;\n+ le32 padding;\n+};\n+\n+struct virtio_crypto_alg_chain_session_req {\n+ /* Device-readable part */\n+ struct virtio_crypto_alg_chain_session_para para;\n+ /* The cipher key */\n+ u8 cipher_key[keylen];\n+ /* The authenticated key */\n+ u8 auth_key[auth_key_len];\n+\n+ /* Device-writable part */\n+ struct virtio_crypto_session_input input;\n+};\n+\\end{lstlisting}\n+\n+Symmetric algorithm requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_sym_create_session_req {\n+ union {\n+ struct virtio_crypto_cipher_session_req cipher;\n+ struct virtio_crypto_alg_chain_session_req chain;\n+ } u;\n+\n+ /* Device-readable part */\n+\n+/* No operation */\n+#define VIRTIO_CRYPTO_SYM_OP_NONE 0\n+/* Cipher only operation on the data */\n+#define VIRTIO_CRYPTO_SYM_OP_CIPHER 1\n+/* Chain any cipher with any hash or mac operation. The order\n+ depends on the value of alg_chain_order param */\n+#define VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING 2\n+ le32 op_type;\n+ le32 padding;\n+};\n+\\end{lstlisting}\n+\n+The information required by symmetric algorithms session creation is stored in the\n+virtio_crypto_sym_create_session_req structure, including the symmetric operation\n+type in \\field{op_type} and the cipher parameters stored in \\field{cipher} or the\n+algorithm chaining paramenters in \\field{chain}.\n+\n+The driver can set the \\field{op_type} field in struct virtio_crypto_sym_create_session_req\n+as follows: VIRTIO_CRYPTO_SYM_OP_NONE: no operation; VIRTIO_CRYPTO_SYM_OP_CIPHER: Cipher only\n+operation on the data; VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING: Chain any cipher with any hash\n+or mac operation.\n+\n+\\subparagraph{Session operation: AEAD session}\\label{sec:Device Types / Crypto Device / Device\n+Operation / Control Virtqueue / Session operation / Session operation: AEAD session}\n+\n+AEAD session requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_aead_session_para {\n+ /* See VIRTIO_CRYPTO_AEAD_* above */\n+ le32 algo;\n+ /* length of key */\n+ le32 key_len;\n+ /* Authentication tag length */\n+ le32 tag_len;\n+ /* The length of the additional authenticated data (AAD) in bytes */\n+ le32 aad_len;\n+ /* encryption or decryption, See above VIRTIO_CRYPTO_OP_* */\n+ le32 op;\n+ le32 padding;\n+};\n+\n+struct virtio_crypto_aead_create_session_req {\n+ /* Device-readable part */\n+ struct virtio_crypto_aead_session_para para;\n+ u8 key[key_len];\n+\n+ /* Device-writeable part */\n+ struct virtio_crypto_session_input input;\n+};\n+\\end{lstlisting}\n+\n+The information required by AEAD session creation is stored in the virtio_crypto_aead_create_session_req\n+structure, including the aead parameters stored in \\field{para} and the cipher key in \\field{key}.\n+\\field{input} stores the result of this operation.\n+\n+\\drivernormative{\\subparagraph}{Session operation: create session}{Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: create session}\n+\n+\\begin{itemize*}\n+\\item The driver MUST set the control general header and the corresponding algorithm-specific structure.\n+ See \\ref{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue}.\n+\\item The driver MUST set the \\field{opcode} field based on service type: CIPHER, HASH, MAC, or AEAD.\n+\\item The driver MUST set the \\field{queue_id} field to show used dataq.\n+\\end{itemize*}\n+\n+\\devicenormative{\\subparagraph}{Session operation: create session}{Device Types / Crypto Device / Device\n+Operation / Control Virtqueue / Session operation / Session operation: create session}\n+\n+\\begin{itemize*}\n+\\item The device MUST use the corresponding algorithm-specific structure according to the\n+ \\field{opcode} in the control general header.\n+\\item The device MUST set the \\field{status} field to one of the following values of enum\n+ VIRTIO_CRYPTO_STATUS after finish a session creation:\n+\\begin{itemize*}\n+\\item VIRTIO_CRYPTO_OK if a session is created successfully.\n+\\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.\n+\\item VIRTIO_CRYPTO_NOSPC if no free session ID (only when the VIRTIO_CRYPTO_F_MUX_MODE\n+ feature bit is negotiated).\n+\\item VIRTIO_CRYPTO_ERR if failure not mentioned above occurs.\n+\\end{itemize*}\n+\\item The device MUST set the \\field{session_id} field to a unique session identifieronly\n+ if the status is set to VIRTIO_CRYPTO_OK.\n+\\end{itemize*}\n+\n+\\drivernormative{\\subparagraph}{Session operation: destroy session}{Device Types / Crypto Device / Device\n+Operation / Control Virtqueue / Session operation / Session operation: destroy session}\n+\n+\\begin{itemize*}\n+\\item The driver MUST set the \\field{opcode} field based on service type: CIPHER, HASH, MAC, or AEAD.\n+\\item The driver MUST set the \\field{session_id} to a valid value assigned by the device\n+ when the session was created.\n+\\end{itemize*}\n+\n+\\devicenormative{\\subparagraph}{Session operation: destroy session}{Device Types / Crypto Device / Device\n+Operation / Control Virtqueue / Session operation / Session operation: destroy session}\n+\n+\\begin{itemize*}\n+\\item The device MUST set the \\field{status} field to one of the following values of enum VIRTIO_CRYPTO_STATUS.\n+\\begin{itemize*}\n+\\item VIRTIO_CRYPTO_OK if a session is created successfully.\n+\\item VIRTIO_CRYPTO_ERR if any failure occurs.\n+\\end{itemize*}\n+\\end{itemize*}\n+\n+\\subsubsection{Data Virtqueue}\\label{sec:Device Types / Crypto Device / Device Operation / Data Virtqueue}\n+\n+The driver uses the data virtqueues to transmit crypto operation requests to the device,\n+and completes the crypto operations.\n+\n+The header for dataq is as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_op_header {\n+#define VIRTIO_CRYPTO_CIPHER_ENCRYPT \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_CIPHER, 0x00)\n+#define VIRTIO_CRYPTO_CIPHER_DECRYPT \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_CIPHER, 0x01)\n+#define VIRTIO_CRYPTO_HASH \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_HASH, 0x00)\n+#define VIRTIO_CRYPTO_MAC \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_MAC, 0x00)\n+#define VIRTIO_CRYPTO_AEAD_ENCRYPT \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_AEAD, 0x00)\n+#define VIRTIO_CRYPTO_AEAD_DECRYPT \\\n+ VIRTIO_CRYPTO_OPCODE(VIRTIO_CRYPTO_SERVICE_AEAD, 0x01)\n+ le32 opcode;\n+ /* algo should be service-specific algorithms */\n+ le32 algo;\n+ le64 session_id;\n+#define VIRTIO_CRYPTO_FLAG_SESSION_MODE 1\n+ /* control flag to control the request */\n+ le32 flag;\n+ le32 padding;\n+};\n+\\end{lstlisting}\n+\n+The format of the dataq request depends on the VIRTIO_CRYPTO_F_MUX_MODE feature bit:\n+\n+\\begin{itemize*}\n+\\item If VIRTIO_CRYPTO_F_MUX_MODE feature bit is NOT negotiated the dataq request is\n+ a fixed-size structure of form:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_op_data_req {\n+ struct virtio_crypto_op_header header;\n+\n+ union {\n+ struct virtio_crypto_sym_data_req sym_req;\n+ struct virtio_crypto_hash_data_req hash_req;\n+ struct virtio_crypto_mac_data_req mac_req;\n+ struct virtio_crypto_aead_data_req aead_req;\n+ } u;\n+};\n+\\end{lstlisting}\n+\n+The header is the general header, and the union is of the algorithm-specific type,\n+which is set by the driver. All the properties in the union are shown as follows.\n+\n+\\item If VIRTIO_CRYPTO_F_MUX_MODE feature bit is negotiated the dataq requests is\n+ composed of two parts, the additional paramenters are preceded by the general header:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_op_data_req_mux {\n+ struct virtio_crypto_op_header header;\n+\n+ /* additional paramenter of the operation */\n+ u8 additional_para[addl_para_len];\n+};\n+\\end{lstlisting}\n+\n+The additional paramenters are stored in a algorithm-specific structure:\n+\\begin{itemize*}\n+\\item struct virtio_crypto_sym_data_req\n+\\item struct virtio_crypto_hash_data_req\n+\\item struct virtio_crypto_mac_data_req\n+\\item struct virtio_crypto_aead_data_req\n+\\item struct virtio_crypto_sym_data_req_stateless\n+\\item struct virtio_crypto_hash_data_req_stateless\n+\\item struct virtio_crypto_mac_data_req_stateless\n+\\item struct virtio_crypto_aead_data_req_stateless\n+\\end{itemize*}\n+All of the structures above are shown as follows.\n+\\end{itemize*}\n+\n+There is a unified input header for all crypto services, is defined as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_inhdr {\n+ u8 status;\n+};\n+\\end{lstlisting}\n+\n+\\subsubsection{HASH Service Operation}\\label{sec:Device Types / Crypto Device / Device Operation / HASH Service Operation}\n+\n+Session mode HASH service requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_hash_para {\n+ /* length of source data */\n+ le32 src_data_len;\n+ /* hash result length */\n+ le32 hash_result_len;\n+};\n+\n+struct virtio_crypto_hash_data_req {\n+ /* Device-readable part */\n+ struct virtio_crypto_hash_para para;\n+ /* Source data */\n+ u8 src_data[src_data_len];\n+\n+ /* Device-writable part */\n+ /* Hash result data */\n+ u8 hash_result[hash_result_len];\n+ struct virtio_crypto_inhdr inhdr;\n+};\n+\\end{lstlisting}\n+\n+Each data request uses virtio_crypto_hash_data_req structure to store information\n+used to run the HASH operations.\n+\n+The information includes the hash parameters stored in \\field{para}, output data\n+and input data. The output data here includes the source data and the input data\n+includes the hash result data used to save the results of the HASH operations.\n+\\field{inhdr} stores the status of executing the HASH operations.\n+\n+Stateless mode HASH service requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_hash_para_statelesss {\n+ struct {\n+ /* See VIRTIO_CRYPTO_HASH_* above */\n+ le32 algo;\n+ } sess_para;\n+\n+ /* length of source data */\n+ le32 src_data_len;\n+ /* hash result length */\n+ le32 hash_result_len;\n+ le32 reserved;\n+};\n+struct virtio_crypto_hash_data_req_stateless {\n+ /* Device-readable part */\n+ struct virtio_crypto_hash_para_stateless para;\n+ /* Source data */\n+ u8 src_data[src_data_len];\n+\n+ /* Device-writable part */\n+ /* Hash result data */\n+ u8 hash_result[hash_result_len];\n+ struct virtio_crypto_inhdr inhdr;\n+};\n+\\end{lstlisting}\n+\n+\\drivernormative{\\paragraph}{HASH Service Operation}{Device Types / Crypto Device / Device Operation / HASH Service Operation}\n+\n+\\begin{itemize*}\n+\\item If the driver uses the session mode, then the driver MUST set \\field{session_id}\n+ in struct virtio_crypto_op_header to a valid value assigned by the device when the\n+\tsession was created.\n+\\item If the VIRTIO_CRYPTO_F_MUX_MODE feature bit is negotiated, the driver MUST use\n+ struct virtio_crypto_op_data_req_mux to wrap crypto requests. Otherwise, the driver\n+\tMUST use struct virtio_crypto_op_data_req.\n+\\item If the VIRTIO_CRYPTO_F_HASH_STATELESS_MODE feature bit is negotiated, 1) if the\n+ driver uses the stateless mode, then the driver MUST set the \\field{flag} field in\n+\tstruct virtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_STATELESS_MODE and MUST set the\n+\tfields in struct virtio_crypto_hash_para_stateless.sess_para, 2) if the driver uses\n+\tthe session mode, then the driver MUST set the \\field{flag} field in struct\n+\tvirtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_SESSION_MODE.\n+\\item The driver MUST set \\field{opcode} in struct virtio_crypto_op_header to VIRTIO_CRYPTO_HASH.\n+\\end{itemize*}\n+\n+\\devicenormative{\\paragraph}{HASH Service Operation}{Device Types / Crypto Device / Device Operation / HASH Service Operation}\n+\n+\\begin{itemize*}\n+\\item If the VIRTIO_CRYPTO_F_MUX_MODE feature bit is negotiated, the device MUST parse\n+ the struct virtio_crypto_op_data_req_mux for crypto requests. Otherwise, the device\n+\tMUST parse the struct virtio_crypto_op_data_req.\n+\\item The device MUST use the corresponding algorithm-specific structure according to\n+ the \\field{opcode} in the data general header.\n+\\item If the VIRTIO_CRYPTO_F_HASH_STATELESS_MODE feature bit is negotiated, the device\n+ MUST parse \\field{flag} field in struct virtio_crypto_op_header in order to decide\n+\twhich mode the driver uses.\n+\\item The device MUST copy the results of HASH operations in the hash_result[] if HASH\n+ operations success.\n+\\item The device MUST set \\field{status} in struct virtio_crypto_inhdr to one of the\n+ following values of enum VIRTIO_CRYPTO_STATUS:\n+\\begin{itemize*}\n+\\item VIRTIO_CRYPTO_OK if the operation success.\n+\\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.\n+\\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.\n+\\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.\n+\\end{itemize*}\n+\\end{itemize*}\n+\n+\\subsubsection{MAC Service Operation}\\label{sec:Device Types / Crypto Device / Device Operation / MAC Service Operation}\n+\n+Session mode MAC service requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_mac_para {\n+ struct virtio_crypto_hash_para hash;\n+};\n+\n+struct virtio_crypto_mac_data_req {\n+ /* Device-readable part */\n+ struct virtio_crypto_mac_para para;\n+ /* Source data */\n+ u8 src_data[src_data_len];\n+\n+ /* Device-writable part */\n+ /* Hash result data */\n+ u8 hash_result[hash_result_len];\n+ struct virtio_crypto_inhdr inhdr;\n+};\n+\\end{lstlisting}\n+\n+Each request uses the virtio_crypto_mac_data_req structure to store information\n+used to run the MAC operations.\n+\n+The information includes the hash parameters stored in \\field{para}, output data\n+and input data. The output data here includes the source data and the input data\n+includes the hash result data used to save the results of the MAC operations.\n+\\field{inhdr} stores the status of executing the MAC operations.\n+\n+Stateless mode MAC service requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_mac_para_stateless {\n+ struct {\n+ /* See VIRTIO_CRYPTO_MAC_* above */\n+ le32 algo;\n+ /* length of authenticated key */\n+ le32 auth_key_len;\n+ } sess_para;\n+\n+ /* length of source data */\n+ le32 src_data_len;\n+ /* hash result length */\n+ le32 hash_result_len;\n+};\n+\n+struct virtio_crypto_mac_data_req_stateless {\n+ /* Device-readable part */\n+ struct virtio_crypto_mac_para_stateless para;\n+ /* The authenticated key */\n+ u8 auth_key[auth_key_len];\n+ /* Source data */\n+ u8 src_data[src_data_len];\n+\n+ /* Device-writable part */\n+ /* Hash result data */\n+ u8 hash_result[hash_result_len];\n+ struct virtio_crypto_inhdr inhdr;\n+};\n+\\end{lstlisting}\n+\n+\\drivernormative{\\paragraph}{MAC Service Operation}{Device Types / Crypto Device / Device Operation / MAC Service Operation}\n+\n+\\begin{itemize*}\n+\\item If the driver uses the session mode, then the driver MUST set \\field{session_id}\n+ in struct virtio_crypto_op_header to a valid value assigned by the device when the\n+\tsession was created.\n+\\item If the VIRTIO_CRYPTO_F_MUX_MODE feature bit is negotiated, the driver MUST use\n+ struct virtio_crypto_op_data_req_mux to wrap crypto requests. Otherwise, the\n+\tdriver MUST use struct virtio_crypto_op_data_req.\n+\\item If the VIRTIO_CRYPTO_F_MAC_STATELESS_MODE feature bit is negotiated, 1) if the\n+ driver uses the stateless mode, then the driver MUST set the \\field{flag} field\n+\tin struct virtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_STATELESS_MODE and MUST\n+\tset the fields in struct virtio_crypto_mac_para_stateless.sess_para, 2) if the\n+\tdriver uses the session mode, then the driver MUST set the \\field{flag} field in\n+\tstruct virtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_SESSION_MODE.\n+\\item The driver MUST set \\field{opcode} in struct virtio_crypto_op_header to VIRTIO_CRYPTO_MAC.\n+\\end{itemize*}\n+\n+\\devicenormative{\\paragraph}{MAC Service Operation}{Device Types / Crypto Device / Device Operation / MAC Service Operation}\n+\n+\\begin{itemize*}\n+\\item If the VIRTIO_CRYPTO_F_MUX_MODE feature bit is negotiated, the device MUST parse\n+ the struct virtio_crypto_op_data_req_mux for crypto requests. Otherwise, the device\n+\tMUST parse the struct virtio_crypto_op_data_req.\n+\\item If the VIRTIO_CRYPTO_F_MAC_STATELESS_MODE feature bit is negotiated, the device\n+ MUST parse \\field{flag} field in struct virtio_crypto_op_header in order to decide\n+\twhich mode the driver uses.\n+\\item The device MUST copy the results of MAC operations in the hash_result[] if HASH\n+ operations success.\n+\\item The device MUST set \\field{status} in struct virtio_crypto_inhdr to one of the\n+ following values of enum VIRTIO_CRYPTO_STATUS:\n+\\begin{itemize*}\n+\\item VIRTIO_CRYPTO_OK if the operation success.\n+\\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.\n+\\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.\n+\\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.\n+\\end{itemize*}\n+\\end{itemize*}\n+\n+\\subsubsection{Symmetric algorithms Operation}\\label{sec:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation}\n+\n+Session mode CIPHER service requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_cipher_para {\n+ /*\n+ * Byte Length of valid IV/Counter data pointed to by the below iv data.\n+ *\n+ * For block ciphers in CBC or F8 mode, or for Kasumi in F8 mode, or for\n+ * SNOW3G in UEA2 mode, this is the length of the IV (which\n+ * must be the same as the block length of the cipher).\n+ * For block ciphers in CTR mode, this is the length of the counter\n+ * (which must be the same as the block length of the cipher).\n+ */\n+ le32 iv_len;\n+ /* length of source data */\n+ le32 src_data_len;\n+ /* length of destination data */\n+ le32 dst_data_len;\n+ le32 padding;\n+};\n+\n+struct virtio_crypto_cipher_data_req {\n+ /* Device-readable part */\n+ struct virtio_crypto_cipher_para para;\n+ /*\n+ * Initialization Vector or Counter data.\n+ *\n+ * For block ciphers in CBC or F8 mode, or for Kasumi in F8 mode, or for\n+ * SNOW3G in UEA2 mode, this is the Initialization Vector (IV)\n+ * value.\n+ * For block ciphers in CTR mode, this is the counter.\n+ * For AES-XTS, this is the 128bit tweak, i, from IEEE Std 1619-2007.\n+ *\n+ * The IV/Counter will be updated after every partial cryptographic\n+ * operation.\n+ */\n+ u8 iv[iv_len];\n+ /* Source data */\n+ u8 src_data[src_data_len];\n+\n+ /* Device-writable part */\n+ /* Destination data */\n+ u8 dst_data[dst_data_len];\n+ struct virtio_crypto_inhdr inhdr;\n+};\n+\\end{lstlisting}\n+\n+Session mode requests of algorithm chaining are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_alg_chain_data_para {\n+ le32 iv_len;\n+ /* Length of source data */\n+ le32 src_data_len;\n+ /* Length of destination data */\n+ le32 dst_data_len;\n+ /* Starting point for cipher processing in source data */\n+ le32 cipher_start_src_offset;\n+ /* Length of the source data that the cipher will be computed on */\n+ le32 len_to_cipher;\n+ /* Starting point for hash processing in source data */\n+ le32 hash_start_src_offset;\n+ /* Length of the source data that the hash will be computed on */\n+ le32 len_to_hash;\n+ /* Length of the additional auth data */\n+ le32 aad_len;\n+ /* Length of the hash result */\n+ le32 hash_result_len;\n+ le32 reserved;\n+};\n+\n+struct virtio_crypto_alg_chain_data_req {\n+ /* Device-readable part */\n+ struct virtio_crypto_alg_chain_data_para para;\n+ /* Initialization Vector or Counter data */\n+ u8 iv[iv_len];\n+ /* Source data */\n+ u8 src_data[src_data_len];\n+ /* Additional authenticated data if exists */\n+ u8 aad[aad_len];\n+\n+ /* Device-writable part */\n+ /* Destination data */\n+ u8 dst_data[dst_data_len];\n+ /* Hash result data */\n+ u8 hash_result[hash_result_len];\n+ struct virtio_crypto_inhdr inhdr;\n+};\n+\\end{lstlisting}\n+\n+Session mode requests of symmetric algorithm are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_sym_data_req {\n+ union {\n+ struct virtio_crypto_cipher_data_req cipher;\n+ struct virtio_crypto_alg_chain_data_req chain;\n+ } u;\n+\n+ /* Device-readable part */\n+\n+ /* See above VIRTIO_CRYPTO_SYM_OP_* */\n+ le32 op_type;\n+ le32 padding;\n+};\n+\\end{lstlisting}\n+\n+Each request uses the virtio_crypto_sym_data_req structure to store information\n+used to run the CIPHER operations.\n+\n+The information includes the cipher parameters stored in \\field{para}, output data\n+and input data. In the first virtio_crypto_cipher_para structure, \\field{iv_len}\n+specifies the length of the initialization vector or counter, \\field{src_data_len}\n+specifies the length of the source data, and \\field{dst_data_len} specifies the length\n+of the destination data. For plain CIPHER operations, the output data here includes\n+the IV/Counter data and source data, and the input data includes the destination data\n+used to save the results of the CIPHER operations.\n+\n+For algorithms chain, the output data here includes the IV/Counter data, source data\n+and additional authenticated data if exists. The input data includes both destination\n+data and hash result data used to store the results of the HASH/MAC operations.\n+\\field{inhdr} stores the status of executing the crypto operations.\n+\n+Stateless mode CIPHER service requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_cipher_para_stateless {\n+ struct {\n+ /* See VIRTIO_CRYPTO_CIPHER* above */\n+ le32 algo;\n+ /* length of key */\n+ le32 keylen;\n+\n+ /* See VIRTIO_CRYPTO_OP_* above */\n+ le32 op;\n+ } sess_para;\n+\n+ /*\n+ * Byte Length of valid IV/Counter data pointed to by the below iv data.\n+ */\n+ le32 iv_len;\n+ /* length of source data */\n+ le32 src_data_len;\n+ /* length of destination data */\n+ le32 dst_data_len;\n+};\n+\n+struct virtio_crypto_cipher_data_req_stateless {\n+ /* Device-readable part */\n+ struct virtio_crypto_cipher_para_stateless para;\n+ /* The cipher key */\n+ u8 cipher_key[keylen];\n+\n+ /* Initialization Vector or Counter data. */\n+ u8 iv[iv_len];\n+ /* Source data */\n+ u8 src_data[src_data_len];\n+\n+ /* Device-writable part */\n+ /* Destination data */\n+ u8 dst_data[dst_data_len];\n+ struct virtio_crypto_inhdr inhdr;\n+};\n+\\end{lstlisting}\n+\n+Stateless mode requests of algorithm chaining are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_alg_chain_data_para_stateless {\n+ struct {\n+ /* See VIRTIO_CRYPTO_SYM_ALG_CHAIN_ORDER_* above */\n+ le32 alg_chain_order;\n+ /* length of the additional authenticated data in bytes */\n+ le32 aad_len;\n+\n+ struct {\n+ /* See VIRTIO_CRYPTO_CIPHER* above */\n+ le32 algo;\n+ /* length of key */\n+ le32 keylen;\n+ /* See VIRTIO_CRYPTO_OP_* above */\n+ le32 op;\n+ } cipher;\n+\n+ struct {\n+ /* See VIRTIO_CRYPTO_HASH_* or VIRTIO_CRYPTO_MAC_* above */\n+ le32 algo;\n+ /* length of authenticated key */\n+ le32 auth_key_len;\n+ /* See VIRTIO_CRYPTO_SYM_HASH_MODE_* above */\n+ le32 hash_mode;\n+ } hash;\n+ } sess_para;\n+\n+ le32 iv_len;\n+ /* Length of source data */\n+ le32 src_data_len;\n+ /* Length of destination data */\n+ le32 dst_data_len;\n+ /* Starting point for cipher processing in source data */\n+ le32 cipher_start_src_offset;\n+ /* Length of the source data that the cipher will be computed on */\n+ le32 len_to_cipher;\n+ /* Starting point for hash processing in source data */\n+ le32 hash_start_src_offset;\n+ /* Length of the source data that the hash will be computed on */\n+ le32 len_to_hash;\n+ /* Length of the additional auth data */\n+ le32 aad_len;\n+ /* Length of the hash result */\n+ le32 hash_result_len;\n+ le32 reserved;\n+};\n+\n+struct virtio_crypto_alg_chain_data_req_stateless {\n+ /* Device-readable part */\n+ struct virtio_crypto_alg_chain_data_para_stateless para;\n+ /* The cipher key */\n+ u8 cipher_key[keylen];\n+ /* The auth key */\n+ u8 auth_key[auth_key_len];\n+ /* Initialization Vector or Counter data */\n+ u8 iv[iv_len];\n+ /* Additional authenticated data if exists */\n+ u8 aad[aad_len];\n+ /* Source data */\n+ u8 src_data[src_data_len];\n+\n+ /* Device-writable part */\n+ /* Destination data */\n+ u8 dst_data[dst_data_len];\n+ /* Hash result data */\n+ u8 hash_result[hash_result_len];\n+ struct virtio_crypto_inhdr inhdr;\n+};\n+\\end{lstlisting}\n+ * header + key + auth_key + iv + srd_data + aad + dst_data + hash_result\n+Stateless mode requests of symmetric algorithm are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_sym_data_req_stateless {\n+ union {\n+ struct virtio_crypto_cipher_data_req_stateless cipher;\n+ struct virtio_crypto_alg_chain_data_req_stateless chain;\n+ } u;\n+\n+ /* Device-readable part */\n+\n+ /* See above VIRTIO_CRYPTO_SYM_OP_* */\n+ le32 op_type;\n+ /* Data virtqueue id */\n+ uint32_t queue_id;\n+};\n+\\end{lstlisting}\n+\n+\\drivernormative{\\paragraph}{Symmetric algorithms Operation}{Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation}\n+\n+\\begin{itemize*}\n+\\item If the driver uses the session mode, then the driver MUST set \\field{session_id}\n+ in struct virtio_crypto_op_header to a valid value assigned by the device when the\n+\tsession was created.\n+\\item If the VIRTIO_CRYPTO_F_MUX_MODE feature bit is negotiated, the driver MUST use\n+ struct virtio_crypto_op_data_req_mux to wrap crypto requests. Otherwise, the driver\n+\tMUST use struct virtio_crypto_op_data_req.\n+\\item If the VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE feature bit is negotiated, 1) if the\n+ driver uses the stateless mode, then the driver MUST set the \\field{flag} field in\n+\tstruct virtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_STATELESS_MODE and MUST set the\n+\tfields in struct virtio_crypto_cipher_para_stateless.sess_para or struct\n+\tvirtio_crypto_alg_chain_data_para_stateless.sess_para, 2) if the driver uses the\n+\tsession mode, then the driver MUST set the \\field{flag} field in struct\n+\tvirtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_SESSION_MODE.\n+\\item The driver MUST set the \\field{opcode} field in struct virtio_crypto_op_header\n+ to VIRTIO_CRYPTO_CIPHER_ENCRYPT or VIRTIO_CRYPTO_CIPHER_DECRYPT.\n+\\item The driver MUST specify the fields of struct virtio_crypto_cipher_data_req in\n+ struct virtio_crypto_sym_data_req if the request is based on VIRTIO_CRYPTO_SYM_OP_CIPHER.\n+\\item The driver MUST specify the fields of both struct virtio_crypto_cipher_data_req\n+ and struct virtio_crypto_mac_data_req in struct virtio_crypto_sym_data_req if the request\n+\tis of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING type and in the VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH mode.\n+\\end{itemize*}\n+\n+\\devicenormative{\\paragraph}{Symmetric algorithms Operation}{Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation}\n+\n+\\begin{itemize*}\n+\\item If the VIRTIO_CRYPTO_F_MUX_MODE feature bit is negotiated, the device MUST parse\n+ the struct virtio_crypto_op_data_req_mux for crypto requests. Otherwise, the device\n+\tMUST parse the struct virtio_crypto_op_data_req.\n+\\item If the VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE feature bit is negotiated, the device\n+ MUST parse \\field{flag} field in struct virtio_crypto_op_header in order to decide\n+\twhich mode the driver uses.\n+\\item The device MUST parse the virtio_crypto_sym_data_req based on the \\field{opcode}\n+ field in general header.\n+\\item The device SHOULD only parse fields of struct virtio_crypto_cipher_data_req in\n+ struct virtio_crypto_sym_data_req if the request is VIRTIO_CRYPTO_SYM_OP_CIPHER type.\n+\\item The device MUST parse fields of both struct virtio_crypto_cipher_data_req and\n+ struct virtio_crypto_mac_data_req in struct virtio_crypto_sym_data_req if the request\n+\tis of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING operation type and in the\n+\tVIRTIO_CRYPTO_SYM_HASH_MODE_AUTH mode.\n+\\item The device MUST copy the result of cryptographic operation in the dst_data[] in\n+ both plain CIPHER mode and algorithms chain mode.\n+\\item The device MUST check the \\field{para}.\\field{add_len} is bigger than 0 before\n+ parse the additional authenticated data in plain algorithms chain mode.\n+\\item The device MUST copy the result of HASH/MAC operation in the hash_result[] is\n+ of the VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING type.\n+\\item The device MUST set the \\field{status} field in struct virtio_crypto_inhdr to\n+ one of the following values of enum VIRTIO_CRYPTO_STATUS:\n+\\begin{itemize*}\n+\\item VIRTIO_CRYPTO_OK if the operation success.\n+\\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.\n+\\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.\n+\\item VIRTIO_CRYPTO_ERR if failure not mentioned above occurs.\n+\\end{itemize*}\n+\\end{itemize*}\n+\n+\\paragraph{Steps of Operation}\\label{sec:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation / Steps of Operation}\n+\n+The following is a example of the flow of work between the driver and the device if the VIRTIO_CRYPTO_F_MUX_MODE feature bit is NOT negotiated.\n+\n+\\subparagraph{Step1: Create session}\\label{sec:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation / Steps of Operation / Step1: Create session on session mode}\n+\n+\\begin{enumerate}\n+\\item The driver specifies information in struct virtio_crypto_op_ctrl_req, including\n+ the algorithm name, key, keylen etc;\n+\\item The driver adds the request of session creation into the controlq's Vring Descriptor Table;\n+\\item The driver kicks the device;\n+\\item The device receives the request from controlq;\n+\\item The device parses information about the request, and determines the information\n+ concerning the crypto accelerator;\n+\\item The device packs information based on the APIs of the crypto accelerator;\n+\\item The device invokes the session creation APIs of the crypto accelerator to create a session;\n+\\item The device returns the session id to the driver.\n+\\end{enumerate}\n+\n+\\subparagraph{Step2: Execute cryptographic operation}\\label{sec:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation / Steps of Operation / Step2: Execute cryptographic operation}\n+\n+\\begin{enumerate}\n+\\item The driver specifies information in struct virtio_crypto_op_data_req, including\n+ struct virtio_crypto_op_header and struct virtio_crypto_sym_data_req,\n+\tsee \\ref{sec:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation};\n+\\item The driver adds the request for cryptographic operation into the dataq's Vring Descriptor Table;\n+\\item The driver kicks the device (Or the device actively polls the dataq's Vring Descriptor Table);\n+\\item The device receives the request from dataq;\n+\\item The device parses information about the request, and determines the identification\n+ information for the crypto accelerator. For example, converting guest physical\n+\taddresses to host physical addresses;\n+\\item The device packs identification information based on the API of the crypto accelerator;\n+\\item The device invokes the cryptographic APIs of the crypto accelerator;\n+\\item The crypto accelerator executes the cryptographic operation implicitly;\n+\\item The device receives the cryptographic results from the crypto accelerator (synchronous or asynchronous);\n+\\item The device sets the \\field{status} in struct virtio_crypto_inhdr;\n+\\item The device updates and flushes the Used Ring to return the cryptographic results to the driver;\n+\\item The device notifies the driver (Or the driver actively polls the dataq's Used Ring);\n+\\item The driver saves the cryptographic results.\n+\\end{enumerate}\n+\n+\\subsubsection{AEAD Service Operation}\\label{sec:Device Types / Crypto Device / Device Operation / AEAD Service Operation}\n+\n+Session mode requests of symmetric algorithm are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_aead_para {\n+ /*\n+ * Byte Length of valid IV data.\n+ *\n+ * For GCM mode, this is either 12 (for 96-bit IVs) or 16, in which\n+ * case iv points to J0.\n+ * For CCM mode, this is the length of the nonce, which can be in the\n+ * range 7 to 13 inclusive.\n+ */\n+ le32 iv_len;\n+ /* length of additional auth data */\n+ le32 aad_len;\n+ /* length of source data */\n+ le32 src_data_len;\n+ /* length of dst data, this should be at least src_data_len + tag_len */\n+ le32 dst_data_len;\n+ /* Authentication tag length */\n+ le32 tag_len;\n+ le32 reserved;\n+};\n+\n+struct virtio_crypto_aead_data_req {\n+ /* Device-readable part */\n+ struct virtio_crypto_aead_para para;\n+ /*\n+ * Initialization Vector data.\n+ *\n+ * For GCM mode, this is either the IV (if the length is 96 bits) or J0\n+ * (for other sizes), where J0 is as defined by NIST SP800-38D.\n+ * Regardless of the IV length, a full 16 bytes needs to be allocated.\n+ * For CCM mode, the first byte is reserved, and the nonce should be\n+ * written starting at &iv[1] (to allow space for the implementation\n+ * to write in the flags in the first byte). Note that a full 16 bytes\n+ * should be allocated, even though the iv_len field will have\n+ * a value less than this.\n+ *\n+ * The IV will be updated after every partial cryptographic operation.\n+ */\n+ u8 iv[iv_len];\n+ /* Source data */\n+ u8 src_data[src_data_len];\n+ /* Additional authenticated data if exists */\n+ u8 aad[aad_len];\n+\n+ /* Device-writable part */\n+ /* Pointer to output data */\n+ u8 dst_data[dst_data_len];\n+\n+ struct virtio_crypto_inhdr inhdr;\n+};\n+\\end{lstlisting}\n+\n+Each data request uses virtio_crypto_aead_data_req structure to store information\n+used to run the AEAD operations.\n+\n+The information includes the hash parameters stored in \\field{para}, output data\n+and input data. In the first virtio_crypto_aead_para structure, \\field{iv_len}\n+specifies the length of the initialization vector. \\field{tag_len} specifies the\n+length of the authentication tag; \\field{aad_len} specifies the length of additional\n+authentication data, \\field{src_data_len} specifies the length of the source data;\n+\\field{dst_data_len} specifies the length of the destination data, which is at least\n+\\field{src_data_len} + \\field{tag_len}.\n+\n+The output data here includes the IV/Counter data, source data and additional\n+authenticated data if exists. The input data includes both destination data used\n+to save the results of the AEAD operations. \\field{inhdr} stores the status of\n+executing the AEAD operations.\n+\n+Stateless mode AEAD service requests are as follows:\n+\n+\\begin{lstlisting}\n+struct virtio_crypto_aead_para_stateless {\n+ struct {\n+ /* See VIRTIO_CRYPTO_AEAD_* above */\n+ le32 algo;\n+ /* length of key */\n+ le32 key_len;\n+ /* encrypt or decrypt, See above VIRTIO_CRYPTO_OP_* */\n+ le32 op;\n+ } sess_para;\n+\n+ /* Byte Length of valid IV data. */\n+ le32 iv_len;\n+ /* Authentication tag length */\n+ le32 tag_len;\n+ /* length of additional auth data */\n+ le32 aad_len;\n+ /* length of source data */\n+ le32 src_data_len;\n+ /* length of dst data, this should be at least src_data_len + tag_len */\n+ le32 dst_data_len;\n+};\n+\n+struct virtio_crypto_aead_data_req_stateless {\n+ /* Device-readable part */\n+ struct virtio_crypto_aead_para_stateless para;\n+ /* The cipher key */\n+ u8 key[key_len];\n+ /* Initialization Vector data. */\n+ u8 iv[iv_len];\n+ /* Source data */\n+ u8 src_data[src_data_len];\n+ /* Additional authenticated data if exists */\n+ u8 aad[aad_len];\n+\n+ /* Device-writable part */\n+ /* Pointer to output data */\n+ u8 dst_data[dst_data_len];\n+\n+ struct virtio_crypto_inhdr inhdr;\n+};\n+\\end{lstlisting}\n+\n+\\drivernormative{\\paragraph}{AEAD Service Operation}{Device Types / Crypto Device / Device Operation / AEAD Service Operation}\n+\n+\\begin{itemize*}\n+\\item If the driver uses the session mode, then the driver MUST set\n+ \\field{session_id} in struct virtio_crypto_op_header to a valid value assigned\n+\tby the device when the session was created.\n+\\item If the VIRTIO_CRYPTO_F_MUX_MODE feature bit is negotiated, the driver MUST\n+ use struct virtio_crypto_op_data_req_mux to wrap crypto requests. Otherwise,\n+\tthe driver MUST use struct virtio_crypto_op_data_req.\n+\\item If the VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE feature bit is negotiated, 1) if\n+ the driver uses the stateless mode, then the driver MUST set the \\field{flag}\n+\tfield in struct virtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_STATELESS_MODE\n+\tand MUST set the fields in struct virtio_crypto_aead_para_stateless.sess_para,\n+\t2) if the driver uses the session mode, then the driver MUST set the \\field{flag}\n+\tfield in struct virtio_crypto_op_header to VIRTIO_CRYPTO_FLAG_SESSION_MODE.\n+\\item The driver MUST set the \\field{opcode} field in struct virtio_crypto_op_header\n+ to VIRTIO_CRYPTO_AEAD_ENCRYPT or VIRTIO_CRYPTO_AEAD_DECRYPT.\n+\\end{itemize*}\n+\n+\\devicenormative{\\paragraph}{AEAD Service Operation}{Device Types / Crypto Device / Device Operation / AEAD Service Operation}\n+\n+\\begin{itemize*}\n+\\item If the VIRTIO_CRYPTO_F_MUX_MODE feature bit is negotiated, the device MUST\n+ parse the struct virtio_crypto_op_data_req_mux for crypto requests. Otherwise,\n+\tthe device MUST parse the struct virtio_crypto_op_data_req.\n+\\item If the VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE feature bit is negotiated, the\n+ device MUST parse the virtio_crypto_aead_data_req based on the \\field{opcode}\n+\tfield in general header.\n+\\item The device MUST copy the result of cryptographic operation in the dst_data[].\n+\\item The device MUST copy the authentication tag in the dst_data[] offset the cipher result.\n+\\item The device MUST set the \\field{status} field in struct virtio_crypto_inhdr to\n+ one of the following values of enum VIRTIO_CRYPTO_STATUS:\n+\\item When the \\field{opcode} field is VIRTIO_CRYPTO_AEAD_DECRYPT, the device MUST\n+ verify and return the verification result to the driver.\n+\\begin{itemize*}\n+\\item VIRTIO_CRYPTO_OK if the operation success.\n+\\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.\n+\\item VIRTIO_CRYPTO_BADMSG if the verification result is incorrect.\n+\\item VIRTIO_CRYPTO_INVSESS if the session ID invalid when in session mode.\n+\\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.\n+\\end{itemize*}\n+\\end{itemize*}\n", "prefixes": [ "REPOST", "v19", "1/2" ] }