Re: [PATCH RFC 2/4] virtio-crypto: Add resource objects for IPsec outbound and inbound SAs

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

On Fri, Nov 15, 2024 at 05:15:21PM +0530, Srujana Challa wrote:
> This commit introduces resource objects to enable the driver/device to
> create IPsec Security Associations (SAs) for both inbound and outbound
> directions.
> 
> The IPsec SA objects include essential parameters required for packet
> outbound and inbound processing, such as SPI, tunnel headers, IPsec mode,
> IPsec options and cipher/authentication specific data.
> 
> Signed-off-by: Srujana Challa <schalla@marvell.com>
> ---
>  device-types/crypto/description.tex | 133 ++++++++++++++++++++++++++++
>  1 file changed, 133 insertions(+)
> 
> diff --git a/device-types/crypto/description.tex b/device-types/crypto/description.tex
> index ce4b1fb..7ac6f5b 100644
> --- a/device-types/crypto/description.tex
> +++ b/device-types/crypto/description.tex
> @@ -334,6 +334,20 @@ \subsection{Device and driver capabilities}\label{sec:Device Types / Crypto Devi
>  \hline
>  \end{tabularx}
>  
> +\subsection{Device resource objects}\label{sec:Device Types / Crypto Device / Device resource objects}
> +
> +The crypto device has the following resource objects.
> +
> +\begin{tabularx}{\textwidth}{ |l||l|X| }
> +\hline
> +type & Name & Description \\
> +\hline \hline
> +0x0200 & \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-OUTBOUND-SA]{VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_OUTBOUND_SA} & IPsec outbound SA resource object \\
> +\hline
> +0x0201 & \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-INBOUND-SA]{VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_INBOUND_SA} & IPsec inbound SA resource object \\
> +\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.
> @@ -2026,3 +2040,122 @@ \subsubsection{IPSEC Service Operation}\label{sec:Device Types / Crypto Device /
>  \end{tabularx}
>  \end{table}
>  
> +\paragraph{Resource objects}
> +\label{par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects}
> +
> +\subparagraph{VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_OUTBOUND_SA}\label{par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-OUTBOUND-SA}
> +
> +A driver can have outbound SAs between 0 and \field{outb_sa_limit}, as specified by the
> +capability VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP. For the IPsec outbound SA resource object
> +\field{resource_obj_specific_data} is in the format
> +\field{struct virtio_crypto_resource_obj_ipsec_sa}.
> +
> +\begin{lstlisting}
> +struct virtio_crypto_ipsec_tunnel_param {
> +        /* Tunnel type: IPv4 or IPv6 */
> +        u8 type;
> +        u8 reserved[3];
> +        union {
> +                /* IPv4 tunnel header parameters */
> +                struct {
> +                        /* IPv4 source address */
> +                        struct in_addr src_ip;
> +                        /* IPv4 destination address */
> +                        struct in_addr dst_ip;
> +                        /* IPv4 Differentiated Services Code Point */
> +                        uint8_t dscp;
> +                        /* IPv4 Don't Fragment bit */
> +                        uint8_t df;
> +                        /* IPv4 Time To Live */
> +                        uint8_t ttl;
> +                } ipv4;
> +                /* IPv6 tunnel header parameters */
> +                struct {
> +                        /* IPv6 source address */
> +                        struct in6_addr src_addr;
> +                        /* IPv6 destination address */
> +                        struct in6_addr dst_addr;
> +                        /* IPv6 flow label */
> +                        uint32_t flabel;
> +                        /* IPv6 hop limit */
> +                        uint8_t hlimit;
> +                        /* IPv6 Differentiated Services Code Point */
> +                        uint8_t dscp;
> +                } ipv6;
> +        };
> +};
> +
> +struct virtio_crypto_resource_obj_ipsec_sa {
> +        le32 spi;
> +        le32 salt;
> +        le64 options;
> +        struct virtio_crypto_ipsec_tunnel_param param;
> +        le64 esn;
> +        le16 udp_sport;
> +        le16 udp_dport;
> +        le32 replay_win_sz;
> +        le64 cipher_algo;
> +        struct {
> +            u8 *data;
> +            le16 length;
> +        } cipher_key;
> +        le64 auth_algo;
> +        struct {
> +            u8 *data;
> +            le16 length;
> +        } auth_key;
> +        le32 obj_id;
> +        u8 mode;
> +        u8 direction;
> +}
> +\end{lstlisting}
> +
> +\field{spi} is the Security Parameter Index(SPI) used to uniquely identify the IPsec SA.
> +\field{salt} is the 32 bit salt value used in the cryptographic operations. 
> +
> +\field{options} specifies the Options for configuring the IPsec SA, see
> +\ref{table:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Device and driver capabilities / VIRTIO-CRYPTO-IPSEC-SA-CAP / IPsec Options}.
> +
> +\field{param} specifies the parameters for IPsec tunnel mode.
> +\field{esn} is the starting sequence number.
> +\field{udp_sport} is the source port for UDP encapsulation. \field{udp_dport} is the
> +destination port for UDP encapsulation.
> +\field{replay_win_sz} is the anti-replay window size to enable sequence replay attack
> +handling, replay checking is disabled if the window size is 0.
> +
> +\field{cipher_algo} is the cipher algorithm identifier
> +see \ref{sec:Device Types / Crypto Device / Supported crypto services  / CIPHER services}
> +\field{cipher_key} specifies the cipher key and it's length.

s/it's/its

> +\field{auth_algo} is the Authentication algorithm identifier
> +\field{auth_key} specifies the authentication key data and its length.
> +\field{obj_id} specifies the object id of the SA that can be used to retrieve
> +driver-defined data associated with the IPsec SA.
> +
> +\field{mode} specifies the mode of the IPsec SA, see
> +\ref{table:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Device and driver capabilities / VIRTIO-CRYPTO-IPSEC-SA-CAP / IPsec Modes}.
> +
> +\field{direction} specifies IPsec SA direction, see
> +\ref{table:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-OUTBOUND-SA / IPsec Direction}.
> +
> +\begin{table}[H]
> +\caption{IPsec Direction}
> +\label{table:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Device and driver capabilities / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-OUTBOUND-SA / IPsec Direction}
> +\begin{tabularx}{\textwidth}{ |l|X|X| }
> +\hline
> +Type & Name & Description \\
> +\hline \hline
> +0x0 & - & Reserved \\
> +\hline
> +0x1 & VIRTIO_CRYPTO_IPSEC_DIR_OUTBOUND & IPsec direction outbound \\
> +\hline
> +0x2 & VIRTIO_CRYPTO_IPSEC_DIR_INBOUND & IPsec direction inbound \\
> +\hline
> +\end{tabularx}
> +\end{table}
> +
> +\subparagraph{VIRTIO_CRYPTO_RESOURCE_OBJ_IPSEC_INBOUND_SA}\label{par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-INBOUND-SA}
> +
> +A driver can have inbound SAs between 0 and \field{inb_sa_limit}, as specified by the
> +capability VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP. For the IPsec inbound SA resource object
> +\field{resource_obj_specific_data} is in the format
> +\field{struct virtio_crypto_resource_obj_ipsec_sa}.
> -- 
> 2.25.1
> 
>