Skip to contentSkip to conversation

introduce IPsec Operation in virtio-net

RFC PATCH Superseded Srujana Challa 2 participants 10 messages Apr 24, 2025 – Apr 28, 2025

v5 of 7 Superseded Latest is v7 →

lore
Share & tools
lore
#0 lore raw

v5 cover introduce IPsec Operation in virtio-net

This series enhances virtio-net by adding support for IPsec Operation. These patches aim to extend the capabilities of virtio-net, enabling it to handle IPsec operations efficiently. This enables the offloading of IPsec processing, both before transmission and after reception, thereby providing inline offload capabilities.

It is using new virtio basic facilities of capability and resource objects. Below is a summary of the changes introduced:

Patch1:
This patch introduces the foundational support for IPsec within the virtio-net framework, outlining the necessary capabilities and resource objects for IPsec operations.

Patch2:
This patch introduces a new selector and action necessary for IPsec processing, leveraging flow filter actions.

Patch3:
This patch introduces new fields in "struct virtio_net_hdr" to to support IPsec functionality.

Patch4:
This patch specifies the requirements for both the device and the driver to support IPsec operations.

These enhancements are for providing support for IPsec within the virtio-net device/driver, improving security and performance for virtualized environments. We believe these additions will significantly benefit users who rely on virtio-net for secure data transmission.

This series references the Virtio-crypto IPsec service operation capabilities and resource objects data structures, and cryptographic algorithm definitions to avoid duplication, however the admin command type value differs between Virtio-crypto and Virtio-net.

depends-on: https://lore.kernel.org/virtio-comment/[email protected]/
depends-on: https://lore.kernel.org/virtio-comment/[email protected]/

v2:
- Addressed the review comments from Parav Pandit.
v3:
- Introduced VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN flag in the virtio_net_hdr:flags.
- Addressed the review comments from Parav Pandit.
v4:
- Rebased this series on VIRTIO_NET_F_OUT_NET_HEADER patch.

Srujana Challa (4):
virtio-net: Add IPsec operation, capabilities and resource objects
virtio-net: Add new flow filter selector and action for IPsec
virtio-net: extend virtio_net_hdr for IPsec support
virtio-net: Add IPsec operation device and driver requirements

 device-types/net/description.tex        | 210 +++++++++++++++++++++++-
 device-types/net/device-conformance.tex |   1 +
 device-types/net/driver-conformance.tex |   1 +
 3 files changed, 207 insertions(+), 5 deletions(-)
Signature · 1 line
2.25.1
#1 lore raw

RFC PATCH v5 1/4 virtio-net: Add IPsec operation, capabilities and resource objects

This commit introduces the IPsec Operation to the Net device along with the capabilities and resource objects. This enables the offloading of IPsec processing, both before transmission and after reception, thereby providing inline offload capabilities.

Capbilities:

1. IPsec Resource Capability (VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP):
Indicates the device's IPsec resource limits, such as the number of encryption and decryption 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.

Resource objects:
1. VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA
2. VIRTIO_NET_RESOURCE_OBJ_IPSEC_INB_SA

These IPsec SA resource objects encompass parameters necessary for packet encryption and decryption. These include the SPI, tunnel headers, IPsec mode, IPsec options, and metadata specific to cipher and authentication.

This patch refers the Virtio-crypto IPsec service operation capabilities and resource objects data structures and crypto algorithm definitions to avoid duplication, however the admin command type vaule differs between Virtio-crypto and Virtio-net.

---
 device-types/net/description.tex | 52 ++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
device-types/net/description.tex +52 -0
index 0bb1cef..d918c55 100644
@@ -140,6 +140,11 @@ \subsection{Feature bits}\label{sec:Device Types / Network Device / Feature bits
 \item[VIRTIO_NET_F_OUT_NET_HEADER(69)] Driver can provide the start of
  \field{outer_nh_offset} value. Device gains advantage by not reading packet
   to calculate outer network header offset.
+
+\item[VIRTIO_NET_F_IPSEC(70)] Device supports inline IPsec processing.
+ \field{struct virtio_net_hdr} size expands upto field \field{sturct ipsec_resource_hdr}
+ when VIRTIO_NET_F_IPSEC is negotiated.
+
 \end{description}
 
 \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device / Feature bits / Feature bit requirements}
@@ -462,6 +467,10 @@ \subsection{Device and driver capabilities}\label{sec:Device Types / Network Dev
 \hline
 0x0802 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP]{VIRTIO_NET_FF_ACTION_CAP} & Flow filter action capability \\
 \hline
+0x0803 & \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Device and driver capabilities / VIRTIO-CRYPTO-IPSEC-RESOURCE-CAP]{VIRTIO_NET_IPSEC_RESOURCE_CAP} & IPsec resource capability \\
+\hline
+0x0804 & \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Device and driver capabilities / VIRTIO-CRYPTO-IPSEC-SA-CAP]{VIRTIO_NET_IPSEC_SA_CAP} & IPsec Security Association(SA) capability \\
+\hline
 \end{tabularx}
 
 \subsection{Device resource objects}\label{sec:Device Types / Network Device / Device resource objects}
@@ -478,6 +487,10 @@ \subsection{Device resource objects}\label{sec:Device Types / Network Device / D
 \hline
 0x0202 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-RULE]{VIRTIO_NET_RESOURCE_OBJ_FF_RULE} & Flow filter rule object \\
 \hline
+0x0203 & \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-OUTBOUND-SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA} & IPsec outbound SA resource object \\
+\hline
+0x0204 & \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} & IPsec inbound SA resource object \\
+\hline
 \end{tabularx}
 
 \subsection{Device parts}\label{sec:Device Types / Network Device / Device parts}
@@ -3480,6 +3493,45 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope
 capability and the classifier object, unless the VIRTIO_NET_FF_MASK_F_PARTIAL_MASK
 is enabled.
 
+\subsubsection{IPsec Operation}\label{sec:Device Types / Network Device / Device Operation / IPsec Operation}
+
+A network device can support the processing of IPsec operations when
+VIRTIO_NET_F_IPSEC feature is negotiated. In addition to standard packet
+processing, the IPsec protocol processing is also handled by the network device.
+This occurs both pre-transmit and post-receive, providing inline IPsec capabilities.
+
+IPsec Inbound processing: In receive path 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 from the packet
+(See \hyperref[intro:IPSEC]{[IPSEC]}). The resulting packet contains only the plain data.
+
+IPsec Outbound processing: In transmit path the device performs encryption,
+attach ICV, update/add IP header and add ESP/AH header/trailer to the packet
+and transmit.
+
+\paragraph{Device and driver capabilities}
+\label{par:Device Types / Network Device / Device Operation / IPsec Operation / Device and driver capabilities}
+
+The device and the driver indicate IPsec SA resource limits using the capability
+\hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Device and driver capabilities / VIRTIO-CRYPTO-IPSEC-RESOURCE-CAP]{VIRTIO_NET_IPSEC_RESOURCE_CAP}
+The \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Device and driver capabilities / VIRTIO-CRYPTO-IPSEC-SA-CAP]{VIRTIO_NET_IPSEC_SA_CAP}
+capability specifies which IPsec protocol capabilities the device supports. The driver indicates
+the IPsec parameters by setting the IPsec SA capability prior to adding any resource objects.
+
+\paragraph{Resource objects}
+\label{par:Device Types / Network Device / Device Operation / IPsec Operation / Resource objects}
+
+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}.
+
+The IPsec SA resource object contains necessary parameters for packet
+encryption and decryption. These include the SPI, tunnel headers, IPsec mode,
+IPsec options, and data specific to cipher and authentication.
+
+See \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-OUTBOUND-SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA}.
+
+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}.
+
 \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 Types / Network Device / Legacy Interface: Framing Requirements}
 
Signature · 1 line
2.25.1
Reviewed-by on v5 1/4
#2 lore raw

RE: [PATCH RFC v5 1/4] virtio-net: Add IPsec operation, capabilities and resource objects

Quoted 155 lines

From: Srujana Challa <[email protected]>
Sent: Thursday, April 24, 2025 3:13 PM

This commit introduces the IPsec Operation to the Net device along with the capabilities and resource objects. This enables the offloading of IPsec processing, both before transmission and after reception, thereby providing inline offload capabilities.

Capbilities:

1. IPsec Resource Capability (VIRTIO_CRYPTO_IPSEC_RESOURCE_CAP):
Indicates the device's IPsec resource limits, such as the number of encryption and decryption 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.

Resource objects:
1. VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA
2. VIRTIO_NET_RESOURCE_OBJ_IPSEC_INB_SA

These IPsec SA resource objects encompass parameters necessary for packet encryption and decryption. These include the SPI, tunnel headers, IPsec mode, IPsec options, and metadata specific to cipher and authentication.

This patch refers the Virtio-crypto IPsec service operation capabilities and resource objects data structures and crypto algorithm definitions to avoid duplication, however the admin command type vaule differs between Virtio- crypto and Virtio-net.

---
 device-types/net/description.tex | 52 ++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
device- renamed from device-types/net/description.tex +0 -0

types/net/description.tex
index 0bb1cef..d918c55 100644

device-types/net/description.tex +0 -0
@@ -140,6 +140,11 @@ \subsection{Feature bits}\label{sec:Device Types /

Network Device / Feature bits \item[VIRTIO_NET_F_OUT_NET_HEADER(69)] Driver can provide the start of
\field{outer_nh_offset} value. Device gains advantage by not reading packet
to calculate outer network header offset.

device-types/net/description.tex +5 -0
+
+\item[VIRTIO_NET_F_IPSEC(70)] Device supports inline IPsec processing.
+ \field{struct virtio_net_hdr} size expands upto field \field{sturct
+ipsec_resource_hdr}  when VIRTIO_NET_F_IPSEC is negotiated.
+
 \end{description}
 
 \subsubsection{Feature bit requirements}\label{sec:Device Types / Network

Device / Feature bits / Feature bit requirements} @@ -462,6 +467,10 @@ \subsection{Device and driver capabilities}\label{sec:Device Types / Network Dev \hline
0x0802 & \hyperref[par:Device Types / Network Device / Device Operation /
Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION- CAP]{VIRTIO_NET_FF_ACTION_CAP} & Flow filter action capability \\ \hline +0x0803 & \hyperref[par:Device Types / Crypto Device / Device Operation

device-types/net/description.tex +2 -0
+/ IPsec Service Operation / Device and driver capabilities /
+VIRTIO-CRYPTO-IPSEC-RESOURCE-CAP]{VIRTIO_NET_IPSEC_RESOURCE_CAP}

&

device-types/net/description.tex +5 -0
+IPsec resource capability \\ \hline
+0x0804 & \hyperref[par:Device Types / Crypto Device / Device Operation
+/ IPsec Service Operation / Device and driver capabilities /
+VIRTIO-CRYPTO-IPSEC-SA-CAP]{VIRTIO_NET_IPSEC_SA_CAP} & IPsec Security
+Association(SA) capability \\ \hline
 \end{tabularx}
 
 \subsection{Device resource objects}\label{sec:Device Types / Network

Device / Device resource objects} @@ -478,6 +487,10 @@ \subsection{Device resource objects}\label{sec:Device Types / Network Device / D \hline
0x0202 & \hyperref[par:Device Types / Network Device / Device Operation /
Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF- RULE]{VIRTIO_NET_RESOURCE_OBJ_FF_RULE} & Flow filter rule object \\
\hline
+0x0203 & \hyperref[par:Device Types / Crypto Device / Device Operation

device-types/net/description.tex +2 -0
+/ IPsec Service Operation / Resource objects /
+VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-OUTBOUND-

SA]{VIRTIO_NET_RESOURCE_OBJ_I

device-types/net/description.tex +4 -0
+PSEC_OUTB_SA} & IPsec outbound SA resource object \\ \hline
+0x0204 & \hyperref[par:Device Types / Crypto Device / Device Operation
+/ IPsec Service Operation / Resource objects /
+VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-INBOUND-

SA]{VIRTIO_NET_RESOURCE_OBJ_IP
+SEC_INB_SA} & IPsec inbound SA resource object \\ \hline
\end{tabularx}

\subsection{Device parts}\label{sec:Device Types / Network Device / Device
parts} @@ -3480,6 +3493,45 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope capability and the classifier object, unless the VIRTIO_NET_FF_MASK_F_PARTIAL_MASK is enabled.

+\subsubsection{IPsec Operation}\label{sec:Device Types / Network Device

device-types/net/description.tex +5 -0
+/ Device Operation / IPsec Operation}
+
+A network device can support the processing of IPsec operations when
+VIRTIO_NET_F_IPSEC feature is negotiated. In addition to standard
+packet processing, the IPsec protocol processing is also handled by the

network device.
+This occurs both pre-transmit and post-receive, providing inline IPsec capabilities.

device-types/net/description.tex +5 -0
+
+IPsec Inbound processing: In receive path 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 from the packet (See \hyperref[intro:IPSEC]{[IPSEC]}). The

resulting packet contains only the plain data.

device-types/net/description.tex +18 -0
+
+IPsec Outbound processing: In transmit path the device performs
+encryption, attach ICV, update/add IP header and add ESP/AH
+header/trailer to the packet and transmit.
+
+\paragraph{Device and driver capabilities} \label{par:Device Types /
+Network Device / Device Operation / IPsec Operation / Device and driver
+capabilities}
+
+The device and the driver indicate IPsec SA resource limits using the
+capability \hyperref[par:Device Types / Crypto Device / Device
+Operation / IPsec Service Operation / Device and driver capabilities /
+VIRTIO-CRYPTO-IPSEC-RESOURCE-CAP]{VIRTIO_NET_IPSEC_RESOURCE_CAP}
+The \hyperref[par:Device Types / Crypto Device / Device Operation /
+IPsec Service Operation / Device and driver capabilities /
+VIRTIO-CRYPTO-IPSEC-SA-CAP]{VIRTIO_NET_IPSEC_SA_CAP}
+capability specifies which IPsec protocol capabilities the device
+supports. The driver indicates the IPsec parameters by setting the IPsec SA

capability prior to adding any resource objects.

device-types/net/description.tex +7 -0
+
+\paragraph{Resource objects}
+\label{par:Device Types / Network Device / Device Operation / IPsec
+Operation / Resource objects}
+
+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}.

device-types/net/description.tex +6 -0
+
+The IPsec SA resource object contains necessary parameters for packet
+encryption and decryption. These include the SPI, tunnel headers, IPsec
+mode, IPsec options, and data specific to cipher and authentication.
+
+See \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec

Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC- OUTBOUND-SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA}.

device-types/net/description.tex +2 -0
+
+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}.
+
\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
Types / Network Device / Legacy Interface: Framing Requirements}

Quoted 2 lines

--
2.25.1

IIRC, the outer header length vnet field is added to speed up the ipsec.
So we should add the dependency or recommendation here to say, when device offers IPSEC feature, it SHOULD offer OUTER_HDR too.

For the rest,

#3 lore raw

RFC PATCH v5 2/4 virtio-net: Add new flow filter selector and action for IPsec

In reply to Srujana Challa

This update introduces a new flow filter selector to match the ESP header and adds a new flow filter action for IPsec processing.

---
 device-types/net/description.tex | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)
device-types/net/description.tex +21 -4
index d918c55..ea70c6f 100644
@@ -3097,7 +3097,9 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 0x5 & VIRTIO_NET_FF_MASK_TYPE_UDP & 8 bytes of UDP header described in \hyperref[intro:UDP]{UDP} \\
 \hline
-0x6 - 0xFF & & Reserved for future \\
+0x6 & VIRTIO_NET_FF_MASK_TYPE_ESP & 8 bytes of ESP header \\
+\hline
+0x7 - 0xFF & & Reserved for future \\
 \hline
 \end{tabularx}
 \end{table}
@@ -3157,7 +3159,11 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 0x2 & VIRTIO_NET_FF_ACTION_DIRECT_RX_VQ & Matching packet will be directed to a receive queue \\
 \hline
-0x3 - 0xFF & & Reserved for future \\
+0x3 & VIRTIO_NET_FF_ACTION_IPSEC & Matching packet will undergo IPsec processing \\
+\hline
+0x4 & VIRTIO_NET_FF_ACTION_IPSEC_RECIRCULATE & Matching packet will first undergo IPsec processing, followed by the flow filter rules again \\
+\hline
+0x5 - 0xFF & & Reserved for future \\
 \hline
 \end{tabularx}
 \end{table}
@@ -3210,8 +3216,8 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope
 
 The first selector is always VIRTIO_NET_FF_MASK_TYPE_ETH. When there are multiple
 selectors, a second selector can be either VIRTIO_NET_FF_MASK_TYPE_IPV4
-or VIRTIO_NET_FF_MASK_TYPE_IPV6. If the third selector exists, the third
-selector can be either VIRTIO_NET_FF_MASK_TYPE_UDP or VIRTIO_NET_FF_MASK_TYPE_TCP.
+or VIRTIO_NET_FF_MASK_TYPE_IPV6. If the third selector exists, it can be set to
+VIRTIO_NET_FF_MASK_TYPE_UDP, VIRTIO_NET_FF_MASK_TYPE_TCP and VIRTIO_NET_FF_MASK_TYPE_ESP.
 For example, to match a Ethernet IPv6 UDP packet,
 \field{selectors[0].type} is set to VIRTIO_NET_FF_MASK_TYPE_ETH, \field{selectors[1].type}
 is set to VIRTIO_NET_FF_MASK_TYPE_IPV6 and \field{selectors[2].type} is
@@ -3509,6 +3515,17 @@ \subsubsection{IPsec Operation}\label{sec:Device Types / Network Device / Device
 attach ICV, update/add IP header and add ESP/AH header/trailer to the packet
 and transmit.
 
+\paragraph{Packet processing order}
+\label{par:Device Types / Network Device / Device Operation / IPsec Operation / Packet processing order}
+
+If an IPsec action rule, either VIRTIO_NET_FF_ACTION_IPSEC or VIRTIO_NET_FF_ACTION_IPSEC_RECIRCULATE,
+is matched during flow filter processing, IPsec processing is applied on the packet.
+In the case of VIRTIO_NET_FF_ACTION_IPSEC_RECIRCULATE, the packet goes through IPsec processing and
+is then recirculated only once to avoid the infinite loops in the device.
+
+See \ref{sec:Device Types / Network Device / Device Operation / Flow filter}
+for details about flow filter.
+
 \paragraph{Device and driver capabilities}
 \label{par:Device Types / Network Device / Device Operation / IPsec Operation / Device and driver capabilities}
 
Signature · 1 line
2.25.1
Reviewed-by on v5 2/4
#4 lore raw

RE: [PATCH RFC v5 2/4] virtio-net: Add new flow filter selector and action for IPsec

Quoted 77 lines

From: Srujana Challa <[email protected]>
Sent: Thursday, April 24, 2025 3:14 PM

This update introduces a new flow filter selector to match the ESP header and adds a new flow filter action for IPsec processing.

---
 device-types/net/description.tex | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)
device- renamed from device-types/net/description.tex +0 -0

types/net/description.tex
index d918c55..ea70c6f 100644

device-types/net/description.tex +0 -0
@@ -3097,7 +3097,9 @@ \subsubsection{Flow filter}\label{sec:Device Types /

Network Device / Device Ope \hline
0x5 & VIRTIO_NET_FF_MASK_TYPE_UDP & 8 bytes of UDP header described
in \hyperref[intro:UDP]{UDP} \\ \hline
-0x6 - 0xFF & & Reserved for future \\
+0x6 & VIRTIO_NET_FF_MASK_TYPE_ESP & 8 bytes of ESP header \\ \hline +0x7 - 0xFF & & Reserved for future \\
\hline
\end{tabularx}
\end{table}

device-types/net/description.tex +0 -0
@@ -3157,7 +3159,11 @@ \subsubsection{Flow filter}\label{sec:Device Types

/ Network Device / Device Ope \hline
0x2 & VIRTIO_NET_FF_ACTION_DIRECT_RX_VQ & Matching packet will be
directed to a receive queue \\ \hline
-0x3 - 0xFF & & Reserved for future \\
+0x3 & VIRTIO_NET_FF_ACTION_IPSEC & Matching packet will undergo IPsec

device-types/net/description.tex +5 -0
+processing \\ \hline
+0x4 & VIRTIO_NET_FF_ACTION_IPSEC_RECIRCULATE & Matching packet will
+first undergo IPsec processing, followed by the flow filter rules again
+\\ \hline
+0x5 - 0xFF & & Reserved for future \\
 \hline
 \end{tabularx}
 \end{table}
@@ -3210,8 +3216,8 @@ \subsubsection{Flow filter}\label{sec:Device Types /

Network Device / Device Ope

The first selector is always VIRTIO_NET_FF_MASK_TYPE_ETH. When there are
multiple selectors, a second selector can be either VIRTIO_NET_FF_MASK_TYPE_IPV4 -or VIRTIO_NET_FF_MASK_TYPE_IPV6. If the third selector exists, the third -selector can be either VIRTIO_NET_FF_MASK_TYPE_UDP or VIRTIO_NET_FF_MASK_TYPE_TCP.

device-types/net/description.tex +2 -0
+or VIRTIO_NET_FF_MASK_TYPE_IPV6. If the third selector exists, it can
+be set to VIRTIO_NET_FF_MASK_TYPE_UDP,

VIRTIO_NET_FF_MASK_TYPE_TCP and VIRTIO_NET_FF_MASK_TYPE_ESP.
For example, to match a Ethernet IPv6 UDP packet, \field{selectors[0].type} is
set to VIRTIO_NET_FF_MASK_TYPE_ETH, \field{selectors[1].type} is set to VIRTIO_NET_FF_MASK_TYPE_IPV6 and \field{selectors[2].type} is @@ -3509,6 +3515,17 @@ \subsubsection{IPsec Operation}\label{sec:Device Types / Network Device / Device attach ICV, update/add IP header and add ESP/AH header/trailer to the packet and transmit.

+\paragraph{Packet processing order}
+\label{par:Device Types / Network Device / Device Operation / IPsec

device-types/net/description.tex +5 -0
+Operation / Packet processing order}
+
+If an IPsec action rule, either VIRTIO_NET_FF_ACTION_IPSEC or
+VIRTIO_NET_FF_ACTION_IPSEC_RECIRCULATE,
+is matched during flow filter processing, IPsec processing is applied on the

packet.

device-types/net/description.tex +2 -0
+In the case of VIRTIO_NET_FF_ACTION_IPSEC_RECIRCULATE, the packet goes
+through IPsec processing and is then recirculated only once to avoid the

infinite loops in the device.

device-types/net/description.tex +4 -0
+
+See \ref{sec:Device Types / Network Device / Device Operation / Flow
+filter} for details about flow filter.
+
 \paragraph{Device and driver capabilities}  \label{par:Device Types / Network

Device / Device Operation / IPsec Operation / Device and driver capabilities}

Quoted 2 lines

--
2.25.1

If you happen to send v6 of this, it would be good to add, a one line description about re-circulate. If not, we can add it right after this series merged.
Something like,

When a packet it recirculated, it undergoes flow filters processing again with the updated packet content.

#5 lore raw

RFC PATCH v5 3/4 virtio-net: extend virtio_net_hdr for IPsec support

In reply to Srujana Challa

Add IPsec resource object identifiers to the virtio_net_hdr for identifying encryption/decryption operations on tx and rx side respectively, along with flags.

---
 device-types/net/description.tex | 50 +++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)
device-types/net/description.tex +49 -1
index ea70c6f..8903e03 100644
@@ -596,6 +596,9 @@ \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O
 #define VIRTIO_NET_HDR_F_DATA_VALID    2
 #define VIRTIO_NET_HDR_F_RSC_INFO      4
 #define VIRTIO_NET_HDR_F_UDP_TUNNEL_CSUM 8
+#define VIRTIO_NET_HDR_F_SECURITY      16
+#define VIRTIO_NET_HDR_F_SECURITY_ERR  32
+#define VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN 64
         u8 flags;
 #define VIRTIO_NET_HDR_GSO_NONE        0
 #define VIRTIO_NET_HDR_GSO_TCPV4       1
@@ -618,6 +621,12 @@ \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O
         le16 inner_nh_offset;   (Only if VIRTIO_NET_F_HOST_UDP_TUNNEL_GSO or VIRTIO_NET_F_GUEST_UDP_TUNNEL_GSO negotiated)
         le16 outer_nh_offset;   /* Only if VIRTIO_NET_F_OUT_NET_HEADER negotiated */
         u8 padding_reserved_2[6]; /* Only if VIRTIO_NET_F_OUT_NET_HEADER negotiated */
+        /* Present only if VIRTIO_NET_F_IPSEC negotiated */
+        struct ipsec_resource_hdr {
+                le32 resource_id;
+                le16 resource_type;
+                u8 padding_reserved_3[2];
+        };
 };
 \end{lstlisting}
 
@@ -971,6 +980,15 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De
 together with the VIRTIO_NET_HDR_F_GSO_UDP_TUNNEL_IPV4 bit or the
 VIRTIO_NET_HDR_F_GSO_UDP_TUNNEL_IPV6 bit in \field{gso_type}.
 
+If the device supports \hyperref[par:Device Types / Network Device / Device Operation / IPsec Operation]{IPsec Operation},
+the driver may set VIRTIO_NET_HDR_F_SECURITY bit in \field{flags}, if so:
+\begin{enumerate}
+\item the driver MUST create IPsec Outbound resource object
+\hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-ENC-SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA}
+\item the driver MUST set \field{resource_id} to a valid IPsec outbound
+      resource object ID.
+\end{enumerate}
+
 \devicenormative{\paragraph}{Packet Transmission}{Device Types / Network Device / Device Operation / Packet Transmission}
 The device MUST ignore \field{flag} bits that it does not recognize.
 
@@ -1031,6 +1049,10 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De
 
 If VIRTIO_NET_HDR_F_NEEDS_CSUM is not set, the device MUST NOT
 rely on the packet checksum being correct.
+
+If VIRTIO_NET_HDR_F_SECURITY bit in \field{flags} is not set, the
+device MUST NOT use the \field{resource_id} and \field{resource_type}.
+
 \paragraph{Packet Transmission Interrupt}\label{sec:Device Types / Network Device / Device Operation / Packet Transmission / Packet Transmission Interrupt}
 
 Often a driver will suppress transmission virtqueue interrupts
@@ -1083,7 +1105,8 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi
 \end{note}
 
 When calculating the size of \field{struct virtio_net_hdr}, the driver
-MUST consider all the fields inclusive up to \field{padding_reserved_2},
+MUST consider all the fields inclusive up to \field{struct ipsec_resource_hdr},
+i.e. 40 bytes if VIRTIO_NET_F_IPSEC is negotiated or up to \field{padding_reserved_2}
 i.e. 32 bytes if VIRTIO_NET_F_OUT_NET_HEADER is negotiated or up to \field{inner_nh_offset}
 i.e. 24 bytes if VIRTIO_NET_F_HOST_UDP_TUNNEL_GSO is negotiated or up to \field{padding_reserved}
 i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not.
@@ -1340,6 +1363,21 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
 \field{flags}, the device MUST either provide a zero outer UDP header
 checksum or a fully checksummed outer UDP header.
 
+The device MUST set the VIRTIO_NET_HDR_F_SECURITY bit in the \field{flags}
+if the packet goes through the IPsec processing. Otherwise, this bit MUST
+be cleared. The device MUST set or clear this bit regardless of setting
+VIRTIO_NET_HDR_F_SECURITY_ERR or VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN bit.
+
+The device MUST set the VIRTIO_NET_HDR_F_SECURITY_ERR bit in the \field{flags}
+if any error is encountered during IPsec processing. Otherwise, this bit MUST be cleared.
+The device MUST set or clear this bit regardless of setting
+VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN bit.
+
+The device MUST set the VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN bit in the \field{flags}
+if the SA associated with \field{resource_id} reaches the SA lifetime soft limits configured in
+the \field{struct virtio_crypto_ipsec_lifetime}.
+See \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-OUTBOUND-SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA}.
+
 \drivernormative{\paragraph}{Processing of Incoming
 Packets}{Device Types / Network Device / Device Operation /
 Processing of Incoming Packets}
@@ -1391,6 +1429,12 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
 VIRTIO_NET_HDR_GSO_UDP_TUNNEL_IPV6 in \field{gso_type} are not set,
 the driver MOST NOT accept the packet.
 
+When VIRTIO_NET_HDR_F_SECURITY and VIRTIO_NET_HDR_F_SECURITY_ERR bits are set in the \field{flags},
+it indicates that the device experienced a processing error on the IPsec packet.
+It need not be an 'error packet'. For example, a particular SA was not offloaded or
+SA has reached the SA lifetime hard limits configured in the \field{struct virtio_crypto_ipsec_lifetime}.
+So vnet_hdr will have both bits set.
+
 \paragraph{Hash calculation for incoming packets}
 \label{sec:Device Types / Network Device / Device Operation / Processing of Incoming Packets / Hash calculation for incoming packets}
 
@@ -3526,6 +3570,10 @@ \subsubsection{IPsec Operation}\label{sec:Device Types / Network Device / Device
 See \ref{sec:Device Types / Network Device / Device Operation / Flow filter}
 for details about flow filter.
 
+Note that there is a small race condition where a SA object might be destroyed
+while a recieve packet is still inflight. The driver SHOULD handle this situation
+appropriately.
+
 \paragraph{Device and driver capabilities}
 \label{par:Device Types / Network Device / Device Operation / IPsec Operation / Device and driver capabilities}
 
Signature · 1 line
2.25.1
#6 lore raw

RE: [PATCH RFC v5 3/4] virtio-net: extend virtio_net_hdr for IPsec support

Quoted 38 lines

From: Srujana Challa <[email protected]>
Sent: Thursday, April 24, 2025 3:14 PM

Add IPsec resource object identifiers to the virtio_net_hdr for identifying encryption/decryption operations on tx and rx side respectively, along with flags.

---
 device-types/net/description.tex | 50 +++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)
device- renamed from device-types/net/description.tex +0 -0

types/net/description.tex
index ea70c6f..8903e03 100644

device-types/net/description.tex +0 -0
@@ -596,6 +596,9 @@ \subsection{Device Operation}\label{sec:Device Types

/ Network Device / Device O
#define VIRTIO_NET_HDR_F_DATA_VALID 2
#define VIRTIO_NET_HDR_F_RSC_INFO 4
#define VIRTIO_NET_HDR_F_UDP_TUNNEL_CSUM 8

device-types/net/description.tex +3 -0
+#define VIRTIO_NET_HDR_F_SECURITY      16
+#define VIRTIO_NET_HDR_F_SECURITY_ERR  32 #define
+VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN 64
         u8 flags;
 #define VIRTIO_NET_HDR_GSO_NONE        0
 #define VIRTIO_NET_HDR_GSO_TCPV4       1
@@ -618,6 +621,12 @@ \subsection{Device Operation}\label{sec:Device

Types / Network Device / Device O
le16 inner_nh_offset; (Only if VIRTIO_NET_F_HOST_UDP_TUNNEL_GSO
or VIRTIO_NET_F_GUEST_UDP_TUNNEL_GSO negotiated)
le16 outer_nh_offset; /* Only if VIRTIO_NET_F_OUT_NET_HEADER
negotiated */
u8 padding_reserved_2[6]; /* Only if VIRTIO_NET_F_OUT_NET_HEADER
negotiated */

device-types/net/description.tex \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O · line 631

Quoted 8 lines
device-types/net/description.tex +6 -0
+        /* Present only if VIRTIO_NET_F_IPSEC negotiated */
+        struct ipsec_resource_hdr {
+                le32 resource_id;
+                le16 resource_type;
+                u8 padding_reserved_3[2];
+        };
 };
 \end{lstlisting}

With the outer header, vnet header is not aligned to 32 bytes.
We should try to squeeze this in relatively well aligned 32B structure.
And we have the 6Bytes space, so lets replace padding_reserved_2 with ipsec_resource_hdr.

Something like,
When VIRTIO_NET_F_OUT_NET_HEADER or VIRTIO_NET_F_IPSEC is negotiated, the virtio_net_hdr length is up to field \field{struct ipsec_resource_hdr}.

Quoted 90 lines
device-types/net/description.tex +0 -0
@@ -971,6 +980,15 @@ \subsubsection{Packet

Transmission}\label{sec:Device Types / Network Device / De together with the VIRTIO_NET_HDR_F_GSO_UDP_TUNNEL_IPV4 bit or the
VIRTIO_NET_HDR_F_GSO_UDP_TUNNEL_IPV6 bit in \field{gso_type}.

device-types/net/description.tex +2 -0
+If the device supports \hyperref[par:Device Types / Network Device /
+Device Operation / IPsec Operation]{IPsec Operation}, the driver may set

VIRTIO_NET_HDR_F_SECURITY bit in \field{flags}, if so:
+\begin{enumerate}
+\item the driver MUST create IPsec Outbound resource object +\hyperref[par:Device Types / Crypto Device / Device Operation / IPsec

device-types/net/description.tex +2 -0
+Service Operation / Resource objects /
+VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-ENC-

SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_

device-types/net/description.tex +5 -0
+OUTB_SA} \item the driver MUST set \field{resource_id} to a valid IPsec
+outbound
+      resource object ID.
+\end{enumerate}
+
 \devicenormative{\paragraph}{Packet Transmission}{Device Types / Network

Device / Device Operation / Packet Transmission} The device MUST ignore \field{flag} bits that it does not recognize.

device-types/net/description.tex +0 -0
@@ -1031,6 +1049,10 @@ \subsubsection{Packet

Transmission}\label{sec:Device Types / Network Device / De

If VIRTIO_NET_HDR_F_NEEDS_CSUM is not set, the device MUST NOT rely
on the packet checksum being correct.

device-types/net/description.tex +4 -0
+
+If VIRTIO_NET_HDR_F_SECURITY bit in \field{flags} is not set, the
+device MUST NOT use the \field{resource_id} and \field{resource_type}.
+
 \paragraph{Packet Transmission Interrupt}\label{sec:Device Types / Network

Device / Device Operation / Packet Transmission / Packet Transmission Interrupt}

Often a driver will suppress transmission virtqueue interrupts @@ -1083,7
+1105,8 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi \end{note}

When calculating the size of \field{struct virtio_net_hdr}, the driver -MUST
consider all the fields inclusive up to \field{padding_reserved_2},

device-types/net/description.tex +3 -0
+MUST consider all the fields inclusive up to \field{struct
+ipsec_resource_hdr}, i.e. 40 bytes if VIRTIO_NET_F_IPSEC is negotiated
+or up to \field{padding_reserved_2}
 i.e. 32 bytes if VIRTIO_NET_F_OUT_NET_HEADER is negotiated or up to

\field{inner_nh_offset} i.e. 24 bytes if VIRTIO_NET_F_HOST_UDP_TUNNEL_GSO is negotiated or up to \field{padding_reserved} i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not.

device-types/net/description.tex +0 -0
@@ -1340,6 +1363,21 @@ \subsubsection{Processing of Incoming

Packets}\label{sec:Device Types / Network \field{flags}, the device MUST either provide a zero outer UDP header checksum or a fully checksummed outer UDP header.

device-types/net/description.tex +4 -0
+The device MUST set the VIRTIO_NET_HDR_F_SECURITY bit in the
+\field{flags} if the packet goes through the IPsec processing.
+Otherwise, this bit MUST be cleared. The device MUST set or clear this
+bit regardless of setting VIRTIO_NET_HDR_F_SECURITY_ERR or

VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN bit.

device-types/net/description.tex +3 -0
+
+The device MUST set the VIRTIO_NET_HDR_F_SECURITY_ERR bit in the
+\field{flags} if any error is encountered during IPsec processing. Otherwise,

this bit MUST be cleared.

device-types/net/description.tex +4 -0
+The device MUST set or clear this bit regardless of setting
+VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN bit.
+
+The device MUST set the

VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN

device-types/net/description.tex +2 -0
+bit in the \field{flags} if the SA associated with \field{resource_id}
+reaches the SA lifetime soft limits configured in the \field{struct

virtio_crypto_ipsec_lifetime}.
+See \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC- OUTBOUND-SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA}.
+
\drivernormative{\paragraph}{Processing of Incoming Packets}{Device Types
/ Network Device / Device Operation / Processing of Incoming Packets} @@ - 1391,6 +1429,12 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
VIRTIO_NET_HDR_GSO_UDP_TUNNEL_IPV6 in \field{gso_type} are not set,
the driver MOST NOT accept the packet.

+When VIRTIO_NET_HDR_F_SECURITY and VIRTIO_NET_HDR_F_SECURITY_ERR bits
+are set in the \field{flags}, it indicates that the device experienced a processing error on the IPsec packet.

device-types/net/description.tex +2 -0
+It need not be an 'error packet'. For example, a particular SA was not
+offloaded or SA has reached the SA lifetime hard limits configured in the

\field{struct virtio_crypto_ipsec_lifetime}.

device-types/net/description.tex \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network · line 1437

Quoted 2 lines
device-types/net/description.tex +2 -0
+So vnet_hdr will have both bits set.
+

If you add the dedicated error code for the hard limit reached in the crypto, we should add the bit here too. Its unfortunate that we have to burn many bits here in u8 flags.
It should have been an enum.
But I believe until the vnet data structs improve, you can skip this extra hard fail limit in both the devices (crypto and net).

Quoted 17 lines

\paragraph{Hash calculation for incoming packets} \label{sec:Device Types /
Network Device / Device Operation / Processing of Incoming Packets / Hash calculation for incoming packets}

device-types/net/description.tex +0 -0
@@ -3526,6 +3570,10 @@ \subsubsection{IPsec Operation}\label{sec:Device

Types / Network Device / Device See \ref{sec:Device Types / Network Device / Device Operation / Flow filter} for details about flow filter.

device-types/net/description.tex +4 -0
+Note that there is a small race condition where a SA object might be
+destroyed while a recieve packet is still inflight. The driver SHOULD
+handle this situation appropriately.
+
 \paragraph{Device and driver capabilities}  \label{par:Device Types / Network

Device / Device Operation / IPsec Operation / Device and driver capabilities}

--
2.25.1

#7 lore raw

RE: [PATCH RFC v5 3/4] virtio-net: extend virtio_net_hdr for IPsec support

Quoted 46 lines
Quoted 29 lines

From: Srujana Challa <[email protected]>
Sent: Thursday, April 24, 2025 3:14 PM

Add IPsec resource object identifiers to the virtio_net_hdr for identifying encryption/decryption operations on tx and rx side respectively, along with flags.

---
 device-types/net/description.tex | 50
+++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)
device- renamed from device-types/net/description.tex +0 -0

types/net/description.tex index ea70c6f..8903e03 100644

device-types/net/description.tex +0 -0
@@ -596,6 +596,9 @@ \subsection{Device Operation}\label{sec:Device

Types / Network Device / Device O
#define VIRTIO_NET_HDR_F_DATA_VALID 2
#define VIRTIO_NET_HDR_F_RSC_INFO 4
#define VIRTIO_NET_HDR_F_UDP_TUNNEL_CSUM 8

device-types/net/description.tex +3 -0
+#define VIRTIO_NET_HDR_F_SECURITY      16
+#define VIRTIO_NET_HDR_F_SECURITY_ERR  32 #define
+VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN 64
         u8 flags;
 #define VIRTIO_NET_HDR_GSO_NONE        0
 #define VIRTIO_NET_HDR_GSO_TCPV4       1
@@ -618,6 +621,12 @@ \subsection{Device Operation}\label{sec:Device
Quoted 2 lines

Types / Network Device / Device O
le16 inner_nh_offset; (Only if

VIRTIO_NET_F_HOST_UDP_TUNNEL_GSO

Quoted 6 lines

or VIRTIO_NET_F_GUEST_UDP_TUNNEL_GSO negotiated)
le16 outer_nh_offset; /* Only if VIRTIO_NET_F_OUT_NET_HEADER
negotiated */

         u8 padding_reserved_2[6]; /* Only if

VIRTIO_NET_F_OUT_NET_HEADER negotiated */

device-types/net/description.tex \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O · line 631

Quoted 8 lines
device-types/net/description.tex +6 -0
+        /* Present only if VIRTIO_NET_F_IPSEC negotiated */
+        struct ipsec_resource_hdr {
+                le32 resource_id;
+                le16 resource_type;
+                u8 padding_reserved_3[2];
+        };
 };
 \end{lstlisting}
Quoted 4 lines

With the outer header, vnet header is not aligned to 32 bytes. We should try to squeeze this in relatively well aligned 32B structure. And we have the 6Bytes space, so lets replace padding_reserved_2 with ipsec_resource_hdr.

Sure, will do.

Quoted 119 lines

Something like,
When VIRTIO_NET_F_OUT_NET_HEADER or VIRTIO_NET_F_IPSEC is negotiated, the virtio_net_hdr length is up to field \field{struct ipsec_resource_hdr}.

Quoted 14 lines
device-types/net/description.tex +0 -0
@@ -971,6 +980,15 @@ \subsubsection{Packet

Transmission}\label{sec:Device Types / Network Device / De together with the VIRTIO_NET_HDR_F_GSO_UDP_TUNNEL_IPV4 bit or the
VIRTIO_NET_HDR_F_GSO_UDP_TUNNEL_IPV6 bit in \field{gso_type}.

device-types/net/description.tex +2 -0
+If the device supports \hyperref[par:Device Types / Network Device /
+Device Operation / IPsec Operation]{IPsec Operation}, the driver may set

VIRTIO_NET_HDR_F_SECURITY bit in \field{flags}, if so:
+\begin{enumerate}
+\item the driver MUST create IPsec Outbound resource object +\hyperref[par:Device Types / Crypto Device / Device Operation / IPsec

device-types/net/description.tex +2 -0
+Service Operation / Resource objects /
+VIRTIO-CRYPTO-RESOURCE-OBJ-IPSEC-ENC-

SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_

device-types/net/description.tex \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De

Quoted 6 lines
device-types/net/description.tex +5 -0
+OUTB_SA} \item the driver MUST set \field{resource_id} to a valid IPsec
+outbound
+      resource object ID.
+\end{enumerate}
+
 \devicenormative{\paragraph}{Packet Transmission}{Device Types /

Network

device-types/net/description.tex \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De

Quoted 13 lines

Device / Device Operation / Packet Transmission} The device MUST ignore \field{flag} bits that it does not recognize.

device-types/net/description.tex +0 -0
@@ -1031,6 +1049,10 @@ \subsubsection{Packet

Transmission}\label{sec:Device Types / Network Device / De

If VIRTIO_NET_HDR_F_NEEDS_CSUM is not set, the device MUST NOT rely
on the packet checksum being correct.

device-types/net/description.tex +4 -0
+
+If VIRTIO_NET_HDR_F_SECURITY bit in \field{flags} is not set, the
+device MUST NOT use the \field{resource_id} and \field{resource_type}.
+
 \paragraph{Packet Transmission Interrupt}\label{sec:Device Types /

Network

Quoted 38 lines

Device / Device Operation / Packet Transmission / Packet Transmission Interrupt}

Often a driver will suppress transmission virtqueue interrupts @@ -1083,7
+1105,8 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi \end{note}

When calculating the size of \field{struct virtio_net_hdr}, the driver -MUST
consider all the fields inclusive up to \field{padding_reserved_2},

device-types/net/description.tex +3 -0
+MUST consider all the fields inclusive up to \field{struct
+ipsec_resource_hdr}, i.e. 40 bytes if VIRTIO_NET_F_IPSEC is negotiated
+or up to \field{padding_reserved_2}
 i.e. 32 bytes if VIRTIO_NET_F_OUT_NET_HEADER is negotiated or up to

\field{inner_nh_offset} i.e. 24 bytes if VIRTIO_NET_F_HOST_UDP_TUNNEL_GSO is negotiated or up to \field{padding_reserved} i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not.

device-types/net/description.tex +0 -0
@@ -1340,6 +1363,21 @@ \subsubsection{Processing of Incoming

Packets}\label{sec:Device Types / Network \field{flags}, the device MUST either provide a zero outer UDP header checksum or a fully checksummed outer UDP header.

device-types/net/description.tex +4 -0
+The device MUST set the VIRTIO_NET_HDR_F_SECURITY bit in the
+\field{flags} if the packet goes through the IPsec processing.
+Otherwise, this bit MUST be cleared. The device MUST set or clear this
+bit regardless of setting VIRTIO_NET_HDR_F_SECURITY_ERR or

VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN bit.

device-types/net/description.tex +3 -0
+
+The device MUST set the VIRTIO_NET_HDR_F_SECURITY_ERR bit in the
+\field{flags} if any error is encountered during IPsec processing. Otherwise,

this bit MUST be cleared.

device-types/net/description.tex +4 -0
+The device MUST set or clear this bit regardless of setting
+VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN bit.
+
+The device MUST set the

VIRTIO_NET_HDR_F_SECURITY_SA_SOFT_EXPIRY_WARN

device-types/net/description.tex +2 -0
+bit in the \field{flags} if the SA associated with \field{resource_id}
+reaches the SA lifetime soft limits configured in the \field{struct
Quoted 3 lines

virtio_crypto_ipsec_lifetime}.
+See \hyperref[par:Device Types / Crypto Device / Device Operation / IPsec Service Operation / Resource objects / VIRTIO-CRYPTO-RESOURCE-OBJ-

IPSEC-

Quoted 3 lines

OUTBOUND-SA]{VIRTIO_NET_RESOURCE_OBJ_IPSEC_OUTB_SA}.
+
\drivernormative{\paragraph}{Processing of Incoming Packets}{Device

Types

Quoted 1 line

/ Network Device / Device Operation / Processing of Incoming Packets} @@

-

Quoted 12 lines

1391,6 +1429,12 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network
VIRTIO_NET_HDR_GSO_UDP_TUNNEL_IPV6 in \field{gso_type} are not set,
the driver MOST NOT accept the packet.

+When VIRTIO_NET_HDR_F_SECURITY and VIRTIO_NET_HDR_F_SECURITY_ERR bits
+are set in the \field{flags}, it indicates that the device experienced a processing error on the IPsec packet.

device-types/net/description.tex +2 -0
+It need not be an 'error packet'. For example, a particular SA was not
+offloaded or SA has reached the SA lifetime hard limits configured in the

\field{struct virtio_crypto_ipsec_lifetime}.

device-types/net/description.tex \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network · line 1437

Quoted 2 lines
device-types/net/description.tex +2 -0
+So vnet_hdr will have both bits set.
+

If you add the dedicated error code for the hard limit reached in the crypto, we should add the bit here too.
Its unfortunate that we have to burn many bits here in u8 flags.
It should have been an enum.
But I believe until the vnet data structs improve, you can skip this extra hard fail limit in both the devices (crypto and net).

device-types/net/description.tex \subsubsection{IPsec

Quoted 5 lines

\paragraph{Hash calculation for incoming packets} \label{sec:Device Types /
Network Device / Device Operation / Processing of Incoming Packets / Hash calculation for incoming packets}

device-types/net/description.tex +0 -0
@@ -3526,6 +3570,10 @@ \subsubsection{IPsec

Operation}\label{sec:Device

Quoted 1 line

Types / Network Device / Device See \ref{sec:Device Types / Network Device

/

Quoted 12 lines

device-types/net/description.tex

Quoted 7 lines

Device Operation / Flow filter} for details about flow filter.

device-types/net/description.tex +4 -0
+Note that there is a small race condition where a SA object might be
+destroyed while a recieve packet is still inflight. The driver SHOULD
+handle this situation appropriately.
+
 \paragraph{Device and driver capabilities}  \label{par:Device Types /

Network

Quoted 4 lines

Device / Device Operation / IPsec Operation / Device and driver capabilities}

--
2.25.1

Thanks.

#8 lore raw

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

In reply to Srujana Challa

Add device and driver requirements for IPsec Operation.

---
 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(+)
device-types/net/description.tex +83 -0
index 8903e03..0674bd8 100644
@@ -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}
 
device-types/net/device-conformance.tex +1 -0
index d88484c..7fe8505 100644
@@ -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}
device-types/net/driver-conformance.tex +1 -0
index d346b88..0d20190 100644
@@ -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}
Signature · 1 line
2.25.1
Reviewed-by on v5 4/4
#9 lore raw

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

Quoted 163 lines

From: Srujana Challa <[email protected]>
Sent: Thursday, April 24, 2025 3:14 PM

Add device and driver requirements for IPsec Operation.

---
 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(+)
device- renamed from device-types/net/description.tex +0 -0

types/net/description.tex
index 8903e03..0674bd8 100644

device-types/net/description.tex +0 -0
@@ -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-types/net/description.tex +4 -0
+/ 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

device-types/net/description.tex +5 -0
+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}

device-types/net/description.tex +4 -0
+
+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

device-types/net/description.tex +5 -0
+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.

device-types/net/description.tex +3 -0
+
+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

device-types/net/description.tex +4 -0
+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}

device-types/net/description.tex +2 -0
+
+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}

device-types/net/description.tex +3 -0
+
+The device SHOULD maintain a table for subsequent lookups to
+inbound/outbound data with the corresponding SA based on the supplied

\field{id}.

device-types/net/description.tex +3 -0
+
+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

device-types/net/description.tex +3 -0
+without undergoing a device reset.
+
+The device MAY fail the command

VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE

device-types/net/description.tex +6 -0
+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.

device-types/net/description.tex +10 -0
+
+\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

device-types/net/description.tex +6 -0
+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,

device-types/net/description.tex +4 -0
+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}.

device-types/net/description.tex +6 -0
+
+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}

device- renamed from device-types/net/device-conformance.tex +0 -0

types/net/device-conformance.tex
index d88484c..7fe8505 100644

device-types/net/device-conformance.tex +0 -0
@@ -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

device-types/net/device-conformance.tex +1 -0
+Operation / IPsec Operation}
 \end{itemize}
device- renamed from device-types/net/driver-conformance.tex +0 -0

types/net/driver-conformance.tex
index d346b88..0d20190 100644

device-types/net/driver-conformance.tex +0 -0
@@ -18,4 +18,5 @@
 \item \ref{drivernormative:Device Types / Network Device / Device Operation

/ Control Virtqueue / Device Statistics} \item \ref{drivernormative:Device

Quoted 8 lines

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