RE: [PATCH RFC v6 1/4] virtio-crypto: Add IPsec service operation and Capabilities

> From: Srujana Challa <[email protected]>
> Sent: Thursday, April 24, 2025 3:01 PM
> 
> This commit introduces the IPsec service operation to the Crypto device,
> enabling offloading of IPsec processing.
> 
> Capabilities:
> 
> 1. IPsec Resource Capability (VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP):
>    Indicates the device's IPsec resource limits, such as the number of
>    outbound and inbound Security Associations (SAs).
> 2. IPsec SA Capability (VIRTIO_CRYPTO_IPSEC_SA_CAP): Specifies the
>    supported IPsec modes, along with the supported cryptographic
>    algorithms, authentication algorithms, IPsec options and
>    anti-replay window size.
> 
> Signed-off-by: Srujana Challa <[email protected]>
> ---
>  device-types/crypto/description.tex | 174 +++++++++++++++++++++++++++-
>  introduction.tex                    |  12 ++
>  2 files changed, 181 insertions(+), 5 deletions(-)
> 
> diff --git a/device-types/crypto/description.tex b/device-
> types/crypto/description.tex
> index e053cc7..f4978f0 100644
> --- a/device-types/crypto/description.tex
> +++ b/device-types/crypto/description.tex
> @@ -2,13 +2,15 @@ \section{Crypto Device}\label{sec:Device Types / Crypto
> Device}
> 
>  The virtio crypto device is a virtual cryptography device as well as a  virtual
> cryptographic accelerator. The virtio crypto device provides the -following
> crypto services: CIPHER, MAC, HASH, AEAD and AKCIPHER. Virtio crypto -
> devices have a single control queue and at least one data queue. Crypto -
> operation requests are placed into a data queue, and serviced by the -device.
> Some crypto operation requests are only valid in the context of a -session.
> The role of the control queue is facilitating control operation
> +following crypto services: CIPHER, MAC, HASH, AEAD, AKCIPHER and IPSEC.
> +Virtio crypto devices have a single control queue and at least one data
> +queue. Crypto operation requests are placed into a data queue, and
> +serviced by the device. Some crypto operation requests are only valid
> +in the context of a session. The role of the control queue is
> +facilitating control operation
>  requests. Sessions management is realized with control operation  requests.
> +The crypto device may have administration command interface through
> +which IPsec service capabilities and resources are configured.
> 
>  \subsection{Device ID}\label{sec:Device Types / Crypto Device / Device ID}
> 
> @@ -72,6 +74,8 @@ \subsection{Supported crypto services}\label{sec:Device
> Types / Crypto Device /
>  #define VIRTIO_CRYPTO_SERVICE_AEAD   3
>  /* AKCIPHER (Asymmetric Key Cipher) service */  #define
> VIRTIO_CRYPTO_SERVICE_AKCIPHER 4
> +/* IPSEC service */
> +#define VIRTIO_CRYPTO_SERVICE_IPSEC  5
>  \end{lstlisting}
> 
>  The above constants designate bits used to indicate the which of crypto
> services are @@ -318,6 +322,20 @@ \subsection{Device
> Initialization}\label{sec:Device Types / Crypto Device / Devi  \item The driver
> MUST read the supported algorithms based on \field{crypto_services} field.
>  \end{itemize*}
> 
> +\subsection{Device and driver capabilities}\label{sec:Device Types /
> +Crypto Device / Device and driver capabilities}
> +
> +The crypto device has the following capabilities.
> +
> +\begin{tabularx}{\textwidth}{ |l||l|X| } \hline Identifier & Name &
> +Description \\ \hline \hline
> +0x0800 & \hyperref[par:Device Types / Crypto Device / Device Operation
> +/ IPsec Service Operation / Device and driver capabilities /
> +VIRTIO-CRYPTO-IPSEC-RESOURCE-
> CAP]{VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP} &
> +IPsec resource capability \\ \hline
> +0x0801 & \hyperref[par:Device Types / Crypto Device / Device Operation
> +/ IPsec Service Operation / Device and driver capabilities /
> +VIRTIO-CRYPTO-IPSEC-SA-CAP]{VIRTIO_CRYPTO_IPSEC_SA_CAP} & IPsec
> +Security Association(SA) capability \\ \hline \end{tabularx}
> +
>  \subsection{Device Operation}\label{sec:Device Types / Crypto Device /
> Device Operation}
> 
>  The operation of a virtio crypto device is driven by requests placed on the
> virtqueues.
> @@ -1872,3 +1890,149 @@ \subsubsection{AKCIPHER Service
> Operation}\label{sec:Device Types / Crypto Devic  \item VIRTIO_CRYPTO_ERR
> if any failure not mentioned above occurs.
>  \end{itemize*}
>  \end{itemize*}
> +
> +\subsubsection{IPSEC Service Operation}\label{sec:Device Types / Crypto
> +Device / Device Operation / IPSEC Service Operation}
> +
> +A crypto device can support the processing of IPsec protocol operations.
> +In addition to standard crypto processing, the IPsec protocol
> +operations are also handled by the crypto device as a lookaside operation.
> +
> +IPsec Inbound processing: The device performs decryption,
> +authentication, integrity checking and remove additional headers,
> +including tunnel header if in tunnel mode, as well as the ESP/AH header on
> the given packet(See \hyperref[intro:IPSEC]{IPSEC} RFC).
> +The resulting packet contains only the plain data.
> +
> +IPsec Outbound processing: The device performs encryption, attach ICV,
> +update/add IP header and add ESP/AH header/trailer. The resulting
> +packet contains encrypted data along with the IPsec header and trailer.
> +
> +A crypto device can support number of IPsec SAs, allowing it to manage
> +multiple secure connections simultaneously.
> +
> +The device and the driver indicate IPsec SA resource limits using the
> +VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP capability specifying the limits on
> +the number of IPsec outbound and inbound SA resource objects.
> +The VIRTIO_CRYPTO_IPSEC_SA_CAP capability  specifies the IPsec protocol
> +capabilities supported by the device. The driver indicates the IPsec
> +parameters by setting VIRTIO_CRYPTO_IPSEC_SA_CAP capability prior to
> adding any resource object.
> +
> +The driver controls the IPsec SA resource object using administration
> +commands described in \ref{sec:Basic Facilities of a Virtio Device / Device
> groups / Group administration commands / Device resource objects}.
> +
> +\paragraph{Device and driver capabilities} \label{par:Device Types /
> +Crypto Device / Device Operation / IPsec Service Operation / Device and
> +driver capabilities}
> +
> +\subparagraph{VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP}
> +\label{par:Device Types / Crypto Device / Device Operation / IPsec
> +Service Operation / Device and driver capabilities /
> +VIRTIO-CRYPTO-IPSEC-RESOURCE-CAP}
> +
> +The VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP capability indicates the IPsec SA
> resource limits.
> +\field{cap_specific_data} is in the format \field{struct
> +virtio_crypto_ipsec_resource_cap}.
> +
> +\begin{lstlisting}
> +struct virtio_crypto_ipsec_resource_cap {
> +        le32 inb_sa_limit;
> +        le32 outb_sa_limit;
> +};
> +\end{lstlisting}
> +
> +\field{inb_sa_limit}, and \field{outb_sa_limit} denote the maximum
> +number of IPsec security Associations (SAs) that can be utilized for
> +IPsec inbound and outbound processing, respectively, which the device is
> capable of creating.
> +
> +\subparagraph{VIRTIO_CRYPTO_IPSEC_SA_CAP}
> +\label{par:Device Types / Crypto Device / Device Operation / IPsec
> +Service Operation / Device and driver capabilities /
> +VIRTIO-CRYPTO-IPSEC-SA-CAP}
> +
> +The VIRTIO_CRYPTO_IPSEC_SA_CAP capability lists the supported IPsec
> +modes along with the supported cryptographic, authentication algorithms
> +and anti-replay window size for each IPsec mode.
> +\field{cap_specific_data} is in the format \field{struct
> virtio_crypto_ipsec_sa_cap_data}.
> +
> +\begin{lstlisting}[label={lst:Device Types / Crypto Device / Device
> +Operation / IPsec Service Operation / Device and driver capabilities / VIRTIO-
> CRYPTO-IPSEC-SA-CAP / virtio-crypto-ipsec-mode-cap}] struct
> virtio_crypto_ipsec_mode_cap {
> +        u8 mode;
> +        u8 reserved[3];
> +        le32 max_replay_win_sz;
> +        le32 options;
> +        le32 reserved1;
> +        le64 cipher_algo;
> +        le64 hmac_algo;
> +        le32 aead_algo;
> +        le32 max_cipher_key_len;
> +        le32 max_auth_key_len;
> +};
> +
> +struct virtio_crypto_ipsec_sa_cap_data {
> +        u8 count;
> +        u8 reserved[7];
> +        struct virtio_crypto_ipsec_mode_cap cap_mode[]; };
> +\end{lstlisting}
> +
> +\field{count} indicates number of valid entries in the \field{mode} array.
> +\field{cap_mode[]} is an array of supported IPsec modes. Within each array
> entry:
> +
> +\field{mode} specifies the IPsec mode, as defined in table
> +\ref{table:Device Types / Crypto Device / Device Operation / IPsec Service
> Operation / Device and driver capabilities / VIRTIO-CRYPTO-IPSEC-SA-CAP /
> IPsec Modes}.
> +\field{max_replay_win_sz} specifies the maximum anti-replay window size
> the device supports.
> +This field is applicable only for inbound operation.
> +
> +\field{options} Each bit indicates the IPsec protocol options supported
> +by the device, as defined in table \ref{table:Device Types / Crypto Device /
> Device Operation / IPsec Service Operation / Device and driver capabilities /
> VIRTIO-CRYPTO-IPSEC-SA-CAP / IPsec Options}.
> +
> +\field{cipher_algo} CIPHER algorithms mask, see \ref{sec:Device Types /
> Crypto Device / Supported crypto services  / CIPHER services}.
> +
> +\field{hmac_algo} HMAC algorithms mask, see \ref{sec:Device Types /
> Crypto Device / Supported crypto services  / MAC services}.
> +
> +\field{aead_algo} AEAD algorithms mask, see \ref{sec:Device Types / Crypto
> Device / Supported crypto services  / AEAD services}.
> +
> +\field{max_cipher_key_len} is the maximum length of cipher key supported
> by the device.
> +
> +\field{max_auth_key_len} is the maximum length of authentication key
> supported by the device.
> +
> +\begin{table}[H]
> +\caption{IPsec Modes}
> +\label{table:Device Types / Crypto Device / Device Operation / IPsec
> +Service Operation / Device and driver capabilities /
> +VIRTIO-CRYPTO-IPSEC-SA-CAP / IPsec Modes} \begin{tabularx}{\textwidth}{
> +|l|X|X| } \hline Type & Name & Description \\ \hline \hline
> +0x0 & - & Reserved \\
> +\hline
> +0x1 & VIRTIO_CRYPTO_IPSEC_MODE_ESP_TUNNEL & IPsec ESP protocol in
> +tunnel mode \\ \hline
> +0x2 & VIRTIO_CRYPTO_IPSEC_MODE_ESP_TRANSPORT & IPsec ESP protocol
> in
> +transport mode \\ \hline
> +0x3 & VIRTIO_CRYPTO_IPSEC_MODE_AH_TUNNEL & IPsec AH protocol in
> tunnel
> +mode \\ \hline
> +0x4 & VIRTIO_CRYPTO_IPSEC_MODE_AH_TRANSPORT & IPsec AH protocol
> in
> +transport mode \\ \hline \end{tabularx} \end{table}
> +
> +See \hyperref[intro:IPSEC]{IPSEC} for more information on tunnel and
> transport modes in ESP/AH IPsec processing.
> +
> +\begin{table}[H]
> +\caption{IPsec Options}
> +\label{table:Device Types / Crypto Device / Device Operation / IPsec
> +Service Operation / Device and driver capabilities /
> +VIRTIO-CRYPTO-IPSEC-SA-CAP / IPsec Options}
> +\begin{tabularx}{\textwidth}{ |l|X|X| } \hline Bit Number & Name &
> +Description \\ \hline \hline
> +0 & VIRTIO_CRYPTO_IPSEC_ESN & Specifies whether extended sequence
> +number is supported, as described in \hyperref[intro:ESN]{ESN}\\ \hline
> +1 & VIRTIO_CRYPTO_IPSEC_UDP_ENCAP & Specifies whether udp
> encapsulation is supported, as described in
> +
> +\hyperref[intro:UDP-Encapsulation]{UDP Encapsulation}, applicable only
> +for ESP IPsec processing \\ \hline
> +2 & VIRTIO_CRYPTO_IPSEC_COPY_DSCP & Specifies whether copy dscp is
> +supported, as described in \hyperref[intro:IPSEC]{IPSEC} \\ \hline
> +3 & VIRTIO_CRYPTO_IPSEC_DEC_TTL & Specifies whether decrementing the
> +time to live is supported, as described in
> +\hyperref[intro:IPSEC]{IPSEC} \\ \hline
> +4 & VIRTIO_CRYPTO_IPSEC_COPY_DF & Specifies whether copy Don't
> Fragment
> +bit is supported, as described in \hyperref[intro:IPSEC]{IPSEC} \\
> +\hline
> +5 & VIRTIO_CRYPTO_IPSEC_ECN & Specifies whether copy Explicit
> +Congestion Notification is supported, as described in
> +\hyperref[intro:IPSEC]{IPSEC} \\ \hline
> +6 & VIRTIO_CRYPTO_IPSEC_SA_LIFETIME & Specifies whether SA lifetime
> +feature is supported, as described in \hyperref[intro:IPSEC]{IPSEC} \\
> +\hline \end{tabularx} \end{table}
> diff --git a/introduction.tex b/introduction.tex index e60298a..80aa67a 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -162,6 +162,18 @@ \section{Normative References}\label{sec:Normative
> References}
>  	\phantomsection\label{intro:TCP-Header-Format}\textbf{[TCP Header
> Format]} &
>      TCP Header Format
> 
> 	\newline\url{https://nam11.safelinks.protection.outlook.com/?url=htt
> ps%3A%2F%2Fwww.rfc-editor.org%2Frfc%2Frfc9293%23name-header-
> format&data=05%7C02%7Cparav%40nvidia.com%7C3b8e54c5374348fbea170
> 8dd8312e037%7C43083d15727340c1b7db39efd9ccc17a%7C0%7C0%7C63881
> 0839328325483%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydW
> UsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%
> 3D%7C0%7C%7C%7C&sdata=knNerVkUCIQXzImA9o0526SQ6auhXYeD4RsOzrq
> asJ0%3D&reserved=0}\\
> +	\phantomsection\label{intro:IPSEC}\textbf{[IPSEC]} &
> +    IPsec Protocol
> +
> 	\newline\url{https://nam11.safelinks.protection.outlook.com/?url=htt
> ps%3A%2F%2Fwww.rfc-
> editor.org%2Frfc%2Frfc4301&data=05%7C02%7Cparav%40nvidia.com%7C3b8
> e54c5374348fbea1708dd8312e037%7C43083d15727340c1b7db39efd9ccc17a
> %7C0%7C0%7C638810839328345601%7CUnknown%7CTWFpbGZsb3d8eyJFb
> XB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWF
> pbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=pt1JOEttI%2Bojz%2FdtElW
> Zu9e6%2BA276TM27Ouz%2Berpsq0%3D&reserved=0}\\
> +	\phantomsection\label{intro:ESP}\textbf{[ESP]} &
> +    IPsec ESP
> +
> 	\newline\url{https://nam11.safelinks.protection.outlook.com/?url=htt
> ps%3A%2F%2Fwww.rfc-
> editor.org%2Frfc%2Frfc4303&data=05%7C02%7Cparav%40nvidia.com%7C3b8
> e54c5374348fbea1708dd8312e037%7C43083d15727340c1b7db39efd9ccc17a
> %7C0%7C0%7C638810839328358078%7CUnknown%7CTWFpbGZsb3d8eyJFb
> XB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWF
> pbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=pH93zkAjlMdk2m5YVAtu5
> xPmfHE5x%2BlEFupefu1Y5Xk%3D&reserved=0}\\
> +	\phantomsection\label{intro:ESN}\textbf{[ESN]} &
> +    IPsec ESN
> +
> 	\newline\url{https://nam11.safelinks.protection.outlook.com/?url=htt
> ps%3A%2F%2Fwww.rfc-
> editor.org%2Frfc%2Frfc4304&data=05%7C02%7Cparav%40nvidia.com%7C3b8
> e54c5374348fbea1708dd8312e037%7C43083d15727340c1b7db39efd9ccc17a
> %7C0%7C0%7C638810839328370013%7CUnknown%7CTWFpbGZsb3d8eyJFb
> XB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWF
> pbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=go5pd86ZwdMI9hZIqxcYc
> RVDEQo97prGrV%2FLgl%2B49H0%3D&reserved=0}\\
> +	\phantomsection\label{intro:UDP-Encapsulation}\textbf{[UDP
> Encapsulation]} &
> +    IPsec UDP Encapsulation
> +
> +\newline\url{https://nam11.safelinks.protection.outlook.com/?url=https%
> +3A%2F%2Fwww.rfc-
> editor.org%2Frfc%2Frfc3948&data=05%7C02%7Cparav%40nvidi
> +a.com%7C3b8e54c5374348fbea1708dd8312e037%7C43083d15727340c1b7d
> b39efd9cc
> +c17a%7C0%7C0%7C638810839328381738%7CUnknown%7CTWFpbGZsb3d8
> eyJFbXB0eU1hc
> +GkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIld
> UIjoy
> +fQ%3D%3D%7C0%7C%7C%7C&sdata=KklJ0Qbwszyi3yRXMW77sz7YkiJN76Gtt
> Y7Xetxncto
> +%3D&reserved=0}\\
>  	\phantomsection\label{intro:CAN}\textbf{[CAN]} &
>      ISO 11898-1:2015 Road vehicles -- Controller area network (CAN) -- Part 1:
> Data link layer and physical signalling\\
>  	\phantomsection\label{intro:rfc8174}\textbf{[RFC8174]} &
> --
> 2.25.1

Reviewed-by: Parav Pandit <[email protected]>