Re: [Qemu-devel] [virtio-dev] [PATCH v17 1/2] virtio-crypto: Add virtio crypto device specification
> -Original Message-
> From: Stefan Hajnoczi [mailto:stefa...@redhat.com]
> Sent: Friday, April 21, 2017 9:07 PM
>
> Subject: Re: [virtio-dev] [PATCH v17 1/2] virtio-crypto: Add virtio crypto
> device
> specification
>
> On Thu, Apr 13, 2017 at 05:11:13PM +0800, Gonglei wrote:
> > +The request of dataq, mixing both session and stateless mode is as follows:
>
> It sounds more natural when "request" is plural:
>
> "Dataq requests for both session and stateless modes are as follows:"
>
OK.
> > +
> > +\begin{lstlisting}
> > +struct virtio_crypto_op_data_req_mux {
> > +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;
> > +struct virtio_crypto_sym_data_req_stateless
> sym_stateless_req;
> > +struct virtio_crypto_hash_data_req_stateless
> hash_stateless_req;
> > +struct virtio_crypto_mac_data_req_stateless
> mac_stateless_req;
> > +struct virtio_crypto_aead_data_req_stateless
> aead_stateless_req;
> > +} u;
> > +};
> > +\end{lstlisting}
> > +
> > +The header is the general header and the union is of the algorithm-specific
> type,
> > +which is set by the driver. All properties in the union are shown as
> > follows.
> > +
> > +There is a unified input header structure for all crypto services.
> > +
> > +The structure is defined as follows:
> > +
> > +\begin{lstlisting}
> > +struct virtio_crypto_inhdr {
> > +u8 status;
> > +};
> > +\end{lstlisting}
> > +
> > +\subsubsection{HASH Service Operation}\label{sec:Device Types / Crypto
> Device / Device Operation / HASH Service Operation}
> > +
> > +The session mode request of HASH service:
>
> Plural "request":
>
> "Session mode HASH service requests are defined as follows:"
>
Fixed.
> > +
> > +\begin{lstlisting}
> > +struct virtio_crypto_hash_para {
> > +/* length of source data */
> > +le32 src_data_len;
> > +/* hash result length */
> > +le32 hash_result_len;
> > +};
> > +
> > +struct virtio_crypto_hash_data_req {
> > +/* Device-readable part */
> > +struct virtio_crypto_hash_para para;
> > +/* Source data */
> > +u8 src_data[src_data_len];
> > +
> > +/* Device-writable part */
> > +/* Hash result data */
> > +u8 hash_result[hash_result_len];
> > +struct virtio_crypto_inhdr inhdr;
> > +};
> > +\end{lstlisting}
> > +
> > +Each data request uses virtio_crypto_hash_data_req structure to store
> information
> > +used to run the HASH operations.
> > +
> > +The information includes the hash parameters stored by \field{para}, output
> data and input data.
>
> "stored in $container" vs "stored by $actor_or_service_or_action". For
> example:
>
> "stored in register EAX" <-- container
> "stored in /etc/passwd" <-- container
> "stored by the worker thread" <-- actor
> "stored by calling api_write()" <-- action
> "stored by ext4" <-- service
>
> Since \field{para} is a container it needs to be "stored in
> \field{para}".
>
Great thanks :)
All fixed.
> > +The output data here includes the source data and the input data includes
> the hash result data used to save the results of the HASH operations.
> > +\field{inhdr} stores status of executing the HASH operations.
>
> Missing article: "stores the status"
>
All fixed.
> > +
> > +The stateless mode request of HASH service is as follows:
>
> Plural "requests":
>
> "Stateless mode HASH service requests are as follows:"
>
> (The same applies to more instances below.)
>
All fixed.
> > +
> > +\begin{lstlisting}
> > +struct virtio_crypto_hash_para_statelesss {
> > +struct {
> > +/* See VIRTIO_CRYPTO_HASH_* above */
> > +le32 algo;
> > +} sess_para;
> > +
> > +/* length of source data */
> > +le32 src_data_len;
> > +/* hash result length */
> > +le32 hash_result_len;
> > +le32 reserved;
> > +};
> > +struct virtio_crypto_hash_data_req_stateless {
> > +/* Device-readable part */
> > +struct virtio_crypto_hash_para_stateless para;
> > +/* Source data */
> > +u8 src_data[src_data_len];
> > +
> > +/* Device-writable part */
> > +/* Hash result data */
> > +u8 hash_result[hash_result_len];
> > +struct virtio_crypto_inhdr inhdr;
> > +};
> > +\end{lstlisting}
> > +
> > +\drivernormative{\paragraph}{HASH Service Operation}{Device Types /
> Crypto Device / Device Operation / HASH Service Operation}
> > +
> > +\begin{itemize*}
> > +\item If the driver uses the session mode, then the driver MUST set the
> \field{session_id} in struct virtio_crypto_op_header
> > + to a valid value which assigned by the device when a session is
> created.
>
> Please see my previous email for a change to "a valid value which
> assigned by the device when a session is created".
>
Sure, all fixed.
> > +\item If the VIRTIO_CR
Re: [Qemu-devel] [virtio-dev] [PATCH v17 1/2] virtio-crypto: Add virtio crypto device specification
On Thu, Apr 13, 2017 at 05:11:13PM +0800, Gonglei wrote:
> +The request of dataq, mixing both session and stateless mode is as follows:
It sounds more natural when "request" is plural:
"Dataq requests for both session and stateless modes are as follows:"
> +
> +\begin{lstlisting}
> +struct virtio_crypto_op_data_req_mux {
> +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;
> +struct virtio_crypto_sym_data_req_stateless sym_stateless_req;
> +struct virtio_crypto_hash_data_req_stateless hash_stateless_req;
> +struct virtio_crypto_mac_data_req_stateless mac_stateless_req;
> +struct virtio_crypto_aead_data_req_stateless aead_stateless_req;
> +} u;
> +};
> +\end{lstlisting}
> +
> +The header is the general header and the union is of the algorithm-specific
> type,
> +which is set by the driver. All properties in the union are shown as follows.
> +
> +There is a unified input header structure for all crypto services.
> +
> +The structure is defined as follows:
> +
> +\begin{lstlisting}
> +struct virtio_crypto_inhdr {
> +u8 status;
> +};
> +\end{lstlisting}
> +
> +\subsubsection{HASH Service Operation}\label{sec:Device Types / Crypto
> Device / Device Operation / HASH Service Operation}
> +
> +The session mode request of HASH service:
Plural "request":
"Session mode HASH service requests are defined as follows:"
> +
> +\begin{lstlisting}
> +struct virtio_crypto_hash_para {
> +/* length of source data */
> +le32 src_data_len;
> +/* hash result length */
> +le32 hash_result_len;
> +};
> +
> +struct virtio_crypto_hash_data_req {
> +/* Device-readable part */
> +struct virtio_crypto_hash_para para;
> +/* Source data */
> +u8 src_data[src_data_len];
> +
> +/* Device-writable part */
> +/* Hash result data */
> +u8 hash_result[hash_result_len];
> +struct virtio_crypto_inhdr inhdr;
> +};
> +\end{lstlisting}
> +
> +Each data request uses virtio_crypto_hash_data_req structure to store
> information
> +used to run the HASH operations.
> +
> +The information includes the hash parameters stored by \field{para}, output
> data and input data.
"stored in $container" vs "stored by $actor_or_service_or_action". For
example:
"stored in register EAX" <-- container
"stored in /etc/passwd" <-- container
"stored by the worker thread" <-- actor
"stored by calling api_write()" <-- action
"stored by ext4" <-- service
Since \field{para} is a container it needs to be "stored in
\field{para}".
> +The output data here includes the source data and the input data includes
> the hash result data used to save the results of the HASH operations.
> +\field{inhdr} stores status of executing the HASH operations.
Missing article: "stores the status"
> +
> +The stateless mode request of HASH service is as follows:
Plural "requests":
"Stateless mode HASH service requests are as follows:"
(The same applies to more instances below.)
> +
> +\begin{lstlisting}
> +struct virtio_crypto_hash_para_statelesss {
> +struct {
> +/* See VIRTIO_CRYPTO_HASH_* above */
> +le32 algo;
> +} sess_para;
> +
> +/* length of source data */
> +le32 src_data_len;
> +/* hash result length */
> +le32 hash_result_len;
> +le32 reserved;
> +};
> +struct virtio_crypto_hash_data_req_stateless {
> +/* Device-readable part */
> +struct virtio_crypto_hash_para_stateless para;
> +/* Source data */
> +u8 src_data[src_data_len];
> +
> +/* Device-writable part */
> +/* Hash result data */
> +u8 hash_result[hash_result_len];
> +struct virtio_crypto_inhdr inhdr;
> +};
> +\end{lstlisting}
> +
> +\drivernormative{\paragraph}{HASH Service Operation}{Device Types / Crypto
> Device / Device Operation / HASH Service Operation}
> +
> +\begin{itemize*}
> +\item If the driver uses the session mode, then the driver MUST set the
> \field{session_id} in struct virtio_crypto_op_header
> + to a valid value which assigned by the device when a session is
> created.
Please see my previous email for a change to "a valid value which
assigned by the device when a session is created".
> +\item If the VIRTIO_CRYPTO_F_STATELESS_MODE feature bit is negotiated, the
> driver MUST use the struct virtio_crypto_op_data_req_mux to wrap crypto
> requests. Otherwise, the driver MUST use the struct virtio_crypto_op_data_req.
The article is omitted when referring to a specific named object:
"use struct virtio_crypto_op_data_req_mux" and "use struct
virtio_crypto_op_data_req"
> +\item If the VIRTIO_CRYPTO_F_HASH_STATELESS_MODE feature bit is negotiated,
> 1) if the driver use the stateless mode, then the driver MUST set
> \field{flag} field in struct virtio_crypto_op_header
"he/she/it us
Re: [Qemu-devel] [virtio-dev] [PATCH v17 1/2] virtio-crypto: Add virtio crypto device specification
Hi Stefan,
>
> Subject: Re: [virtio-dev] [PATCH v17 1/2] virtio-crypto: Add virtio crypto
> device
> specification
>
> On Thu, Apr 13, 2017 at 05:11:13PM +0800, Gonglei wrote:
>
> More review, not done yet.
>
Thanks a lot!
[snip]
> > +The device can set the operation status as follows: VIRTIO_CRYPTO_OK:
> success;
> > +VIRTIO_CRYPTO_ERR: failure or device error; VIRTIO_CRYPTO_NOTSUPP:
> not supported;
> > +VIRTIO_CRYPTO_INVSESS: invalid session ID when executing crypto
> operations.
> > +
> > +\begin{lstlisting}
> > +enum VIRITO_CRYPTO_STATUS {
>
> s/VIRITO/VIRTIO/
>
Oops, good catch. Fortunately I hadn't define this name in source code.
Will fix it in the next version.
> > +VIRTIO_CRYPTO_OK = 0,
> > +VIRTIO_CRYPTO_ERR = 1,
> > +VIRTIO_CRYPTO_BADMSG = 2,
> > +VIRTIO_CRYPTO_NOTSUPP = 3,
> > +VIRTIO_CRYPTO_INVSESS = 4,
> > +VIRTIO_CRYPTO_MAX
> > +};
> > +\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, such as session operations (See \ref{sec:Device Types / Crypto
> Device / Device Operation / Control Virtqueue / Session operation}).
> > +
> > +The request of controlq is as below:
> > +
> > +\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}
> > +
> > +struct virtio_crypto_op_ctrl_req is the only loading form of controlq
> requests.
>
> Does "loading" mean "allowed"?
>
> "struct virtio_crypto_op_ctrl_req is the only allowed control request"
>
Hmm.. It's better.
> > +The header is the general header, and the union is of the
> > algorithm-specific
> type,
> > +which is set by the driver. All the properties in the union are shown as
> follows.
> > +
> > +\paragraph{Session operation}\label{sec:Device Types / Crypto Device /
> Device Operation / Control Virtqueue / Session operation}
> > +
> > +The symmetric algorithms involve the concept of sessions. A session is a
> > +handle which describes the cryptographic parameters to be applied to
> > +a number of buffers. The data within a session handle includes:
> > +
> > +\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 (encryption or decryption).
> > +\item The HASH/MAC set data, including the HASH algorithm or MAC
> algorithm,
> > + and hash result length (to allow for truncation).
> > +\begin{itemize*}
> > +\item Authenticated mode can refer to MAC, which requires that the key
> and
> > + its length are also specified.
> > +\item For nested mode, the inner and outer prefix data and length are
> specified,
> > + as well as the outer HASH algorithm.
> > +\end{itemize*}
> > +\end{enumerate}
> > +
> > +The following structure stores the result of session creation set by the
> device:
> > +
> > +\begin{lstlisting}
> > +struct virtio_crypto_session_input {
> > +/* Device-writable part */
> > +le64 session_id;
> > +le32 status;
> > +le32 padding;
> > +};
> > +\end{lstlisting}
> > +
> > +A request to destroy a session includes the following information:
> > +
> > +\begin{lstlisting}
> > +struct virtio_crypto_destroy_session_req {
> > +/* Device-readable part */
> > +le64 session_id;
> > +/* Device-writable part */
> > +le32 status;
> > +le32 padding;
> > +};
> > +\end{lstlisting}
> > +
> > +\subparagraph{Session operation: HASH session}\label{sec:Device Types /
> Crypto Device / Device
> > +Operation / Control Virtqueue / Session operation / Session operation: HASH
> session}
> > +
> > +The request of HASH session is as follows:
> > +
> > +\begin{lstlisting}
> > +struct virtio_crypto_hash_session_para {
> > +/* See VIRTIO_CRYPTO_HASH_* above */
> > +le32 algo;
> > +/* hash result length */
> > +le32 hash_result_len;
> > +};
> > +struct virtio_crypto_hash_create_session_req {
> > +/* Device-readable part */
> > +struct virtio_crypto_hash_session_para para;
> > +/* Device-writable part */
> > +struct virtio_crypto_session_input input;
> > +};
> > +\end{lstlisting}
> > +
> > +\subparagraph{Session operation: MAC session}\label{sec:Device Types /
> Crypto Device / Device
> > +Operation / Control Virtqueue / Session operation / Session o
Re: [Qemu-devel] [virtio-dev] [PATCH v17 1/2] virtio-crypto: Add virtio crypto device specification
On Thu, Apr 13, 2017 at 05:11:13PM +0800, Gonglei wrote:
More review, not done yet.
> The virtio crypto device is a virtual crypto device (ie. hardware
> crypto accelerator card). Currently, the virtio crypto device provides
> the following crypto services: CIPHER, MAC, HASH, and AEAD.
>
> In this patch, CIPHER, MAC, HASH, AEAD services are introduced.
>
> VIRTIO-153
>
> Signed-off-by: Gonglei
> CC: Michael S. Tsirkin
> CC: Cornelia Huck
> CC: Stefan Hajnoczi
> CC: Lingli Deng
> CC: Jani Kokkonen
> CC: Ola Liljedahl
> CC: Varun Sethi
> CC: Zeng Xin
> CC: Keating Brian
> CC: Ma Liang J
> CC: Griffin John
> CC: Mihai Claudiu Caraman
> CC: Halil Pasic
> ---
> acknowledgements.tex |1 +
> content.tex |2 +
> virtio-crypto.tex| 1305
> ++
> 3 files changed, 1308 insertions(+)
> create mode 100644 virtio-crypto.tex
>
> diff --git a/acknowledgements.tex b/acknowledgements.tex
> index 53942b0..6714544 100644
> --- a/acknowledgements.tex
> +++ b/acknowledgements.tex
> @@ -44,4 +44,5 @@ Patrick Durusau,Technical Advisory Board, OASIS \newline
> Thomas Huth, Red Hat \newline
> Yan Vugenfirer, Red Hat / Daynix \newline
> Kevin Lo,MSI \newline
> +Halil Pasic, IBM \newline
> \end{oasistitlesection}
> diff --git a/content.tex b/content.tex
> index 4b45678..ab75f78 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -5750,6 +5750,8 @@ descriptor for the \field{sense_len}, \field{residual},
> \field{status_qualifier}, \field{status}, \field{response} and
> \field{sense} fields.
>
> +\input{virtio-crypto.tex}
> +
> \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
>
> Currently there are three device-independent feature bits defined:
> diff --git a/virtio-crypto.tex b/virtio-crypto.tex
> new file mode 100644
> index 000..c73a1ef
> --- /dev/null
> +++ b/virtio-crypto.tex
> @@ -0,0 +1,1305 @@
> +\section{Crypto Device}\label{sec:Device Types / Crypto Device}
> +
> +The virtio crypto device is a virtual cryptography device as well as a kind
> of
> +virtual hardware accelerator for virtual machines. The encryption and
> +decryption requests are placed in any of the data queues and are ultimately
> handled by the
> +backend crypto accelerators. The second kind of queue is the control queue
> used to create
> +or destroy sessions for symmetric algorithms and will control some advanced
> +features in the future. The virtio crypto device provides the following
> crypto
> +services: CIPHER, MAC, HASH, and AEAD.
> +
> +
> +\subsection{Device ID}\label{sec:Device Types / Crypto Device / Device ID}
> +
> +20
> +
> +\subsection{Virtqueues}\label{sec:Device Types / Crypto Device / Virtqueues}
> +
> +\begin{description}
> +\item[0] dataq1
> +\item[\ldots]
> +\item[N-1] dataqN
> +\item[N] controlq
> +\end{description}
> +
> +N is set by \field{max_dataqueues}.
> +
> +\subsection{Feature bits}\label{sec:Device Types / Crypto Device / Feature
> bits}
> +
> +VIRTIO_CRYPTO_F_STATELESS_MODE (0) stateless mode is available.
> +VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE (1) stateless mode is available for
> CIPHER service.
> +VIRTIO_CRYPTO_F_HASH_STATELESS_MODE (2) stateless mode is available for HASH
> service.
> +VIRTIO_CRYPTO_F_MAC_STATELESS_MODE (3) stateless mode is available for MAC
> service.
> +VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE (4) stateless mode is available for AEAD
> service.
> +
> +\subsubsection{Feature bit requirements}\label{sec:Device Types / Crypto
> Device / Feature bits}
> +
> +Some crypto feature bits require other crypto feature bits
> +(see \ref{drivernormative:Basic Facilities of a Virtio Device / Feature
> Bits}):
> +
> +\begin{description}
> +\item[VIRTIO_CRYPTO_F_CIPHER_STATELESS_MODE] Requires
> VIRTIO_CRYPTO_F_STATELESS_MODE.
> +\item[VIRTIO_CRYPTO_F_HASH_STATELESS_MODE] Requires
> VIRTIO_CRYPTO_F_STATELESS_MODE.
> +\item[VIRTIO_CRYPTO_F_MAC_STATELESS_MODE] Requires
> VIRTIO_CRYPTO_F_STATELESS_MODE.
> +\item[VIRTIO_CRYPTO_F_AEAD_STATELESS_MODE] Requires
> VIRTIO_CRYPTO_F_STATELESS_MODE.
> +\end{description}
> +
> +\subsection{Supported crypto services}\label{sec:Device Types / Crypto
> Device / Supported crypto services}
> +
> +The virtio crypto device provides the following crypto services: CIPHER,
> MAC, HASH, and AEAD.
> +
> +\begin{lstlisting}
> +/* CIPHER service */
> +#define VIRTIO_CRYPTO_SERVICE_CIPHER 0
> +/* HASH service */
> +#define VIRTIO_CRYPTO_SERVICE_HASH 1
> +/* MAC (Message Authentication Codes) service */
> +#define VIRTIO_CRYPTO_SERVICE_MAC2
> +/* AEAD (Authenticated Encryption with Associated Data) service */
> +#define VIRTIO_CRYPTO_SERVICE_AEAD 3
> +\end{lstlisting}
> +
> +The above constants are bit numbers, which used to tell the driver which
> crypto services
> +are supported by the device, see \ref{sec:Device Types / Crypto Device /
> Device configuration layout}.
> +
> +\subsubsection{CIPHER services}\label{sec:Device Types / Cry
