Re: [PATCH RFC 4/4] virtio-crypto: Add device and driver requirements for IPsec operation

[Matias Ezequiel Vara Larsen <mvaralar@redhat.com>]

On Fri, Nov 15, 2024 at 05:15:23PM +0530, Srujana Challa wrote:
> Add device and driver requirements for IPsec Operation.
> 
> Signed-off-by: Srujana Challa <schalla@marvell.com>
> ---
>  device-types/crypto/description.tex        | 100 +++++++++++++++++++++
>  device-types/crypto/device-conformance.tex |   1 +
>  device-types/crypto/driver-conformance.tex |   1 +
>  3 files changed, 102 insertions(+)
> 
> diff --git a/device-types/crypto/description.tex b/device-types/crypto/description.tex
> index 9c878f7..5ca6602 100644
> --- a/device-types/crypto/description.tex
> +++ b/device-types/crypto/description.tex
> @@ -2238,3 +2238,103 @@ \subsubsection{IPSEC Service Operation}\label{sec:Device Types / Crypto Device /
>  \field{src_data_len} is the length of source data.
>  \field{dst_result} is the result plain IP packet and
>  \field{dst_data_len} is the length of it.
> +
> +\devicenormative{\paragraph}{IPsec Service Operation}{Device Types / Crypto Device / Device Operation / IPsec Service Operation}
> +
> +When the device supports IPsec operations,
> +\begin{itemize}
> +\item the device MUST set VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP, VIRTIO_CRYPTO_IPSEC_SA_CAP
> +capability in the \field{supported_caps} in the command VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY.
> +\item the device MUST support the administration commands
> +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE,
> +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY,
> +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY for the resource types
> +VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_OUTBOUND_SA and VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_INBOUND_SA.
> +\end{itemize}
> +
> +When any of the VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP or VIRTIO_CRYPTO_IPSEC_SA_CAP
> +capability is disabled, the device MUST set \field{status} to
> +VIRTIO_ADMIN_STATUS_Q_INVALID_OPCODE for the commands
> +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE,
> +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY,
> +and VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY.
> +
> +The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_EEXIST for the
> +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE when the resource \field{type}
> +is VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_OUTBOUND_SA or VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_INBOUND_SA,
> +if the object is already exists with the supplied \field{id}.

Remove `is` in last sentence.

> +
> +The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_EBUSY for the
> +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY when the resource \field{type}
> +is VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_OUTBOUND_SA or VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_INBOUND_SA,
> +if the object is in use.
> +
> +The device MUST fail the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE with
> +the \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL, for the
> +VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_OUTBOUND_SA object if,
> +\begin{itemize}
> +\item \field{id} is greater than or equal to \field{outb_sa_limit}.
> +\item the supplied SA parameters, such as mode, options, cipher and authentication
> +      algorithms is not supported in the capabitlity VIRTIO_CRYPTO_IPSEC_SA_CAP.

s/is/are

> +\end{itemize}
> +
> +The device MUST fail the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE with
> +the \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL, for the
> +VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_INBOUND_SA object if,
> +\begin{itemize}
> +\item \field{id} is greater than or equal to \field{inb_sa_limit}.
> +\item the supplied SA parameters, such as mode, options, cipher and authentication
> +      algorithms is not supported in the capabitlity VIRTIO_CRYPTO_IPSEC_SA_CAP.

s/is/are

> +\end{itemize}
> +
> +The device SHOULD maintain a table for subsequent lookups for inbound/outbound data
> +processing with the corresponding SA based on the supplied \field{id}.
> +
> +The device MUST allow recreating the resource objects using the command
> +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE which was previously destroyed using
> +the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY respectively without
> +undergoing a device reset.
> +
> +The device MAY fail the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE with
> +the \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL for the
> +VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_OUTBOUND_SA or VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_INBOUND_SA
> +commands if the resource object with the same \field{spi} already exists.
> +
> +On device reset, the device MUST destroy all the resource objects which have been created.
> +
> +The device MUST copy the result of IPsec operation in the \field{dst_data[]}.
> +The device MUST set the \field{status} field in struct virtio_crypto_inhdr to
> +one of the following values of enum VIRTIO_CRYPTO_STATUS:
> +\begin{itemize*}
> +\item VIRTIO_CRYPTO_OK if the operation success.
> +\item VIRTIO_CRYPTO_NOTSUPP if the requested algorithm or operation is unsupported.
> +\item VIRTIO_CRYPTO_BADMSG if the integrity check is failed for IPsec decryption.
> +\item VIRTIO_CRYPTO_INVSESS if the session ID invalid.
> +\item VIRTIO_CRYPTO_ERR if any failure not mentioned above occurs.
> +\end{itemize*}
> +
> +\drivernormative{\paragraph}{IPsec Service Operation}{Device Types / Crypto Device / Device Operation / IPsec Service Operation}
> +
> +The driver MUST query the capabilities using VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY
> +to discover the capability types the device offers.
> +
> +The driver MUST get VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP and VIRTIO_CRYPTO_IPSEC_SA_CAP
> +if listed in VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY command result, using
> +VIRTION_ADMIN_CMD_DEVICE_CAP_GET to discover the capabilities the device is
> +able to offer.
> +The driver MUST set VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP and VIRTIO_CRYPTO_IPSEC_SA_CAP
> +using VIRTIO_ADMIN_CMD_DEVICE_CAP_SET to indicate the device which capability
> +the driver uses.
> +
> +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, when creating a resource
> +VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_OUTBOUND_SA, the driver MUST set all the parameters
> +in \field struct virtio_crypto_resource_obj_ipsec_sa with relevant values.
> +And when create a resource object VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_INBOUND_SA,
> +the driver MUST set all the parameters except
> +\field struct virtio_crypto_ipsec_tunnel_param.
> +
> +The driver MUST set \field{session_id} in struct virtio_crypto_op_header to a
> +valid VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_OUTBOUND_SA or
> +VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_INBOUND_SA \field{id} .

Remove space at the end.

> +The driver MUST set the \field{opcode} field in struct virtio_crypto_op_header
> +to one of VIRTIO_CRYPTO_IPSEC_OUTBOUND and VIRTIO_CRYPTO_IPSEC_INBOUND.
> diff --git a/device-types/crypto/device-conformance.tex b/device-types/crypto/device-conformance.tex
> index 1667120..5d1c59f 100644
> --- a/device-types/crypto/device-conformance.tex
> +++ b/device-types/crypto/device-conformance.tex
> @@ -10,4 +10,5 @@
>  \item \ref{devicenormative:Device Types / Crypto Device / Device Operation / MAC Service Operation}
>  \item \ref{devicenormative:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation}
>  \item \ref{devicenormative:Device Types / Crypto Device / Device Operation / AEAD Service Operation}
> +\item \ref{devicenormative:Device Types / Crypto Device / Device Operation / IPsec Service Operation}
>  \end{itemize}
> diff --git a/device-types/crypto/driver-conformance.tex b/device-types/crypto/driver-conformance.tex
> index 672d0f6..4083ea4 100644
> --- a/device-types/crypto/driver-conformance.tex
> +++ b/device-types/crypto/driver-conformance.tex
> @@ -11,4 +11,5 @@
>  \item \ref{drivernormative:Device Types / Crypto Device / Device Operation / MAC Service Operation}
>  \item \ref{drivernormative:Device Types / Crypto Device / Device Operation / Symmetric algorithms Operation}
>  \item \ref{drivernormative:Device Types / Crypto Device / Device Operation / AEAD Service Operation}
> +\item \ref{drivernormative:Device Types / Crypto Device / Device Operation / IPsec Service Operation}
>  \end{itemize}
> -- 
> 2.25.1
> 
>