Hi, Xin
> From: virtio-...@lists.oasis-open.org [mailto:virtio-...@lists.oasis-open.org]
> On Behalf Of Zeng, Xin
> Sent: Sunday, July 31, 2016 9:27 PM
> To: Gonglei (Arei); Michael S. Tsirkin
> Cc: qemu-devel@nongnu.org; virtio-...@lists.oasis-open.org; Ola Liljedahl;
> Keating, Brian A; Hanweidong (Randy); Luonengjun; Huangpeng (Peter); Griffin,
> John; Ma, Liang J; Stefan Hajnoczi; Cornelia Huck; Varun Sethi; Jani Kokkonen;
> Lingli Deng; Huangweidong (C)
> Subject: [virtio-dev] RE: [Qemu-devel] [PATCH v5] virtio-crypto: Add virtio
> crypto
> device specification
>
> On Friday, July 29, 2016 12:10 PM Gonglei (Arei) Wrote:
>
> > > I think version field is useful in some cases.
> > > Considering a case, if virtio crypto device implementation has defects,
> > > and a new version fixes this defect, how can the driver know whether the
> > > behavior of the device is correct or not?
> >
> > If it has defects, then we can call it bugs, if a software implementation
> > has
> > Bugs, the best choice is fixing them, Or we don't support the function
> > before
> > the bugs
> > fixed. And this is what the feature bits do. If we introduce a version, how
> > do
> > we
> > know which version fix that bugs? Do we need add another feature bit to
> > negotiable
> > it?
> >
>
> Refer to the comments in
> https://lists.gnu.org/archive/html/qemu-devel/2016-07/msg06680.html
>
I see, it seems to make sense. Thanks.
> > > Feature bit is mostly like a negotiable field between device and driver.
> > >
> > > > >
> > > > > > +One read-only bit (for the device) is currently defined for the
> > > > \field{status}
> > > > > > +field: VIRTIO_CRYPTO_S_HW_READY. One read-only bit (for the
> > driver)
> > > > > > +is currently defined for the status field:
> > VIRTIO_CRYPTO_S_STARTED.
> > > > >
> > > > >
> > > > > what does for the device/for the driver mean here?
> > > > >
> > > > Actually I meant the device set the status filed with
> > > > VIRTIO_CRYPTO_S_HW_READY,
> > > > And the driver set the status with VIRTIO_CRYPTO_S_STARTED.
> > > > But it seems that VIRTIO_CRYPTO_S_STARTED is superfluous,
> > > > VIRTIO_CONFIG_S_DRIVER_OK
> > > > is enough for all virtio devices.
> > > >
> > > > > > +
> > > > > > +\begin{lstlisting}
> > > > > > +#define VIRTIO_CRYPTO_S_HW_READY (1 << 0)
> > > > >
> > > > >
> > > > > so this is a way to tell guest "I am not ready yet, do not use"?
> > > > >
> > > > Yes. That's what I mean.
> > > >
> > > > >
> > > > > > +#define VIRTIO_CRYPTO_S_STARTED (1 << 1)
> > > > >
> > > > > does not look like anyone uses bit 1.
> > > > >
> > > > Yes, will drop it.
> > > >
> > > > > > +\end{lstlisting}
> > > > >
> > > > > What does each of these mean?
> > > > >
> > > > > > +
> > > > > > +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
> > > > > > +\end{lstlisting}
> > > > > > +
> > >
> > > Add ZUC_EIA3
> > > #define VIRTIO_CRYPTO_MAC_ZUC_EIA3 54
> > >
> > OK, will add it.
> >
> > > > > > +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.
> > > > >
> > > > > does it always go not ready->ready and never back?
> > > > >
> > > > Maybe not, if the cryptodev client is unplugged (if we support in QEMU
> > side),
> > > > we'd better set the ready status to false, which means ready --> not
> > ready.
> > > >
> > > > > > +\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
> > > > >
> > > > > why not use a name instead of "bottom bit of"?
> > > > >
> > > > OK.
> > > >
> > > > > > to
> > > > > > + check whether the hardware-backed implementation is ready
> or
> > > not.
> > > > >
> > > > > and if not ready then what is legal to do and what isn't?
> > > >
> > > > If you send packet to the device you can't get correct results
> > > > when the device is not ready.
> > > >
> > > > > better say what it must not do until device is ready.
> > > > >
> > > > We'd better not block to wait IMO because the hardware maybe unread
> > > > forever.
> > > >
> > > > > > +\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 \field{status} of hardware-backend comes
> > > > from the
> > > > > bottom bit of 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;
> > > > >
> > > > > does this means it is always the max size? or can any size be used
> > > > > as long as the struct fits in there?
> > > > > If second, then better split it I think.
> > > > >
> > > > Yes, it always use the max size reply on the union children.
> > > >
> > > > > > +};
> > > > > > +\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 Use VIRTIO_Crypto_CMD_RESOURCE_FLUSH
> > > > >
> > > > > why mixed case?
> > > > >
> > > > Sorry, I missed to drop those stuff came from virtio-gpu tex document
> > > > template :(
> > > >
> > > > > > to flush the updated resource
> > > > > > + to the display.
> > > > >
> > > > > display?
> > > > >
> > > > > > +\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.
> > > > >
> > > > > What is not supported?
> > > > >
> > > >
> > > > I meant some algorithms were unsupported by the device. But maybe
> > > > is not needed because the driver will check the virtio-crypo
> > > > configuration
> > > > space to get what the device support, right?
> > > >
> > >
> > > VIRTIO_CRYPTO_OP_NOTSUPP may also be used in some trivial features
> > that
> > > the feature bits and device configuration field don't present.
> > >
> > If the configuration filed don't present, how the driver know to use the
> > function or algorithm?
> >
>
> Here I meant some features which is passed by the parameter,
> For example, for CIPHER algorithm, the device might not support the some
> key's
> length by which the driver passed, it's better that the device could return a
> friendly
> error code. Probably VIRTIO_CRYPTO_OP_INVAL is better than
> VIRTIO_CRYPTO_OP_NOTSUPP.
>
Good point. :)
Regards,
-Gonglei
