[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [PATCH v9 1/2] virtio-crypto: Add virtio crypto device specification
On Thursday, September 08, 2016 6:05 PM, Gonglei Wrote: > +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} > + > +\devicenormative{\subsection}{Device Requirements: Device configuration > layout}\label{sec:Device Types / Crypto Device / Device configuration layout / > Device Requirements: Device configuration layout} Xelatex complains " Argument of \label has an extra } ", need fix. Same complaints below when using devicenormative and label. > + > +\begin{itemize*} > +\item The device MUST set \field{max_dataqueues} to between 1 and 65535 > inclusive. > +\item The device SHOULD set \field{status} according to the status of the > hardware-backed implementation. > +\item The device MUST set \field{crypto_services} according to the crypto > services which the device offered. > +\item The device MUST set detailed algorithms mask according to > \field{crypto_services} field. > +\end{itemize*} > + > +\drivernormative{\subsection}{Driver Requirements: Device configuration > layout}\label{sec:Device Types / Crypto Device / Device configuration layout / > Driver Requirements: Device configuration layout} > + > +\begin{itemize*} > +\item The driver MUST read the ready \field{status} from the bottom bit of > status to > + check whether the hardware-backed implementation is ready or not. > +\item The driver MAY read \field{max_dataqueues} field to discover how > many data queues the device supports. > +\item The driver MUST read \field{crypto_services} field to discover which > services the device is able to offer. > +\item The driver MUST read the detailed \field{algorithms} field according to > \field{crypto_services} field. > +\end{itemize*} > + > +\subsection{Device Initialization}\label{sec:Device Types / Crypto Device / > Device Initialization} > + > +\subsubsection{Driver Requirements: Device Initialization}\label{sec:Device > Types / Crypto Device / Device Initialization / Driver Requirements: Device > Initialization} > + > +\begin{itemize*} > +\item The driver MUST identify and initialize up to \field{max_dataqueues} > data virtqueues. > +\item The driver MUST identify the control virtqueue. > +\item The driver MUST identify the ready status of hardware-backend from > \field{status} field. > +\item The driver MUST read the supported crypto services from bits of > \field{crypto_servies}. > +\item The driver MUST read the supported algorithms according to > \field{crypto_services} field. > +\end{itemize*} > + > +\subsubsection{Device Requirements: Device Initialization}\label{sec:Device > Types / Crypto Device / Device Initialization / Device Requirements: Device > Initialization} > + > +\begin{itemize*} > +\item The device MUST be configured at least one accelerator which executes > real crypto operations. > +\item The device MUST write the \field{crypto_services} field according to the > capacities of the backend accelerator. > +\end{itemize*} > + > +\subsection{Device Operation}\label{sec:Device Types / Crypto Device / > Device Operation} > + > +Packets can be transmitted by placing them in both the controlq and dataq. > +Packets consist of a generic header and a service-specific request. > +Where 'general header' is for all crypto requests, 'service specific requests' > +are composed of operation parameter + output data + input data in general. > +Operation parameters are algorithm-specific parameters, output data is the > +data should be operated, input 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) > + __virtio32 opcode; > + __virtio32 algo; > + __virtio32 flag; > + /* data virtqueue id */ > + __virtio32 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) > + __virtio32 opcode; > + /* algo should be service-specific algorithms */ > + __virtio32 algo; > + /* session_id should be service-specific algorithms */ > + __virtio64 session_id; > + /* control flag to control the request */ > + __virtio32 flag; > + __virtio32 padding; > +}; > +\end{lstlisting} > + > +The device CAN set the status of operation as follows: > VIRTIO_CRYPTO_OP_OK for success, > +VIRTIO_CRYPTO_OP_ERR for failure or device error, > VIRTIO_CRYPTO_OP_NOTSUPP for not support, > +VIRTIO_CRYPTO_OP_INVSESS for invalid session id when executing crypto > operations. > + > +\begin{lstlisting} > +#define VIRTIO_CRYPTO_OP_OK 0 > +#define VIRTIO_CRYPTO_OP_ERR 1 > +#define VIRTIO_CRYPTO_OP_BADMSG 2 > +#define VIRTIO_CRYPTO_OP_NOTSUPP 3 > +#define VIRTIO_CRYPTO_OP_INVSESS 4 > +\end{lstlisting} > + > +\subsubsection{Control Virtqueue}\label{sec:Device Types / Crypto Device / > Device Operation / Control Virtqueue} > + > +The driver uses the control virtqueue to send control commands to the > +device which handles the non-data plane operations, such as session > +operations (See \ref{sec:Device Types / Crypto Device / Device Operation / > Control Virtqueue / Session operation}). > +The packet of controlq: > + > +\begin{lstlisting} > +struct virtio_crypto_op_ctrl_req { > + struct virtio_crypto_ctrl_header header; > + > + union { > + struct virtio_crypto_sym_create_session_req sym_create_session; > + struct virtio_crypto_hash_create_session_req hash_create_session; > + struct virtio_crypto_mac_create_session_req mac_create_session; > + struct virtio_crypto_aead_create_session_req aead_create_session; > + struct virtio_crypto_destroy_session_req destroy_session; > + } u; > +}; > +\end{lstlisting} > + > +The header is the general header, the union is an algorithm-specific type, > +which is set by the driver. All the properties in the union will be shown as > follows. > + > +\paragraph{Session operation}\label{sec:Device Types / Crypto Device / > Device Operation / Control Virtqueue / 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 set data, including the cipher algorithm and mode, > + the key and its length, and the direction (encrypt or decrypt). > +\item The hash/mac setup data, including the hash algorithm or mac > algorithm, > + and digest result length (to allow for truncation). > +\begin{itemize*} > +\item Authenticated mode can refer to MAC, which requires that the key and > + its length are also specified. > +\item For nested mode, the inner and outer prefix data and length are > specified, > + as well as the outer hash algorithm. > +\end{itemize*} > +\end{enumerate} > + > +The below structure store the result of session creation which is set by the > device: > + > +\begin{lstlisting} > +struct virtio_crypto_session_input { > + /* Device-writable part */ > + __virtio64 session_id; > + __virtio32 status; > + __virtio32 padding; > +}; > +\end{lstlisting} > + > +A request which destroy a session including the following information: > + > +\begin{lstlisting} > +struct virtio_crypto_destroy_session_req { > + /* Device-readable part */ > + __virtio64 session_id; > + /* Device-writable part */ > + __virtio32 status; > + __virtio32 padding; > +}; > +\end{lstlisting} > + > +\subparagraph{Session operation: HASH session}\label{sec:Device Types / > Crypto Device / Device > +Operation / Control Virtqueue / Session operation / Session operation: HASH > session} > + > +The packet of HASH session is: > + > +\begin{lstlisting} > +struct virtio_crypto_hash_session_para { > + /* See VIRTIO_CRYPTO_HASH_* above */ > + le32 algo; > + /* hash result length */ > + le32 hash_result_len; > +}; > +struct virtio_crypto_hash_create_session_req { > + /* Device-readable part */ > + struct virtio_crypto_hash_session_para para; > + /* Device-writable part */ > + struct virtio_crypto_session_input input; > +}; > +\end{lstlisting} > + > +\subparagraph{Session operation: MAC session}\label{sec:Device Types / > Crypto Device / Device > +Operation / Control Virtqueue / Session operation / Session operation: MAC > session} > + > +The packet of MAC session is: > + > +\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; > + __virtio32 padding; > +}; > +struct virtio_crypto_mac_session_output { > + __virtio64 auth_key_addr; /* guest key physical address */ > +}; > + > +struct virtio_crypto_mac_create_session_req { > + /* Device-readable part */ > + struct virtio_crypto_mac_session_para para; > + struct virtio_crypto_mac_session_output out; > + /* Device-writable part */ > + struct virtio_crypto_session_input input; > +}; > +\end{lstlisting} > + > + > +\devicenormative{\subparagraph}{Session operation: create > session}\label{sec:Device Types / Crypto Device / Device > +Operation / Control Virtqueue / 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 \field{status} field and a \field{session_id} field: > + > +Both \field{status} and \field{session_id} are written by the device: either > VIRTIO_CRYPTO_OP_OK for success, > +VIRTIO_CRYPTO_OP_ERR for creation failed or device error, > VIRTIO_CRYPTO_OP_NOTSUPP for not support, > +VIRTIO_CRYPTO_OP_INVSESS for invalid session id when executing crypto > operations. > + > +\drivernormative{\subparagraph}{Session operation: destroy > session}\label{sec:Device Types / Crypto Device / Device > +Operation / Control Virtqueue / Session operation / Session operation: destroy > session / Driver Requirements: Session operation: destroy session} > + > +The driver MUST set the control general header and corresponding property > +of union in struct virtio_crypto_op_ctrl_req. See \ref{sec:Device Types / > Crypto Device / Device Operation / Control Virtqueue}. > +Take the example of MAC service, the driver MUST set > VIRTIO_CRYPTO_MAC_DESTROY_SESSION > +for \field{opcode} field in struct virtio_crypto_op_ctrl_req, and set the > \field{queue_id} shows dataq used. > +The driver MUST set the \field{session_id} which MUST be a valid value which > assigned by the > +device when a session was created. > + > +\devicenormative{\subparagraph}{Session operation: destroy > session}\label{sec:Device Types / Crypto Device / Device > +Operation / Control Virtqueue / Session operation / Session operation: destroy > session / Device Requirements: Session operation: destroy session} > + > +\field{status} field is written by the device: either VIRTIO_CRYPTO_OP_OK for > success, VIRTIO_CRYPTO_OP_ERR for failure or device error. > + > +\subsubsection{Data Virtqueue}\label{sec:Device Types / Crypto Device / > Device Operation / Data Virtqueue} > + > +The driver uses the data virtqueue to transmit the requests of crypto > operation to the device, > +and to finish the data plane operations (such as crypto operation). > + > +The packet of dataq: > + > +\begin{lstlisting} > +struct virtio_crypto_op_data_req { > + struct virtio_crypto_op_header header; > + > + union { > + struct virtio_crypto_sym_data_req sym_req; > + struct virtio_crypto_hash_data_req hash_req; > + struct virtio_crypto_mac_data_req mac_req; > + struct virtio_crypto_aead_data_req aead_req; > + } u; > +}; > +\end{lstlisting} > + > +The header is the general header, the union is algorithm-specific type, > +which are set by the driver. All properties in the union will be shown as follow. > + > +There is a unify idata structure for all symmetric algorithms, including > CIPHER, HASH, MAC, AEAD. > +The structure is defined as: > + > +\begin{lstlisting} > +struct virtio_crypto_sym_input { > + /* Destination data guest address, it's useless for plain HASH and MAC */ > + __virtio64 dst_data_addr; > + /* Digest result guest address, it's useless for plain cipher algos */ > + __virtio64 digest_result_addr; > + > + __virtio32 status; > + __virtio32 padding; > +}; > +\end{lstlisting} > + > +\paragraph{HASH Service Operation}\label{sec:Device Types / Crypto Device / > Device Operation / Data Virtqueue / HASH Service Operation} > + > +\begin{lstlisting} > +struct virtio_crypto_hash_input { > + struct virtio_crypto_sym_input input; > +}; > + > +struct virtio_crypto_hash_output { > + /* source data guest address */ > + __virtio64 src_data_addr; > + /* length of source data */ > + __virtio32 src_data_len; > + __virtio32 padding; > +}; > + > +struct virtio_crypto_hash_data_req { > + /* Device-readable part */ > + struct virtio_crypto_hash_output odata; > + /* Device-writable part */ > + struct virtio_crypto_hash_input idata; > +}; > +\end{lstlisting} > + > +Each data request uses virtio_crypto_hash_data_req structure to store > informations, > +which are used to execute one HASH operation. The request only occupies one > entry > +of the Vring descriptor table in virtio crypto device's dataq, which improves > +the throughput of data transferring for HASH service, so that the virtio crypto > +device CAN get the better result of acceleration. > + > +The informations include the source data guest physical address stored by > \field{src_data_addr}, > +length of source data stored by \field{src_data_len}, digest result guest > physical address > +stored by \field{digest_result_addr} which is used to save the result of HASH > operation. > +The address and length CAN determine the specific content in the guest > memory. > + > +Note: The guest memory MUST be guaranteed to be allocated and physically- > contiguous > +pointed by \field{digest_result_addr} in struct virtio_crypto_hash_input and > +\field{src_data_addr} in struct virtio_crypto_hash_output. > + > +\drivernormative{\subparagraph}{HASH Service Operation}\label{sec:Device > Types / Crypto Device / Device > +Operation / Data Virtqueue / HASH Service Operation / Driver Requirements: > HASH Service Operation} > + > +The driver MUST set the \field{opcode}, \field{session_id} in struct > virtio_crypto_op_header. > +The \field{opcode} is set to VIRTIO_CRYPTO_HASH, \field{session_id} MUST be > a valid value > +which assigned by the device when a session was created. > +The driver SHOULD set the \field{queue_id} field to show dataq used in struct > virtio_crypto_op_header. > +The driver MUST fill out all fields in struct virtio_crypto_hash_data_req, > including \field{parameter}, > +\field{odata} and \field{idata} sub structures. > + > +\devicenormative{\subparagraph}{HASH Service Operation}\label{sec:Device > Types / Crypto Device / Device > +Operation / Data Virtqueue / HASH Service Operation / Device Requirements: > HASH Service Operation} > + > +The device MUST copy the result of hash operation recorded by > \field{digest_result_addr} > +filed in struct virtio_crypto_hash_input. > +The device MUST set the \field{status} in strut virtio_crypto_hash_input: either > VIRTIO_CRYPTO_OP_OK for success, > +VIRTIO_CRYPTO_OP_ERR for creation failed or device error, > VIRTIO_CRYPTO_OP_NOTSUPP for not support. > + > +\paragraph{MAC Service Operation}\label{sec:Device Types / Crypto Device / > Device Operation / Data Virtqueue / MAC Service Operation} > + > +\begin{lstlisting} > +struct virtio_crypto_mac_input { > + struct virtio_crypto_sym_input input; > +}; > + > +struct virtio_crypto_mac_output { > + struct virtio_crypto_hash_output hash_output; > +}; > + > +struct virtio_crypto_mac_data_req { > + /* Device-readable part */ > + struct virtio_crypto_mac_output odata; > + /* Device-writable part */ > + struct virtio_crypto_mac_input idata; > +}; > +\end{lstlisting} > + > +Each data request uses virtio_crypto_mac_data_req structure to store > informations, > +which are used to execute one MAC operation. The request only occupies one > entry > +of the Vring descriptor table in virtio crypto device's dataq, which improves > +the throughput of data transferring for MAC service, so that the virtio crypto > +device CAN get the better result of acceleration. > + > +The informations include the source data guest physical address stored by > \field{src_data_addr}, > +length of source data stored by \field{src_data_len}, digest result guest > physical address > +stored by \field{digest_result_addr} which is used to save the result of MAC > operation. > +The address and length CAN determine the specific content in the guest > memory. > + > +Note: The guest memory MUST be guaranteed to be allocated and physically- > contiguous > +pointed by \field{digest_result_addr} in struct virtio_crypto_hash_input and > +\field{src_data_addr} in struct virtio_crypto_hash_output. > + > +\drivernormative{\subparagraph}{MAC Service Operation}\label{sec:Device > Types / Crypto Device / Device > +Operation / Data Virtqueue / MAC Service Operation / Driver Requirements: > MAC Service Operation} > + > +Refer to the hash operation. > +The driver MUST set the \field{opcode} field to VIRTIO_CRYPTO_MAC. > + > +\devicenormative{\subparagraph}{MAC Service Operation}\label{sec:Device > Types / Crypto Device / Device > +Operation / Data Virtqueue / MAC Service Operation / Device Requirements: > MAC Service Operation} > + > +Refer to the hash operation. > + > +\paragraph{Symmetric algorithms Operation}\label{sec:Device Types / Crypto > Device / Device Operation / Data Virtqueue / Symmetric algorithms Operation} > + > +The packet of plain CIPHER service is: > + > +\begin{lstlisting} > +struct virtio_crypto_cipher_para { > + le32 iv_len; > + /* length of source data */ > + le32 src_data_len; > + /* length of dst data */ > + le32 dst_data_len; > + __virtio32 padding; > +}; > + > + > +The device MUST parse the virtio_crypto_sym_data_req according to the > session_id in general header. > + > +The device SHOULD only parsed fields of struct virtio_crypto_cipher_data_req > in > +struct virtio_crypto_sym_data_req if the created session is > VIRTIO_CRYPTO_SYM_OP_CIPHER type. > + > +The driver SHOULD parse fields of both struct virtio_crypto_cipher_data_req > and struct > +virtio_crypto_mac_data_req mac_req in struct virtio_crypto_sym_data_req if > the created > +session is VIRTIO_CRYPTO_SYM_OP_ALGORITHM_CHAINING operation type > and VIRTIO_CRYPTO_SYM_HASH_MODE_AUTH mode. > + > +The device MUST copy the result of encryption operation recorded by > \filed{dst_data_addr} filed in struct virtio_crypto_cipher_input in plain cipher s/filed/field/ > mode. > +The device MUST copy the result of hash operation recorded by > \filed{digest_result_addr} filed in struct virtio_crypto_hash_input in chain > hash/mac mode. > +The device MUST set the \filed{status} field in strut > virtio_crypto_cipher_input: either VIRTIO_CRYPTO_OP_OK for success, > VIRTIO_CRYPTO_OP_ERR for creation > +failed or device error, VIRTIO_CRYPTO_OP_NOTSUPP for not support. > + > +\subparagraph{Steps of Encryption}\label{sec:Device Types / Crypto Device / > Device > +Operation / Data Virtqueue / Symmetric algorithms Operation / Steps of > Encryption} > + > +Step1: Creating a session: > +\begin{enumerate} > +\item The driver fills out informations in struct virtio_crypto_op_ctrl_req, > including algorithm name, key, keylen etc; > +\item The driver puts the request of session creation into the controlq's Vring > descriptor table; > +\item The driver kicks the device; > +\item The device gets the request from controlq; > +\item The device parses informations of the request, determines the > informations of the backend crypto accelerator; > +\item The device packages informations according to the API of the backend > crypto accelerator; > +\item The device invokes the session creation API of the backend crypto > accelerator to create a session; > +\item The device returns the session id to the driver. > +\end{enumerate} > + > +Step2: Executing the detail encryption operation: > +\begin{enumerate} > +\item The driver fills out informations in struct virtio_crypto_op_data_req, > including struct virtio_crypto_op_header and struct > virtio_crypto_sym_data_req, See \ref{sec:Device Types / Crypto Device / > Device > + Operation / Data Virtqueue / Symmetric algorithms Operation / Driver > Requirements: Symmetric algorithms Encryption}; > +\item The driver puts the request of encryption into the dataq's Vring > descriptor table; > +\item The driver kicks the device (Or the device polls the dataq's Vring > descriptor table actively); > +\item The device gets the request from dataq; > +\item The device parses informations of the request, determines the > identifying informations of the backend crypto accelerator. > + For example, changing guest physical addresses to host physical addresses; > +\item The device packages identifying informations according to the API of the > backend crypto accelerator; > +\item The device invokes the encryption API of the backend crypto > accelerator; > +\item The backend crypto accelerator executes the encryption operation > implicitly; > +\item The device gets the encryption result from the backend crypto > accelerator (synchronous or asynchronous); > +\item The device set the \field{status} in struct virtio_crypto_cipher_input; > +\tiem The device updates and flushes the Vring used table to return the s/tiem/item/ > encryption result to the driver; > +\item The device notifies the driver (Or the driver polls the dataq's Vring used > table actively); > +\item The driver handles the encryption result. > +\end{enumerate} > +
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]