RE: [PATCH RFC v5 4/4] virtio-net: Add IPsec operation device and driver requirements

> From: Srujana Challa <[email protected]>
> Sent: Thursday, April 24, 2025 3:14 PM
> 
> Add device and driver requirements for IPsec Operation.
> 
> Signed-off-by: Srujana Challa <[email protected]>
> ---
>  device-types/net/description.tex        | 83 +++++++++++++++++++++++++
>  device-types/net/device-conformance.tex |  1 +  device-types/net/driver-
> conformance.tex |  1 +
>  3 files changed, 85 insertions(+)
> 
> diff --git a/device-types/net/description.tex b/device-
> types/net/description.tex
> index 8903e03..0674bd8 100644
> --- a/device-types/net/description.tex
> +++ b/device-types/net/description.tex
> @@ -3597,6 +3597,89 @@ \subsubsection{IPsec Operation}\label{sec:Device
> Types / Network Device / Device
> 
>  See \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec
> Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-
> INBOUND-SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_INB_SA}.
> 
> +\devicenormative{\paragraph}{IPsec Operation}{Device Types / Net Device
> +/ Device Operation / IPsec Operation}
> +
> +When the device supports IPsec operations, \begin{itemize} \item the
> +device MUST set VIRTIO_NET_IPSEC_RESOURCE_CAP,
> VIRTIO_NET_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_NET_RESOURCE_OBJ_IPSEC_OUTB_SA and
> VIRTIO_NET_RESOURCE_OBJ_IPSEC_INB_SA.
> +\end{itemize}
> +
> +When any of the VIRTIO_NET_IPSEC_RESOURCE_CAP or
> +VIRTIO_NET_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 for the resource types
> +VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA and
> VIRTIO_NET_RESOURCE_OBJ_IPSEC_INB_SA.
> +
> +The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_EEXIT for the
> +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE when the
> resource
> +\field{type} is VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA or
> +VIRTIO_NET_RESOURCE_OBJ_IPSEC_INB_SA,
> +if the object already exists with the supplied \field{id}.
> +
> +The device MUST fail the command
> VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE
> +for the VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_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 are not supported in the capabitlity
> VIRTIO_NET_IPSEC_SA_CAP.
> +\end{itemize}
> +
> +The device MUST fail the command
> VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE
> +for the VIRTIO_NET_RESOURCE_OBJ_IPSEC_INB_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 are not supported in the capabitlity
> VIRTIO_NET_IPSEC_SA_CAP.
> +\end{itemize}
> +
> +The device SHOULD maintain a table for subsequent lookups to
> +inbound/outbound data 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_OUTB_SA or
> +VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_INB_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.
> +
> +\drivernormative{\paragraph}{IPsec Operation}{Device Types / Net Device
> +/ Device Operation / IPsec 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_NET_IPSEC_RESOURCE_CAP and
> +VIRTIO_NET_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_NET_IPSEC_RESOURCE_CAP and
> +VIRTIO_NET_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_NET_RESOURCE_OBJ_IPSEC_OUTB_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_NET_RESOURCE_OBJ_IPSEC_INB_SA,
> +the driver MUST set all the parameters except \field{struct
> +virtio_crypto_ipsec_tunnel_param}.
> +
> +The driver SHOULD NOT add multiple inbound SA objects with the same
> \field{spi}.
> +
> +In the outbound data path, the driver MUST ensure that packets do not
> +exceed the PMTU prior to transmission to the device.
> +(Refer to \hyperref[intro:IPSEC]{[IPSEC]} for a detailed description of
> +PMTU)
> +
>  \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
> Types / Network Device / Legacy Interface: Framing Requirements}
> 
> diff --git a/device-types/net/device-conformance.tex b/device-
> types/net/device-conformance.tex
> index d88484c..7fe8505 100644
> --- a/device-types/net/device-conformance.tex
> +++ b/device-types/net/device-conformance.tex
> @@ -18,4 +18,5 @@
>  \item \ref{devicenormative:Device Types / Network Device / Device
> Operation / Control Virtqueue / Device Statistics}  \item
> \ref{devicenormative:Device Types / Network Device / Device Operation /
> Control Virtqueue / RSS Context}  \item \ref{devicenormative:Device Types /
> Network Device / Device Operation / Flow filter}
> +\item \ref{devicenormative:Device Types / Network Device / Device
> +Operation / IPsec Operation}
>  \end{itemize}
> diff --git a/device-types/net/driver-conformance.tex b/device-
> types/net/driver-conformance.tex
> index d346b88..0d20190 100644
> --- a/device-types/net/driver-conformance.tex
> +++ b/device-types/net/driver-conformance.tex
> @@ -18,4 +18,5 @@
>  \item \ref{drivernormative:Device Types / Network Device / Device Operation
> / Control Virtqueue / Device Statistics}  \item \ref{drivernormative:Device
> Types / Network Device / Device Operation / Control Virtqueue / RSS Context}
> \item \ref{drivernormative:Device Types / Network Device / Device Operation
> / Flow filter}
> +\item \ref{drivernormative:Device Types / Network Device / Device
> +Operation / IPsec Operation}
>  \end{itemize}
> --
> 2.25.1
Reviewed-by: Parav Pandit <[email protected]>