[PATCH v6 1/4] virtio-crypto: Add IPsec service operation and Capabilities
Srujana Challa <[email protected]>
| Newsgroups | dev.linux.lists.virtio-comment |
|---|---|
| Message-ID | <[email protected]> |
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]> Reviewed-by: Parav Pandit <[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://www.rfc-editor.org/rfc/rfc9293#name-header-format}\\ + \phantomsection\label{intro:IPSEC}\textbf{[IPSEC]} & + IPsec Protocol + \newline\url{https://www.rfc-editor.org/rfc/rfc4301}\\ + \phantomsection\label{intro:ESP}\textbf{[ESP]} & + IPsec ESP + \newline\url{https://www.rfc-editor.org/rfc/rfc4303}\\ + \phantomsection\label{intro:ESN}\textbf{[ESN]} & + IPsec ESN + \newline\url{https://www.rfc-editor.org/rfc/rfc4304}\\ + \phantomsection\label{intro:UDP-Encapsulation}\textbf{[UDP Encapsulation]} & + IPsec UDP Encapsulation + \newline\url{https://www.rfc-editor.org/rfc/rfc3948}\\ \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