add TLS record processing security offload

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Friday, August 11, 2023 8:17 AM
To: Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [RFC PATCH 1/3] net: add headers for TLS/DTLS packets

From: Akhil Goyal <[email protected]>

Added TLS and DTLS packet headers for L4 security applications.

Signed-off-by Akhil Goyal <[email protected]>

Signed-off-by Anoob Joseph <[email protected]>

Signed-off-by Vidya Sagar Velumuri <[email protected]>

---
 doc/api/doxy-api-index.md |  2 ++
 lib/net/meson.build       |  2 ++
 lib/net/rte_dtls.h        | 61 +++++++++++++++++++++++++++++++++++++++
 lib/net/rte_tls.h         | 48 ++++++++++++++++++++++++++++++
 4 files changed, 113 insertions(+)
 create mode 100644 lib/net/rte_dtls.h
 create mode 100644 lib/net/rte_tls.h

doc/api/doxy-api-index.md +2 -0

index fdeda13932..03e2445bb1 100644
@@ -128,6 +128,8 @@ The public API headers are grouped by topics:
   [eCPRI](@ref rte_ecpri.h),
   [PDCP hdr](@ref rte_pdcp_hdr.h),
   [PDCP](@ref rte_pdcp.h),
+  [TLS](@ref rte_tls.h),
+  [DTLS](@ref rte_dtls.h),
   [L2TPv2](@ref rte_l2tpv2.h),
   [PPP](@ref rte_ppp.h),
   [IB](@ref rte_ib.h)

lib/net/meson.build +2 -0

index b1bc27bad5..0b69138949 100644
@@ -5,6 +5,8 @@ headers = files(
         'rte_ip.h',
         'rte_tcp.h',
         'rte_udp.h',
+        'rte_tls.h',
+        'rte_dtls.h',
         'rte_esp.h',
         'rte_sctp.h',
         'rte_icmp.h',

lib/net/rte_dtls.h new file +11 -0

new file mode 100644
index 0000000000..1455c07a92
@@ -0,0 +1,61 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(C) 2023 Marvell.
+ */
+
+#ifndef RTE_DTLS_H
+#define RTE_DTLS_H
+
+/**
+ * @file
+ *
+ * Datagram transport layer security(DTLS) related defines.

lib/net/rte_dtls.h new file +2 -0

+#define RTE_DTLS_TYPE_ALERT	21 /**< Alert message. */
+#define RTE_DTLS_TYPE_HANDSHAKE	22 /**< Handshake message for

DTLS. */
+#define RTE_DTLS_TYPE_APPDATA 23 /**< DTLS application data message.
*/

lib/net/rte_dtls.h new file +2 -0

+#define RTE_DTLS_TYPE_HEARTBEAT	24 /**< DTLS 1.3 heartbeat message. */
+#define RTE_DTLS_TYPE_CIPHERTEXT_WITH_CID	25 /**< DTLS 1.3

ciphertext with CID message. */

lib/net/rte_dtls.h new file +2 -0

+#define RTE_DTLS_TYPE_ACK	26 /**< DTLS 1.3 ACK message. */
+#define RTE_DTLS_TYPE_MAX	255 /**< Maximum value as DTLS

content type. */

lib/net/rte_dtls.h new file +2 -0

+
+#define RTE_DTLS_VERSION_1_2	0xFEFD /**< DTLS 1.2 version. 1's

complement of 1.2. */
+#define RTE_DTLS_VERSION_1_3 0xFEFC /**< DTLS 1.3 version. 1's
complement of 1.3. */

lib/net/rte_dtls.h new file +4 -0

+#if RTE_BYTE_ORDER == RTE_LITTLE_ENDIAN
+	/** The sequence number for the DTLS record. */
+	uint64_t sequence_number : 48;
+	/** A counter value that is incremented on every cipher state change.

*/

lib/net/rte_dtls.h new file +3 -0

+	uint64_t epoch : 16;
+#elif RTE_BYTE_ORDER == RTE_BIG_ENDIAN
+	/** A counter value that is incremented on every cipher state change.

*/

lib/net/rte_dtls.h new file +13 -0

+	uint64_t epoch : 16;
+	/** The sequence number for the DTLS record. */
+	uint64_t sequence_number : 48;
+#endif
+	/** The length (in bytes) of the following DTLS packet. */
+	rte_be16_t length;
+} __rte_packed;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RTE_DTLS_H */

lib/net/rte_tls.h new file +26 -0

new file mode 100644
index 0000000000..d708d06014
@@ -0,0 +1,48 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(C) 2023 Marvell.
+ */
+
+#ifndef RTE_TLS_H
+#define RTE_TLS_H
+
+/**
+ * @file
+ *
+ * Transport layer security(TLS) related defines.
+ */
+
+#include <rte_byteorder.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define RTE_TLS_TYPE_INVALID	0 /**< Invalid TLS message type. */
+#define RTE_TLS_TYPE_CCS	20 /**< Change cipher message. */
+#define RTE_TLS_TYPE_ALERT	21 /**< Alert message. */
+#define RTE_TLS_TYPE_HANDSHAKE	22 /**< Handshake message for TLS. */
+#define RTE_TLS_TYPE_APPDATA	23 /**< TLS application data message. */
+#define RTE_TLS_TYPE_HEARTBEAT	24 /**< TLS 1.3 heartbeat message. */
+#define RTE_TLS_TYPE_MAX	255 /**< Maximum value as TLS content type.

*/

lib/net/rte_tls.h new file +3 -0

+
+#define RTE_TLS_VERSION_1_2	0x0303 /**< TLS 1.2 version. */
+#define RTE_TLS_VERSION_1_3	0x0304 /**< TLS 1.3 version. */

lib/net/rte_tls.h new file +9 -1

+	/** The length (in bytes) of the following TLS packet. */
+	rte_be16_t length;
+} __rte_packed;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RTE_TLS_H */
--

2.25.1

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Friday, August 11, 2023 8:17 AM
To: Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [RFC PATCH 2/3] security: add TLS record processing

Add Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS). The protocols provide communications privacy for L4 protocols such as TCP & UDP.

TLS (and DTLS) protocol is composed of two layers,
1. TLS Record Protocol
2. TLS Handshake Protocol

While TLS Handshake Protocol helps in establishing security parameters by which client and server can communicate, TLS Record Protocol provides the connection security. TLS Record Protocol leverages symmetric cryptographic operations such as data encryption and authentication for providing security to the communications.

Cryptodevs that are capable of offloading TLS Record Protocol may perform other operations like IV generation, header insertion, atomic sequence number updates and anti-replay window check in addition to cryptographic transformations.

The support is added for TLS 1.2, TLS 1.3 and DTLS 1.2.

Signed-off-by Akhil Goyal <[email protected]>

Signed-off-by Anoob Joseph <[email protected]>

Signed-off-by Vidya Sagar Velumuri <[email protected]>

---
 doc/guides/prog_guide/rte_security.rst |  58 +++++++++++++
 lib/security/rte_security.c            |   4 +
 lib/security/rte_security.h            | 110 +++++++++++++++++++++++++
 3 files changed, 172 insertions(+)

doc/guides/prog_guide/rte_security.rst +4 -0

index 7418e35c1b..7716d7239f 100644
@@ -399,6 +399,64 @@ The API ``rte_security_macsec_sc_create`` returns a
 handle for SC,
 and this handle is set in ``rte_security_macsec_xform``
 to create a MACsec session using ``rte_security_session_create``.
 
+TLS-Record Protocol
+~~~~~~~~~~~~~~~~~~~
+
+The Transport Layer Protocol provides communications security over the

Internet. The protocol
+allows client/server applications to communicate in a way that is designed to prevent eavesdropping,

doc/guides/prog_guide/rte_security.rst +3 -0

+tampering, or message forgery.
+
+TLS protocol is composed of two layers: the TLS Record Protocol and the TLS

Handshake Protocol. At
+the lowest level, layered on top of some reliable transport protocol (e.g., TCP), is the TLS Record
+Protocol. The TLS Record Protocol provides connection security that has two basic properties:

doc/guides/prog_guide/rte_security.rst +5 -0

+
+   -  The connection is private.  Symmetric cryptography is used for data
+      encryption (e.g., AES, DES, etc.).  The keys for this symmetric encryption
+      are generated uniquely for each connection and are based on a secret
+      negotiated by another protocol (such as the TLS Handshake Protocol). The

doc/guides/prog_guide/rte_security.rst +32 -0

+             Record Write                   Record Read
+             ------------                   -----------
+
+             TLSPlaintext                  TLSCiphertext
+                  |                              |
+                  ~                              ~
+                  |                              |
+                  V                              V
+        +---------|----------+        +----------|---------+
+        | Seq. no generation |        | Seq. no generation |
+        +---------|----------+        +----------|---------+
+                  |                              |
+        +---------|----------+        +----------|---------+
+        |  Header insertion  |        |    Decryption &    |
+        +---------|----------+        |  MAC verification  |
+                  |                   +----------|---------+
+        +---------|----------+                   |
+        |  MAC generation &  |        +----------|---------+
+        |     Encryption     |        | TLS Header removal |
+        +---------|----------+        +----------|---------+
+                  |                              |
+                  ~                              ~
+                  |                              |
+                  V                              V
+            TLSCiphertext                  TLSPlaintext
+
+Supported Versions
+^^^^^^^^^^^^^^^^^^
+
+* TLS 1.2
+* TLS 1.3
+* DTLS 1.2
 
 Device Features and Capabilities
 ---------------------------------

lib/security/rte_security.c +2 -0

index c4d64bb8e9..bd7b026547 100644
@@ -282,6 +282,10 @@ rte_security_capability_get(struct rte_security_ctx
 *instance,
 				if (capability->docsis.direction ==
 							idx->docsis.direction)
 					return capability;
+			} else if (idx->protocol ==
 RTE_SECURITY_PROTOCOL_TLS_RECORD) {
+				if (capability->tls_record.ver == idx-

Quoted 1 line

tls_record.ver &&

lib/security/rte_security.c +1 -0

+				    capability->tls_record.type == idx-

Quoted 1 line

tls_record.type)

lib/security/rte_security.c +1 -0

+					return capability;
 			}
 		}
 	}

lib/security/rte_security.h +30 -0

index 3b2df526ba..b9d064ed84 100644
@@ -620,6 +620,99 @@ struct rte_security_docsis_xform {
 	/**< DOCSIS direction */
 };
 
+/** Salt len to be used with AEAD algos in TLS 1.2 */
+#define RTE_SECURITY_TLS_1_2_SALT_LEN 4
+/** Salt len to be used with AEAD algos in TLS 1.3 */
+#define RTE_SECURITY_TLS_1_3_SALT_LEN 12
+/** Salt len to be used with AEAD algos in DTLS 1.2 */
+#define RTE_SECURITY_DTLS_1_2_SALT_LEN 4
+
+/** TLS version */
+enum rte_security_tls_version {
+	RTE_SECURITY_VERSION_TLS_1_2,	/**< TLS 1.2 */
+	RTE_SECURITY_VERSION_TLS_1_3,	/**< TLS 1.3 */
+	RTE_SECURITY_VERSION_DTLS_1_2,	/**< DTLS 1.2 */
+};
+
+/** TLS session type */
+enum rte_security_tls_sess_type {
+	/** Record read session
+	 * - Decrypt & digest verification.
+	 */
+	RTE_SECURITY_TLS_SESS_TYPE_READ,
+	/** Record write session
+	 * - Encrypt & digest generation.
+	 */
+	RTE_SECURITY_TLS_SESS_TYPE_WRITE,
+};
+
+/**
+ * Configure soft and hard lifetime of a TLS record session
+ *
+ * Lifetime of a TLS record session would specify the maximum number of

packets that can be
+ * processed. TLS record processing operations would start failing once hard limit is reached.
+ *
+ * Soft limits can be specified to generate notification when the TLS record session is approaching
+ * hard limits for lifetime. This would result in a warning returned in ``rte_crypto_op.aux_flags``.

+ */

lib/security/rte_security.h +36 -0

+struct rte_security_tls_record_lifetime {
+	/** Soft expiry limit in number of packets */
+	uint64_t packets_soft_limit;
+	/** Hard expiry limit in number of packets */
+	uint64_t packets_hard_limit;
+};
+
+/**
+ * TLS record protocol session configuration.
+ *
+ * This structure contains data required to create a TLS record security session.
+ */
+struct rte_security_tls_record_xform {
+	/** TLS record version. */
+	enum rte_security_tls_version ver;
+	/** TLS record session type. */
+	enum rte_security_tls_sess_type type;
+	/** TLS record session lifetime. */
+	struct rte_security_tls_record_lifetime life;
+	union {
+		/** TLS 1.2 parameters. */
+		struct {
+			/** Starting sequence number. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_TLS_1_2_SALT_LEN];
+		} tls_1_2;
+
+		/** TLS 1.3 parameters. */
+		struct {
+			/** Starting sequence number. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_TLS_1_3_SALT_LEN];
+			/**
+			 * Minimum payload length (in case of write sessions).

For shorter inputs,

lib/security/rte_security.h +1 -0

+			 * the payload would be padded appropriately before

performing crypto

lib/security/rte_security.h +14 -0

+			 * transformations.
+			 */
+			uint32_t min_payload_len;
+		} tls_1_3;
+
+		/** DTLS 1.2 parameters */
+		struct {
+			/** Epoch value to be used. */
+			uint16_t epoch;
+			/** 6B starting sequence number to be used. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_DTLS_1_2_SALT_LEN];
+			/** Anti replay window size to enable sequence replay

attack handling.

lib/security/rte_security.h +9 -0

+			 * Anti replay check is disabled if the window size is 0.
+			 */
+			uint32_t ar_win_sz;
+		} dtls_1_2;
+	};
+};
+
 /**
  * Security session action type.
  */

@@ -654,6 +747,8 @@ enum rte_security_session_protocol {
 	/**< PDCP Protocol */
 	RTE_SECURITY_PROTOCOL_DOCSIS,
 	/**< DOCSIS Protocol */
+	RTE_SECURITY_PROTOCOL_TLS_RECORD,
+	/**< TLS Record Protocol */
 };
 
 /**

lib/security/rte_security.h +7 -0

 	};
 	/**< Configuration parameters for security session */
 	struct rte_crypto_sym_xform *crypto_xform;

@@ -1190,6 +1286,16 @@ struct rte_security_capability {
 			/**< DOCSIS direction */
 		} docsis;
 		/**< DOCSIS capability */
+		struct {
+			enum rte_security_tls_version ver;
+			/**< TLS record version. */
+			enum rte_security_tls_sess_type type;
+			/**< TLS record session type. */
+			uint32_t ar_win_size;
+			/**< Maximum anti replay window size supported for

DTLS 1.2 record read

lib/security/rte_security.h +1 -0

+			 * operation. Value of 0 means anti replay check is not

supported.

lib/security/rte_security.h +4 -1

 	};
 
 	const struct rte_cryptodev_capabilities *crypto_capabilities;

@@ -1251,6 +1357,10 @@ struct rte_security_capability_idx {
 		struct {
 			enum rte_security_docsis_direction direction;
 		} docsis;
+		struct {
+			enum rte_security_tls_version ver;
+			enum rte_security_tls_sess_type type;
+		} tls_record;
 	};
 };
 
--

2.25.1

-----Original Message-----
From: Van Haaren, Harry <[email protected]>
Sent: Wednesday, September 20, 2023 2:53 PM
To: Anoob Joseph <[email protected]>; Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [EXT] RE: [RFC PATCH 2/3] security: add TLS record processing

External Email

----------------------------------------------------------------------

Quoted 29 lines

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Friday, August 11, 2023 8:17 AM
To: Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [RFC PATCH 2/3] security: add TLS record processing

Add Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS). The protocols provide communications privacy for L4 protocols such as TCP & UDP.

TLS (and DTLS) protocol is composed of two layers, 1. TLS Record Protocol 2. TLS Handshake Protocol

While TLS Handshake Protocol helps in establishing security parameters by which client and server can communicate, TLS Record Protocol provides the connection security. TLS Record Protocol leverages symmetric cryptographic operations such as data encryption and authentication for providing security to the communications.

Cryptodevs that are capable of offloading TLS Record Protocol may perform other operations like IV generation, header insertion, atomic sequence number updates and anti-replay window check in addition to cryptographic transformations.

Quoted 1 line

The support is added for TLS 1.2, TLS 1.3 and DTLS 1.2.

From the code below, my understanding is that *ONLY* the record layer is being added/supported? The difference is described well above, but the intended support added is not clearly defined.

Suggest reword the last line to clarify:
"Support for TLS record protocol is added for TLS 1.2, TLS 1.3 and DTLS 1.2."

Quoted 41 lines

Signed-off-by Akhil Goyal <[email protected]>

Signed-off-by Anoob Joseph <[email protected]>

Signed-off-by Vidya Sagar Velumuri <[email protected]>

---
 doc/guides/prog_guide/rte_security.rst |  58 +++++++++++++
 lib/security/rte_security.c            |   4 +
 lib/security/rte_security.h            | 110 +++++++++++++++++++++++++
 3 files changed, 172 insertions(+)

doc/guides/prog_guide/rte_security.rst +0 -0

index 7418e35c1b..7716d7239f 100644
@@ -399,6 +399,64 @@ The API ``rte_security_macsec_sc_create`` returns

a handle for SC, and this handle is set in ``rte_security_macsec_xform`` to create a MACsec session using ``rte_security_session_create``.

doc/guides/prog_guide/rte_security.rst +5 -0

+TLS-Record Protocol
+~~~~~~~~~~~~~~~~~~~
+
+The Transport Layer Protocol provides communications security over
+the

Internet. The protocol

doc/guides/prog_guide/rte_security.rst +2 -0

+allows client/server applications to communicate in a way that is
+designed to

prevent eavesdropping,

doc/guides/prog_guide/rte_security.rst +4 -0

+tampering, or message forgery.
+
+TLS protocol is composed of two layers: the TLS Record Protocol and
+the TLS

Handshake Protocol. At

doc/guides/prog_guide/rte_security.rst +2 -0

+the lowest level, layered on top of some reliable transport protocol
+(e.g., TCP),

is the TLS Record

doc/guides/prog_guide/rte_security.rst +2 -0

+Protocol. The TLS Record Protocol provides connection security that
+has two

basic properties:

doc/guides/prog_guide/rte_security.rst The API ``rte_security_macsec_sc_create`` returns a handle for SC,

Quoted 3 lines

doc/guides/prog_guide/rte_security.rst +3 -0

+
+   -  The connection is private.  Symmetric cryptography is used for data
+      encryption (e.g., AES, DES, etc.).  The keys for this symmetric

encryption

doc/guides/prog_guide/rte_security.rst

Quoted 2 lines

doc/guides/prog_guide/rte_security.rst +2 -0

+      are generated uniquely for each connection and are based on a secret
+      negotiated by another protocol (such as the TLS Handshake Protocol).

The

doc/guides/prog_guide/rte_security.rst The API ``rte_security_macsec_sc_create`` returns a handle for SC, · line 426

Quoted 10 lines

doc/guides/prog_guide/rte_security.rst +10 -0

+      Record Protocol can also be used without encryption.
+
+   -  The connection is reliable.  Message transport includes a message
+      integrity check using a keyed MAC.  Secure hash functions (e.g.,
+      SHA-1, etc.) are used for MAC computations.  The Record Protocol
+      can operate without a MAC, but is generally only used in this mode
+      while another protocol is using the Record Protocol as a transport
+      for negotiating security parameters.
+
+.. code-block:: c

The code block below isn't C? Is there a better code block type for a text diagram?

Quoted 101 lines

doc/guides/prog_guide/rte_security.rst +32 -0

+             Record Write                   Record Read
+             ------------                   -----------
+
+             TLSPlaintext                  TLSCiphertext
+                  |                              |
+                  ~                              ~
+                  |                              |
+                  V                              V
+        +---------|----------+        +----------|---------+
+        | Seq. no generation |        | Seq. no generation |
+        +---------|----------+        +----------|---------+
+                  |                              |
+        +---------|----------+        +----------|---------+
+        |  Header insertion  |        |    Decryption &    |
+        +---------|----------+        |  MAC verification  |
+                  |                   +----------|---------+
+        +---------|----------+                   |
+        |  MAC generation &  |        +----------|---------+
+        |     Encryption     |        | TLS Header removal |
+        +---------|----------+        +----------|---------+
+                  |                              |
+                  ~                              ~
+                  |                              |
+                  V                              V
+            TLSCiphertext                  TLSPlaintext
+
+Supported Versions
+^^^^^^^^^^^^^^^^^^
+
+* TLS 1.2
+* TLS 1.3
+* DTLS 1.2
 
 Device Features and Capabilities
 ---------------------------------

lib/security/rte_security.c +2 -0

index c4d64bb8e9..bd7b026547 100644
@@ -282,6 +282,10 @@ rte_security_capability_get(struct
 rte_security_ctx *instance,
 				if (capability->docsis.direction ==
 							idx->docsis.direction)
 					return capability;
+			} else if (idx->protocol ==
 RTE_SECURITY_PROTOCOL_TLS_RECORD) {
+				if (capability->tls_record.ver == idx-

Quoted 1 line

tls_record.ver &&

lib/security/rte_security.c +1 -0

+				    capability->tls_record.type == idx-

Quoted 1 line

tls_record.type)

lib/security/rte_security.c +1 -0

+					return capability;
 			}
 		}
 	}

lib/security/rte_security.h +31 -0

index 3b2df526ba..b9d064ed84 100644
@@ -620,6 +620,99 @@ struct rte_security_docsis_xform {
 	/**< DOCSIS direction */
 };
 
+/** Salt len to be used with AEAD algos in TLS 1.2 */ #define
+RTE_SECURITY_TLS_1_2_SALT_LEN 4
+/** Salt len to be used with AEAD algos in TLS 1.3 */ #define
+RTE_SECURITY_TLS_1_3_SALT_LEN 12
+/** Salt len to be used with AEAD algos in DTLS 1.2 */ #define
+RTE_SECURITY_DTLS_1_2_SALT_LEN 4
+
+/** TLS version */
+enum rte_security_tls_version {
+	RTE_SECURITY_VERSION_TLS_1_2,	/**< TLS 1.2 */
+	RTE_SECURITY_VERSION_TLS_1_3,	/**< TLS 1.3 */
+	RTE_SECURITY_VERSION_DTLS_1_2,	/**< DTLS 1.2 */
+};
+
+/** TLS session type */
+enum rte_security_tls_sess_type {
+	/** Record read session
+	 * - Decrypt & digest verification.
+	 */
+	RTE_SECURITY_TLS_SESS_TYPE_READ,
+	/** Record write session
+	 * - Encrypt & digest generation.
+	 */
+	RTE_SECURITY_TLS_SESS_TYPE_WRITE,
+};
+
+/**
+ * Configure soft and hard lifetime of a TLS record session
+ *
+ * Lifetime of a TLS record session would specify the maximum number
+of

packets that can be
+ * processed. TLS record processing operations would start failing
+ once hard
limit is reached.
+ *
+ * Soft limits can be specified to generate notification when the TLS
+ record

Quoted 4 lines

session is approaching
+ * hard limits for lifetime. This would result in a warning returned
+ in
``rte_crypto_op.aux_flags``.

Can we define "a warning" better? Perhaps an example of a soft-limit and hard-limit, what the user can check aux_flags for, to identify? Or link to the appropriate part of the crypto_op.aux_flags documentation to help the user.

lib/security/rte_security.h struct rte_security_docsis_xform {

Quoted 12 lines

+ */

lib/security/rte_security.h +11 -0

+struct rte_security_tls_record_lifetime {
+	/** Soft expiry limit in number of packets */
+	uint64_t packets_soft_limit;
+	/** Hard expiry limit in number of packets */
+	uint64_t packets_hard_limit;
+};
+
+/**
+ * TLS record protocol session configuration.
+ *
+ * This structure contains data required to create a TLS record security

session.

Quoted 15 lines

+ */

lib/security/rte_security.h +14 -0

+struct rte_security_tls_record_xform {
+	/** TLS record version. */
+	enum rte_security_tls_version ver;
+	/** TLS record session type. */
+	enum rte_security_tls_sess_type type;
+	/** TLS record session lifetime. */
+	struct rte_security_tls_record_lifetime life;
+	union {
+		/** TLS 1.2 parameters. */
+		struct {
+			/** Starting sequence number. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_TLS_1_2_SALT_LEN];

lib/security/rte_security.h struct rte_security_docsis_xform {

Quoted 10 lines

lib/security/rte_security.h +10 -0

+		} tls_1_2;
+
+		/** TLS 1.3 parameters. */
+		struct {
+			/** Starting sequence number. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_TLS_1_3_SALT_LEN];
+			/**
+			 * Minimum payload length (in case of write

sessions).

Quoted 3 lines

For shorter inputs,

lib/security/rte_security.h +1 -0

+			 * the payload would be padded appropriately before

performing crypto

Replace "would be" with "must be"? And who must do this step, is it the application?

Quoted 5 lines

lib/security/rte_security.h +4 -0

+			 * transformations.
+			 */
+			uint32_t min_payload_len;
+		} tls_1_3;

lib/security/rte_security.h struct rte_security_docsis_xform {

Quoted 10 lines

lib/security/rte_security.h +10 -0

+
+		/** DTLS 1.2 parameters */
+		struct {
+			/** Epoch value to be used. */
+			uint16_t epoch;
+			/** 6B starting sequence number to be used. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_DTLS_1_2_SALT_LEN];
+			/** Anti replay window size to enable sequence

replay

Quoted 19 lines

attack handling.

lib/security/rte_security.h +9 -0

+			 * Anti replay check is disabled if the window size is 0.
+			 */
+			uint32_t ar_win_sz;
+		} dtls_1_2;
+	};
+};
+
 /**
  * Security session action type.
  */

@@ -654,6 +747,8 @@ enum rte_security_session_protocol {
 	/**< PDCP Protocol */
 	RTE_SECURITY_PROTOCOL_DOCSIS,
 	/**< DOCSIS Protocol */
+	RTE_SECURITY_PROTOCOL_TLS_RECORD,
+	/**< TLS Record Protocol */
 };
 

lib/security/rte_security.h struct rte_security_session_conf { · line 768

Quoted 6 lines

lib/security/rte_security.h +1 -0

 /**

@@ -670,6 +765,7 @@ struct rte_security_session_conf {
 		struct rte_security_macsec_xform macsec;
 		struct rte_security_pdcp_xform pdcp;
 		struct rte_security_docsis_xform docsis;
+		struct rte_security_tls_record_xform tls;

Do we see TLS handshake xform being added in future? If so, is 'tls' a good name, perhaps 'tls_record'?
That would allow 'tls_handshake' in future, with consistent naming scheme without API/ABI break.

lib/security/rte_security.h struct rte_security_session_conf {

Quoted 5 lines

lib/security/rte_security.h +0 -0

 	};
 	/**< Configuration parameters for security session */
 	struct rte_crypto_sym_xform *crypto_xform; @@ -1190,6 +1286,16

@@

lib/security/rte_security.h struct rte_security_capability {

Quoted 11 lines

struct rte_security_capability {

lib/security/rte_security.h +7 -0

 			/**< DOCSIS direction */
 		} docsis;
 		/**< DOCSIS capability */
+		struct {
+			enum rte_security_tls_version ver;
+			/**< TLS record version. */
+			enum rte_security_tls_sess_type type;
+			/**< TLS record session type. */
+			uint32_t ar_win_size;
+			/**< Maximum anti replay window size supported

for

lib/security/rte_security.h

Quoted 2 lines

DTLS 1.2 record read

lib/security/rte_security.h +1 -0

+			 * operation. Value of 0 means anti replay check is

not

lib/security/rte_security.h struct rte_security_capability { · line 1298

Quoted 3 lines

supported.

lib/security/rte_security.h +2 -0

+			 */
+		} tls_record;

Missing /**< TLS Record Capability */ docstring here.

Quoted 17 lines

lib/security/rte_security.h +4 -2

 	};
 
 	const struct rte_cryptodev_capabilities *crypto_capabilities; @@
-1251,6 +1357,10 @@ struct rte_security_capability_idx {
 		struct {
 			enum rte_security_docsis_direction direction;
 		} docsis;
+		struct {
+			enum rte_security_tls_version ver;
+			enum rte_security_tls_sess_type type;
+		} tls_record;
 	};
 };
 
--

2.25.1

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Wednesday, September 20, 2023 12:52 PM
To: Van Haaren, Harry <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>; Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Konstantin Ananyev <[email protected]>
Subject: RE: [RFC PATCH 2/3] security: add TLS record processing

Hi Harry,

Thanks for the review. Please see inline.

Thanks,
Anoob

Quoted 46 lines

-----Original Message-----
From: Van Haaren, Harry <[email protected]>
Sent: Wednesday, September 20, 2023 2:53 PM
To: Anoob Joseph <[email protected]>; Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [EXT] RE: [RFC PATCH 2/3] security: add TLS record processing

External Email

----------------------------------------------------------------------

Quoted 30 lines

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Friday, August 11, 2023 8:17 AM
To: Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [RFC PATCH 2/3] security: add TLS record processing

Add Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS). The protocols provide communications privacy for L4 protocols such as TCP & UDP.

TLS (and DTLS) protocol is composed of two layers, 1. TLS Record Protocol 2. TLS Handshake Protocol

While TLS Handshake Protocol helps in establishing security parameters by which client and server can communicate, TLS Record Protocol provides the connection security. TLS Record Protocol leverages symmetric cryptographic operations such as data encryption and authentication for providing security to the communications.

Cryptodevs that are capable of offloading TLS Record Protocol may perform other operations like IV generation, header insertion, atomic sequence number updates and anti-replay window check in addition to cryptographic transformations.

The support is added for TLS 1.2, TLS 1.3 and DTLS 1.2.

Quoted 6 lines

From the code below, my understanding is that *ONLY* the record layer is being added/supported? The difference is described well above, but the intended support added is not clearly defined.

Suggest reword the last line to clarify:
"Support for TLS record protocol is added for TLS 1.2, TLS 1.3 and DTLS 1.2."

[Anoob] Indeed. Will reword as suggested.

Quoted 46 lines

Quoted 39 lines

Signed-off-by Akhil Goyal <[email protected]>

Signed-off-by Anoob Joseph <[email protected]>

Signed-off-by Vidya Sagar Velumuri <[email protected]>

---
 doc/guides/prog_guide/rte_security.rst |  58 +++++++++++++
 lib/security/rte_security.c            |   4 +
 lib/security/rte_security.h            | 110 +++++++++++++++++++++++++
 3 files changed, 172 insertions(+)

doc/guides/prog_guide/rte_security.rst +0 -0

index 7418e35c1b..7716d7239f 100644
@@ -399,6 +399,64 @@ The API ``rte_security_macsec_sc_create`` returns

a handle for SC, and this handle is set in ``rte_security_macsec_xform`` to create a MACsec session using ``rte_security_session_create``.

doc/guides/prog_guide/rte_security.rst +5 -0

+TLS-Record Protocol
+~~~~~~~~~~~~~~~~~~~
+
+The Transport Layer Protocol provides communications security over
+the

Internet. The protocol

doc/guides/prog_guide/rte_security.rst +2 -0

+allows client/server applications to communicate in a way that is
+designed to

prevent eavesdropping,

doc/guides/prog_guide/rte_security.rst +4 -0

+tampering, or message forgery.
+
+TLS protocol is composed of two layers: the TLS Record Protocol and
+the TLS

Handshake Protocol. At

doc/guides/prog_guide/rte_security.rst +2 -0

+the lowest level, layered on top of some reliable transport protocol
+(e.g., TCP),

is the TLS Record

doc/guides/prog_guide/rte_security.rst +2 -0

+Protocol. The TLS Record Protocol provides connection security that
+has two

basic properties:

doc/guides/prog_guide/rte_security.rst The API ``rte_security_macsec_sc_create`` returns a handle for SC,

Quoted 3 lines

doc/guides/prog_guide/rte_security.rst +3 -0

+
+   -  The connection is private.  Symmetric cryptography is used for data
+      encryption (e.g., AES, DES, etc.).  The keys for this symmetric

encryption

doc/guides/prog_guide/rte_security.rst

Quoted 2 lines

doc/guides/prog_guide/rte_security.rst +2 -0

+      are generated uniquely for each connection and are based on a secret
+      negotiated by another protocol (such as the TLS Handshake Protocol).

The

Quoted 13 lines

doc/guides/prog_guide/rte_security.rst The API ``rte_security_macsec_sc_create`` returns a handle for SC, · line 426

Quoted 10 lines

doc/guides/prog_guide/rte_security.rst +10 -0

+      Record Protocol can also be used without encryption.
+
+   -  The connection is reliable.  Message transport includes a message
+      integrity check using a keyed MAC.  Secure hash functions (e.g.,
+      SHA-1, etc.) are used for MAC computations.  The Record Protocol
+      can operate without a MAC, but is generally only used in this mode
+      while another protocol is using the Record Protocol as a transport
+      for negotiating security parameters.
+
+.. code-block:: c

The code block below isn't C? Is there a better code block type for a text diagram?

[Anoob] Valid point. I was just following the general scheme followed in this file. May be, I'll introduce a .svg image for newly added code.

Quoted 100 lines

Quoted 100 lines

doc/guides/prog_guide/rte_security.rst +32 -0

+             Record Write                   Record Read
+             ------------                   -----------
+
+             TLSPlaintext                  TLSCiphertext
+                  |                              |
+                  ~                              ~
+                  |                              |
+                  V                              V
+        +---------|----------+        +----------|---------+
+        | Seq. no generation |        | Seq. no generation |
+        +---------|----------+        +----------|---------+
+                  |                              |
+        +---------|----------+        +----------|---------+
+        |  Header insertion  |        |    Decryption &    |
+        +---------|----------+        |  MAC verification  |
+                  |                   +----------|---------+
+        +---------|----------+                   |
+        |  MAC generation &  |        +----------|---------+
+        |     Encryption     |        | TLS Header removal |
+        +---------|----------+        +----------|---------+
+                  |                              |
+                  ~                              ~
+                  |                              |
+                  V                              V
+            TLSCiphertext                  TLSPlaintext
+
+Supported Versions
+^^^^^^^^^^^^^^^^^^
+
+* TLS 1.2
+* TLS 1.3
+* DTLS 1.2
 
 Device Features and Capabilities
 ---------------------------------

lib/security/rte_security.c +2 -0

index c4d64bb8e9..bd7b026547 100644
@@ -282,6 +282,10 @@ rte_security_capability_get(struct
 rte_security_ctx *instance,
 				if (capability->docsis.direction ==
 							idx->docsis.direction)
 					return capability;
+			} else if (idx->protocol ==
 RTE_SECURITY_PROTOCOL_TLS_RECORD) {
+				if (capability->tls_record.ver == idx-

Quoted 1 line

tls_record.ver &&

lib/security/rte_security.c +1 -0

+				    capability->tls_record.type == idx-

Quoted 1 line

tls_record.type)

lib/security/rte_security.c +1 -0

+					return capability;
 			}
 		}
 	}

lib/security/rte_security.h +31 -0

index 3b2df526ba..b9d064ed84 100644
@@ -620,6 +620,99 @@ struct rte_security_docsis_xform {
 	/**< DOCSIS direction */
 };
 
+/** Salt len to be used with AEAD algos in TLS 1.2 */ #define
+RTE_SECURITY_TLS_1_2_SALT_LEN 4
+/** Salt len to be used with AEAD algos in TLS 1.3 */ #define
+RTE_SECURITY_TLS_1_3_SALT_LEN 12
+/** Salt len to be used with AEAD algos in DTLS 1.2 */ #define
+RTE_SECURITY_DTLS_1_2_SALT_LEN 4
+
+/** TLS version */
+enum rte_security_tls_version {
+	RTE_SECURITY_VERSION_TLS_1_2,	/**< TLS 1.2 */
+	RTE_SECURITY_VERSION_TLS_1_3,	/**< TLS 1.3 */
+	RTE_SECURITY_VERSION_DTLS_1_2,	/**< DTLS 1.2 */
+};
+
+/** TLS session type */
+enum rte_security_tls_sess_type {
+	/** Record read session
+	 * - Decrypt & digest verification.
+	 */
+	RTE_SECURITY_TLS_SESS_TYPE_READ,
+	/** Record write session
+	 * - Encrypt & digest generation.
+	 */
+	RTE_SECURITY_TLS_SESS_TYPE_WRITE,
+};
+
+/**
+ * Configure soft and hard lifetime of a TLS record session
+ *
+ * Lifetime of a TLS record session would specify the maximum number
+of

packets that can be
+ * processed. TLS record processing operations would start failing
+ once hard
limit is reached.
+ *
+ * Soft limits can be specified to generate notification when the TLS
+ record

Quoted 9 lines

Quoted 4 lines

session is approaching
+ * hard limits for lifetime. This would result in a warning returned
+ in
``rte_crypto_op.aux_flags``.

Can we define "a warning" better? Perhaps an example of a soft-limit and hard-limit, what the user can check aux_flags for, to identify? Or link to the appropriate part of the crypto_op.aux_flags documentation to help the user.

[Anoob] The concept of lifetime is present in most protocols. Idea is to limit the max number of operations performed with a session. Soft expiry notification is to help application prepare for an expiry and setup a new session before the current one expires.

The idea was borrowed from IPsec which has the 'RTE_CRYPTO_OP_AUX_FLAGS_IPSEC_SOFT_EXPIRY' flag defined. But I realize, it should be better defined. I can rename the flag to 'RTE_CRYPTO_OP_AUX_FLAGS_SEC_SOFT_EXPIRY' to avoid redefining same flag for each security offload. Do you agree to this suggestion?

https://elixir.bootlin.com/dpdk/latest/source/lib/cryptodev/rte_crypto.h#L67

Do note that once hard expiry is hit, the operation would fail. Expectation is, cryptodev would return 'RTE_CRYPTO_OP_STATUS_ERROR' in case of errors.

Quoted 39 lines

lib/security/rte_security.h struct rte_security_docsis_xform {

Quoted 12 lines

+ */

lib/security/rte_security.h +11 -0

+struct rte_security_tls_record_lifetime {
+	/** Soft expiry limit in number of packets */
+	uint64_t packets_soft_limit;
+	/** Hard expiry limit in number of packets */
+	uint64_t packets_hard_limit;
+};
+
+/**
+ * TLS record protocol session configuration.
+ *
+ * This structure contains data required to create a TLS record security

session.

Quoted 15 lines

+ */

lib/security/rte_security.h +14 -0

+struct rte_security_tls_record_xform {
+	/** TLS record version. */
+	enum rte_security_tls_version ver;
+	/** TLS record session type. */
+	enum rte_security_tls_sess_type type;
+	/** TLS record session lifetime. */
+	struct rte_security_tls_record_lifetime life;
+	union {
+		/** TLS 1.2 parameters. */
+		struct {
+			/** Starting sequence number. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_TLS_1_2_SALT_LEN];

lib/security/rte_security.h struct rte_security_docsis_xform {

Quoted 10 lines

lib/security/rte_security.h +10 -0

+		} tls_1_2;
+
+		/** TLS 1.3 parameters. */
+		struct {
+			/** Starting sequence number. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_TLS_1_3_SALT_LEN];
+			/**
+			 * Minimum payload length (in case of write

sessions).

Quoted 6 lines

Quoted 3 lines

For shorter inputs,

lib/security/rte_security.h +1 -0

+			 * the payload would be padded appropriately before

performing crypto

Replace "would be" with "must be"? And who must do this step, is it the application?

[Anoob] Padding is performed by the PMD/cryptodev device. I'll change "would be" to "will be". Would that address your concern?

Quoted 35 lines

Quoted 5 lines

lib/security/rte_security.h +4 -0

+			 * transformations.
+			 */
+			uint32_t min_payload_len;
+		} tls_1_3;

lib/security/rte_security.h struct rte_security_docsis_xform {

Quoted 10 lines

lib/security/rte_security.h +10 -0

+
+		/** DTLS 1.2 parameters */
+		struct {
+			/** Epoch value to be used. */
+			uint16_t epoch;
+			/** 6B starting sequence number to be used. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_DTLS_1_2_SALT_LEN];
+			/** Anti replay window size to enable sequence

replay

Quoted 19 lines

attack handling.

lib/security/rte_security.h +9 -0

+			 * Anti replay check is disabled if the window size is 0.
+			 */
+			uint32_t ar_win_sz;
+		} dtls_1_2;
+	};
+};
+
 /**
  * Security session action type.
  */

@@ -654,6 +747,8 @@ enum rte_security_session_protocol {
 	/**< PDCP Protocol */
 	RTE_SECURITY_PROTOCOL_DOCSIS,
 	/**< DOCSIS Protocol */
+	RTE_SECURITY_PROTOCOL_TLS_RECORD,
+	/**< TLS Record Protocol */
 };
 

Quoted 11 lines

lib/security/rte_security.h struct rte_security_session_conf { · line 768

Quoted 6 lines

lib/security/rte_security.h +1 -0

 /**

@@ -670,6 +765,7 @@ struct rte_security_session_conf {
 		struct rte_security_macsec_xform macsec;
 		struct rte_security_pdcp_xform pdcp;
 		struct rte_security_docsis_xform docsis;
+		struct rte_security_tls_record_xform tls;

Do we see TLS handshake xform being added in future? If so, is 'tls' a good name, perhaps 'tls_record'?
That would allow 'tls_handshake' in future, with consistent naming scheme without API/ABI break.

[Anoob] In the future, I would like to see TLS handshake also offloaded in a similar manner. But that would need some fundamental changes in security library. Like, current security library is pretty much tied to symmetric operations but a handshake would involve both symmetric & asymmetric operations.

Said that, I agree with your suggestion to rename the field. Will change it to 'tls_record' in next version.

Quoted 22 lines

lib/security/rte_security.h struct rte_security_session_conf {

Quoted 6 lines

lib/security/rte_security.h +0 -0

 	};
 	/**< Configuration parameters for security session */
 	struct rte_crypto_sym_xform *crypto_xform; @@ -1190,6 +1286,16

@@

lib/security/rte_security.h struct rte_security_capability {

Quoted 11 lines

struct rte_security_capability {

lib/security/rte_security.h +7 -0

 			/**< DOCSIS direction */
 		} docsis;
 		/**< DOCSIS capability */
+		struct {
+			enum rte_security_tls_version ver;
+			/**< TLS record version. */
+			enum rte_security_tls_sess_type type;
+			/**< TLS record session type. */
+			uint32_t ar_win_size;
+			/**< Maximum anti replay window size supported

for

lib/security/rte_security.h

Quoted 2 lines

DTLS 1.2 record read

lib/security/rte_security.h +1 -0

+			 * operation. Value of 0 means anti replay check is

not

Quoted 5 lines

lib/security/rte_security.h struct rte_security_capability { · line 1298

Quoted 3 lines

supported.

lib/security/rte_security.h +2 -0

+			 */
+		} tls_record;

Missing /**< TLS Record Capability */ docstring here.

[Anoob] Agreed. Will add in next version.

-----Original Message-----
From: Van Haaren, Harry <[email protected]>
Sent: Thursday, September 21, 2023 2:09 PM
To: Anoob Joseph <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>; Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Konstantin Ananyev <[email protected]>
Subject: [EXT] RE: [RFC PATCH 2/3] security: add TLS record processing

External Email

----------------------------------------------------------------------

Quoted 7 lines

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Wednesday, September 20, 2023 12:52 PM
To: Van Haaren, Harry <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>; Thomas Monjalon <[email protected]>;

Akhil

Quoted 5 lines

Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Konstantin Ananyev <[email protected]>
Subject: RE: [RFC PATCH 2/3] security: add TLS record processing

Quoted 31 lines

Hi Harry,

Thanks for the review. Please see inline.

Thanks,
Anoob

Quoted 24 lines

-----Original Message-----
From: Van Haaren, Harry <[email protected]>
Sent: Wednesday, September 20, 2023 2:53 PM
To: Anoob Joseph <[email protected]>; Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [EXT] RE: [RFC PATCH 2/3] security: add TLS record processing

External Email

--------------------------------------------------------------------
--

Quoted 7 lines

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Friday, August 11, 2023 8:17 AM
To: Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected];

Matz,

Quoted 8 lines

Quoted 8 lines

Quoted 8 lines

Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [RFC PATCH 2/3] security: add TLS record processing

Add Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS). The protocols provide communications privacy for L4 protocols such as TCP & UDP.

Quoted 8 lines

Quoted 8 lines

Quoted 8 lines

TLS (and DTLS) protocol is composed of two layers, 1. TLS Record Protocol 2. TLS Handshake Protocol

While TLS Handshake Protocol helps in establishing security parameters by which client and server can communicate, TLS Record Protocol provides the connection security. TLS Record Protocol leverages symmetric cryptographic operations such as data encryption and authentication for providing security to the

communications.

Quoted 6 lines

Quoted 6 lines

Quoted 6 lines

Cryptodevs that are capable of offloading TLS Record Protocol may perform other operations like IV generation, header insertion, atomic sequence number updates and anti-replay window check in addition to cryptographic transformations.

Quoted 8 lines

Quoted 8 lines

Quoted 1 line

The support is added for TLS 1.2, TLS 1.3 and DTLS 1.2.

From the code below, my understanding is that *ONLY* the record layer is being added/supported? The difference is described well above, but the intended support added is not clearly defined.

Suggest reword the last line to clarify:
"Support for TLS record protocol is added for TLS 1.2, TLS 1.3 and DTLS

1.2."

Quoted 2 lines

[Anoob] Indeed. Will reword as suggested.

Thanks.

Quoted 44 lines

Quoted 44 lines

Quoted 39 lines

Signed-off-by Akhil Goyal <[email protected]>

Signed-off-by Anoob Joseph <[email protected]>

Signed-off-by Vidya Sagar Velumuri <[email protected]>

---
 doc/guides/prog_guide/rte_security.rst |  58 +++++++++++++
 lib/security/rte_security.c            |   4 +
 lib/security/rte_security.h            | 110 +++++++++++++++++++++++++
 3 files changed, 172 insertions(+)

doc/guides/prog_guide/rte_security.rst +0 -0

index 7418e35c1b..7716d7239f 100644
@@ -399,6 +399,64 @@ The API ``rte_security_macsec_sc_create``

returns a handle for SC, and this handle is set in ``rte_security_macsec_xform`` to create a MACsec session using ``rte_security_session_create``.

doc/guides/prog_guide/rte_security.rst +5 -0

+TLS-Record Protocol
+~~~~~~~~~~~~~~~~~~~
+
+The Transport Layer Protocol provides communications security
+over the

Internet. The protocol

doc/guides/prog_guide/rte_security.rst +2 -0

+allows client/server applications to communicate in a way that is
+designed to

prevent eavesdropping,

doc/guides/prog_guide/rte_security.rst +4 -0

+tampering, or message forgery.
+
+TLS protocol is composed of two layers: the TLS Record Protocol
+and the TLS

Handshake Protocol. At

doc/guides/prog_guide/rte_security.rst +2 -0

+the lowest level, layered on top of some reliable transport
+protocol (e.g., TCP),

is the TLS Record

doc/guides/prog_guide/rte_security.rst +2 -0

+Protocol. The TLS Record Protocol provides connection security
+that has two

basic properties:

doc/guides/prog_guide/rte_security.rst The API ``rte_security_macsec_sc_create`` returns a handle for SC,

Quoted 4 lines

doc/guides/prog_guide/rte_security.rst +4 -0

+
+   -  The connection is private.  Symmetric cryptography is used for data
+      encryption (e.g., AES, DES, etc.).  The keys for this
+ symmetric

encryption

Quoted 1 line

Quoted 1 line

Quoted 1 line

+ are generated uniquely for each connection and are based on a

secret

Quoted 1 line

Quoted 1 line

Quoted 1 line

+ negotiated by another protocol (such as the TLS Handshake

Protocol).

Quoted 15 lines

Quoted 14 lines

The

doc/guides/prog_guide/rte_security.rst The API ``rte_security_macsec_sc_create`` returns a handle for SC, · line 426

Quoted 10 lines

doc/guides/prog_guide/rte_security.rst +10 -0

+      Record Protocol can also be used without encryption.
+
+   -  The connection is reliable.  Message transport includes a message
+      integrity check using a keyed MAC.  Secure hash functions (e.g.,
+      SHA-1, etc.) are used for MAC computations.  The Record Protocol
+      can operate without a MAC, but is generally only used in this mode
+      while another protocol is using the Record Protocol as a transport
+      for negotiating security parameters.
+
+.. code-block:: c

The code block below isn't C? Is there a better code block type for a text diagram?

Quoted 1 line

[Anoob] Valid point. I was just following the general scheme followed in

this file.

Quoted 1 line

May be, I'll introduce a .svg image for newly added code.

This was a nit-pick that perhaps "code-block:: text-diagram" or so exists. No need to make a .svg in my opinion, the text-diagrams are clear.

Quoted 101 lines

Quoted 101 lines

Quoted 101 lines

doc/guides/prog_guide/rte_security.rst +32 -0

+             Record Write                   Record Read
+             ------------                   -----------
+
+             TLSPlaintext                  TLSCiphertext
+                  |                              |
+                  ~                              ~
+                  |                              |
+                  V                              V
+        +---------|----------+        +----------|---------+
+        | Seq. no generation |        | Seq. no generation |
+        +---------|----------+        +----------|---------+
+                  |                              |
+        +---------|----------+        +----------|---------+
+        |  Header insertion  |        |    Decryption &    |
+        +---------|----------+        |  MAC verification  |
+                  |                   +----------|---------+
+        +---------|----------+                   |
+        |  MAC generation &  |        +----------|---------+
+        |     Encryption     |        | TLS Header removal |
+        +---------|----------+        +----------|---------+
+                  |                              |
+                  ~                              ~
+                  |                              |
+                  V                              V
+            TLSCiphertext                  TLSPlaintext
+
+Supported Versions
+^^^^^^^^^^^^^^^^^^
+
+* TLS 1.2
+* TLS 1.3
+* DTLS 1.2
 
 Device Features and Capabilities
 --------------------------------- diff --git

a/lib/security/rte_security.c b/lib/security/rte_security.c index c4d64bb8e9..bd7b026547 100644

lib/security/rte_security.c +2 -0

@@ -282,6 +282,10 @@ rte_security_capability_get(struct
 rte_security_ctx *instance,
 				if (capability->docsis.direction ==
 							idx->docsis.direction)
 					return capability;
+			} else if (idx->protocol ==
 RTE_SECURITY_PROTOCOL_TLS_RECORD) {
+				if (capability->tls_record.ver == idx-

Quoted 1 line

tls_record.ver &&

lib/security/rte_security.c +1 -0

+				    capability->tls_record.type == idx-

Quoted 1 line

tls_record.type)

lib/security/rte_security.c +1 -0

+					return capability;
 			}
 		}
 	}

(quoted diff) +0 -0

b/lib/security/rte_security.h index 3b2df526ba..b9d064ed84 100644

lib/security/rte_security.h +30 -0

@@ -620,6 +620,99 @@ struct rte_security_docsis_xform {
 	/**< DOCSIS direction */
 };
 
+/** Salt len to be used with AEAD algos in TLS 1.2 */ #define
+RTE_SECURITY_TLS_1_2_SALT_LEN 4
+/** Salt len to be used with AEAD algos in TLS 1.3 */ #define
+RTE_SECURITY_TLS_1_3_SALT_LEN 12
+/** Salt len to be used with AEAD algos in DTLS 1.2 */ #define
+RTE_SECURITY_DTLS_1_2_SALT_LEN 4
+
+/** TLS version */
+enum rte_security_tls_version {
+	RTE_SECURITY_VERSION_TLS_1_2,	/**< TLS 1.2 */
+	RTE_SECURITY_VERSION_TLS_1_3,	/**< TLS 1.3 */
+	RTE_SECURITY_VERSION_DTLS_1_2,	/**< DTLS 1.2 */
+};
+
+/** TLS session type */
+enum rte_security_tls_sess_type {
+	/** Record read session
+	 * - Decrypt & digest verification.
+	 */
+	RTE_SECURITY_TLS_SESS_TYPE_READ,
+	/** Record write session
+	 * - Encrypt & digest generation.
+	 */
+	RTE_SECURITY_TLS_SESS_TYPE_WRITE, };
+
+/**
+ * Configure soft and hard lifetime of a TLS record session
+ *
+ * Lifetime of a TLS record session would specify the maximum
+number of

packets that can be
+ * processed. TLS record processing operations would start
+ failing once hard
limit is reached.
+ *
+ * Soft limits can be specified to generate notification when the
+ TLS record

Quoted 8 lines

Quoted 8 lines

Quoted 4 lines

session is approaching
+ * hard limits for lifetime. This would result in a warning
+ returned in
``rte_crypto_op.aux_flags``.

Can we define "a warning" better? Perhaps an example of a soft-limit and hard-limit, what the user can check aux_flags for, to identify? Or link to the appropriate part of the crypto_op.aux_flags documentation

to help the user.

Quoted 6 lines

Quoted 1 line

[Anoob] The concept of lifetime is present in most protocols. Idea is to limit the max number of operations performed with a session. Soft expiry notification is to help application prepare for an expiry and setup a new session before the current one expires.

Understood, yes.

Quoted 4 lines

The idea was borrowed from IPsec which has the 'RTE_CRYPTO_OP_AUX_FLAGS_IPSEC_SOFT_EXPIRY' flag defined. But I realize, it should be better defined. I can rename the flag to 'RTE_CRYPTO_OP_AUX_FLAGS_SEC_SOFT_EXPIRY' to avoid redefining

same

Quoted 4 lines

flag for each security offload. Do you agree to this suggestion?

https://urldefense.proofpoint.com/v2/url?u=https-3A__elixir.bootlin.co
m_dpdk_latest_source_lib_cryptodev_rte-5Fcrypto.h-

23L67&d=DwIFAg&c=nKj

Quoted 1 line

Wec2b6R0mOyPaz7xtfQ&r=jPfB8rwwviRSxyLWs2n6B-

WYLn1v9SyTMrT5EQqh2TU&m=F6

Quoted 1 line

WuwwuvXG0eJ1IWAMFgcXlMdQwKFDx6C1qsQgSaDa2XGr3PZ6LEDtSw0OeC DstG&s=0iO8Y

Quoted 1 line

sr0f4cnE8ihg40sZfEEZfPzEXvJBvcNcyOdS98&e=

So we cannot "just rename" the flag, its an API break. It likely is possible to add an additional #define with the same value as IPSEC_SOFT_EXPIRY, and call it SEC_SOFT_EXPIRY.
Is that the best/most descriptive name? SYM_ALG_SOFT_EXPIRY? I'm not sure here, input welcomed.

Perhaps we can improve the doc-string there, to explain what it means a bit more verbosely.

Quoted 3 lines

Do note that once hard expiry is hit, the operation would fail. Expectation is, cryptodev would return 'RTE_CRYPTO_OP_STATUS_ERROR'

in case of errors.

That is good.

Quoted 47 lines

Quoted 40 lines

lib/security/rte_security.h struct rte_security_docsis_xform {

Quoted 13 lines

+ */

lib/security/rte_security.h +12 -0

+struct rte_security_tls_record_lifetime {
+	/** Soft expiry limit in number of packets */
+	uint64_t packets_soft_limit;
+	/** Hard expiry limit in number of packets */
+	uint64_t packets_hard_limit;
+};
+
+/**
+ * TLS record protocol session configuration.
+ *
+ * This structure contains data required to create a TLS record
+security

session.

Quoted 15 lines

+ */

lib/security/rte_security.h +14 -0

+struct rte_security_tls_record_xform {
+	/** TLS record version. */
+	enum rte_security_tls_version ver;
+	/** TLS record session type. */
+	enum rte_security_tls_sess_type type;
+	/** TLS record session lifetime. */
+	struct rte_security_tls_record_lifetime life;
+	union {
+		/** TLS 1.2 parameters. */
+		struct {
+			/** Starting sequence number. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_TLS_1_2_SALT_LEN];

lib/security/rte_security.h struct rte_security_docsis_xform {

Quoted 10 lines

lib/security/rte_security.h +10 -0

+		} tls_1_2;
+
+		/** TLS 1.3 parameters. */
+		struct {
+			/** Starting sequence number. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_TLS_1_3_SALT_LEN];
+			/**
+			 * Minimum payload length (in case of write

sessions).

Quoted 6 lines

Quoted 3 lines

For shorter inputs,

lib/security/rte_security.h +1 -0

+			 * the payload would be padded appropriately before

performing crypto

Replace "would be" with "must be"? And who must do this step, is it the application?

Quoted 2 lines

[Anoob] Padding is performed by the PMD/cryptodev device. I'll change "would be" to "will be". Would that address your concern?

I suppose my concern is "is it clear to PMD authors that they must implement X in their PMD", and to ensure we (DPDK community) do our best to clarify API demands, and to ensure future contributions are of high quality too.

For example, could we have a security library unit-test that checks the padding case, to ensure correct & consistent behaviour across different crypto PMDs?

Same thoughts for SOFT and HARD error variants, (although they might take... hours?) to execute.
But it is nice to automate-and-test these "corner cases".

It's not about wording, its about clarity between PMD devs, security library devs, and application facing APIs, to ensure that DPDK provides the most/best help it can to provide correctness. Does that clarify what I'd like to see?

For this patchset, could we document a list of "caveats" when implementing PMD functionality for TLS-record security offload, and indicate that:
1) Padding must be added by the PMD based on security library flags& algo in use, not application layer (I know this is demanded by the sym algos anyway, but let's make it explicit)

2) It is strongly recommended to build unit-tests for _SOFT and _HARD error cases (potentially by "fast forwarding" the internal counters via private APIs to avoid hours of enc/decryption)

I think that limits scope-impact to this patchset, but is clear for PMD implementations in future what expectations are.
Thoughts, is that a good way forward?

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Thursday, September 21, 2023 11:55 AM
To: Van Haaren, Harry <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>; Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Konstantin Ananyev <[email protected]>
Subject: RE: [RFC PATCH 2/3] security: add TLS record processing

Hi Harry,

Please see inline.

Thanks,
Anoob

Quoted 160 lines

-----Original Message-----
From: Van Haaren, Harry <[email protected]>
Sent: Thursday, September 21, 2023 2:09 PM
To: Anoob Joseph <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>; Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Konstantin Ananyev <[email protected]>
Subject: [EXT] RE: [RFC PATCH 2/3] security: add TLS record processing

External Email

----------------------------------------------------------------------

Quoted 7 lines

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Wednesday, September 20, 2023 12:52 PM
To: Van Haaren, Harry <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>; Thomas Monjalon <[email protected]>;

Akhil

Quoted 5 lines

Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Konstantin Ananyev <[email protected]>
Subject: RE: [RFC PATCH 2/3] security: add TLS record processing

Quoted 31 lines

Hi Harry,

Thanks for the review. Please see inline.

Thanks,
Anoob

Quoted 24 lines

-----Original Message-----
From: Van Haaren, Harry <[email protected]>
Sent: Wednesday, September 20, 2023 2:53 PM
To: Anoob Joseph <[email protected]>; Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [EXT] RE: [RFC PATCH 2/3] security: add TLS record processing

External Email

--------------------------------------------------------------------
--

Quoted 7 lines

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Friday, August 11, 2023 8:17 AM
To: Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected];

Matz,

Quoted 8 lines

Quoted 8 lines

Quoted 8 lines

Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [RFC PATCH 2/3] security: add TLS record processing

Add Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS). The protocols provide communications privacy for L4 protocols such as TCP & UDP.

Quoted 8 lines

Quoted 8 lines

Quoted 8 lines

TLS (and DTLS) protocol is composed of two layers, 1. TLS Record Protocol 2. TLS Handshake Protocol

While TLS Handshake Protocol helps in establishing security parameters by which client and server can communicate, TLS Record Protocol provides the connection security. TLS Record Protocol leverages symmetric cryptographic operations such as data encryption and authentication for providing security to the

communications.

Quoted 6 lines

Quoted 6 lines

Quoted 6 lines

Cryptodevs that are capable of offloading TLS Record Protocol may perform other operations like IV generation, header insertion, atomic sequence number updates and anti-replay window check in addition to cryptographic transformations.

Quoted 8 lines

Quoted 8 lines

Quoted 1 line

The support is added for TLS 1.2, TLS 1.3 and DTLS 1.2.

From the code below, my understanding is that *ONLY* the record layer is being added/supported? The difference is described well above, but the intended support added is not clearly defined.

Suggest reword the last line to clarify:
"Support for TLS record protocol is added for TLS 1.2, TLS 1.3 and DTLS

1.2."

Quoted 2 lines

[Anoob] Indeed. Will reword as suggested.

Thanks.

Quoted 44 lines

Quoted 44 lines

Quoted 39 lines

Signed-off-by Akhil Goyal <[email protected]>

Signed-off-by Anoob Joseph <[email protected]>

Signed-off-by Vidya Sagar Velumuri <[email protected]>

---
 doc/guides/prog_guide/rte_security.rst |  58 +++++++++++++
 lib/security/rte_security.c            |   4 +
 lib/security/rte_security.h            | 110 +++++++++++++++++++++++++
 3 files changed, 172 insertions(+)

doc/guides/prog_guide/rte_security.rst +0 -0

index 7418e35c1b..7716d7239f 100644
@@ -399,6 +399,64 @@ The API ``rte_security_macsec_sc_create``

returns a handle for SC, and this handle is set in ``rte_security_macsec_xform`` to create a MACsec session using ``rte_security_session_create``.

doc/guides/prog_guide/rte_security.rst +5 -0

+TLS-Record Protocol
+~~~~~~~~~~~~~~~~~~~
+
+The Transport Layer Protocol provides communications security
+over the

Internet. The protocol

doc/guides/prog_guide/rte_security.rst +2 -0

+allows client/server applications to communicate in a way that is
+designed to

prevent eavesdropping,

doc/guides/prog_guide/rte_security.rst +4 -0

+tampering, or message forgery.
+
+TLS protocol is composed of two layers: the TLS Record Protocol
+and the TLS

Handshake Protocol. At

doc/guides/prog_guide/rte_security.rst +2 -0

+the lowest level, layered on top of some reliable transport
+protocol (e.g., TCP),

is the TLS Record

doc/guides/prog_guide/rte_security.rst +2 -0

+Protocol. The TLS Record Protocol provides connection security
+that has two

basic properties:

doc/guides/prog_guide/rte_security.rst The API ``rte_security_macsec_sc_create`` returns a handle for SC,

Quoted 4 lines

doc/guides/prog_guide/rte_security.rst +4 -0

+
+   -  The connection is private.  Symmetric cryptography is used for data
+      encryption (e.g., AES, DES, etc.).  The keys for this
+ symmetric

encryption

Quoted 1 line

Quoted 1 line

Quoted 1 line

+ are generated uniquely for each connection and are based on a

secret

Quoted 1 line

Quoted 1 line

Quoted 1 line

+ negotiated by another protocol (such as the TLS Handshake

Protocol).

Quoted 15 lines

Quoted 14 lines

The

doc/guides/prog_guide/rte_security.rst The API ``rte_security_macsec_sc_create`` returns a handle for SC, · line 426

Quoted 10 lines

doc/guides/prog_guide/rte_security.rst +10 -0

+      Record Protocol can also be used without encryption.
+
+   -  The connection is reliable.  Message transport includes a message
+      integrity check using a keyed MAC.  Secure hash functions (e.g.,
+      SHA-1, etc.) are used for MAC computations.  The Record Protocol
+      can operate without a MAC, but is generally only used in this mode
+      while another protocol is using the Record Protocol as a transport
+      for negotiating security parameters.
+
+.. code-block:: c

The code block below isn't C? Is there a better code block type for a text diagram?

Quoted 6 lines

Quoted 1 line

[Anoob] Valid point. I was just following the general scheme followed in

this file.

Quoted 1 line

May be, I'll introduce a .svg image for newly added code.

This was a nit-pick that perhaps "code-block:: text-diagram" or so exists. No need to make a .svg in my opinion, the text-diagrams are clear.

[Anoob] Thanks for the confirmation. I do not think "code-block:: text-diagram" exists. Anyway, I'll improve the diagrams to make the padding etc more clear.

Quoted 137 lines

Quoted 35 lines

Quoted 35 lines

Quoted 35 lines

doc/guides/prog_guide/rte_security.rst +32 -0

+             Record Write                   Record Read
+             ------------                   -----------
+
+             TLSPlaintext                  TLSCiphertext
+                  |                              |
+                  ~                              ~
+                  |                              |
+                  V                              V
+        +---------|----------+        +----------|---------+
+        | Seq. no generation |        | Seq. no generation |
+        +---------|----------+        +----------|---------+
+                  |                              |
+        +---------|----------+        +----------|---------+
+        |  Header insertion  |        |    Decryption &    |
+        +---------|----------+        |  MAC verification  |
+                  |                   +----------|---------+
+        +---------|----------+                   |
+        |  MAC generation &  |        +----------|---------+
+        |     Encryption     |        | TLS Header removal |
+        +---------|----------+        +----------|---------+
+                  |                              |
+                  ~                              ~
+                  |                              |
+                  V                              V
+            TLSCiphertext                  TLSPlaintext
+
+Supported Versions
+^^^^^^^^^^^^^^^^^^
+
+* TLS 1.2
+* TLS 1.3
+* DTLS 1.2

Quoted 10 lines

Quoted 10 lines

lib/security/rte_security.c rte_security_capability_get(struct · line 284

Quoted 10 lines

Device Features and Capabilities --------------------------------- diff --git
a/lib/security/rte_security.c b/lib/security/rte_security.c index c4d64bb8e9..bd7b026547 100644

lib/security/rte_security.c +0 -0

@@ -282,6 +282,10 @@ rte_security_capability_get(struct
 rte_security_ctx *instance,
 				if (capability->docsis.direction ==
 							idx-

docsis.direction)

Quoted 56 lines

Quoted 56 lines

Quoted 56 lines

lib/security/rte_security.c +2 -0

 					return capability;
+			} else if (idx->protocol ==
 RTE_SECURITY_PROTOCOL_TLS_RECORD) {
+				if (capability->tls_record.ver == idx-

Quoted 1 line

tls_record.ver &&

lib/security/rte_security.c +1 -0

+				    capability->tls_record.type == idx-

Quoted 1 line

tls_record.type)

lib/security/rte_security.c +1 -0

+					return capability;
 			}
 		}
 	}

(quoted diff) +0 -0

b/lib/security/rte_security.h index 3b2df526ba..b9d064ed84 100644

lib/security/rte_security.h +30 -0

@@ -620,6 +620,99 @@ struct rte_security_docsis_xform {
 	/**< DOCSIS direction */
 };
 
+/** Salt len to be used with AEAD algos in TLS 1.2 */ #define
+RTE_SECURITY_TLS_1_2_SALT_LEN 4
+/** Salt len to be used with AEAD algos in TLS 1.3 */ #define
+RTE_SECURITY_TLS_1_3_SALT_LEN 12
+/** Salt len to be used with AEAD algos in DTLS 1.2 */ #define
+RTE_SECURITY_DTLS_1_2_SALT_LEN 4
+
+/** TLS version */
+enum rte_security_tls_version {
+	RTE_SECURITY_VERSION_TLS_1_2,	/**< TLS 1.2 */
+	RTE_SECURITY_VERSION_TLS_1_3,	/**< TLS 1.3 */
+	RTE_SECURITY_VERSION_DTLS_1_2,	/**< DTLS 1.2 */
+};
+
+/** TLS session type */
+enum rte_security_tls_sess_type {
+	/** Record read session
+	 * - Decrypt & digest verification.
+	 */
+	RTE_SECURITY_TLS_SESS_TYPE_READ,
+	/** Record write session
+	 * - Encrypt & digest generation.
+	 */
+	RTE_SECURITY_TLS_SESS_TYPE_WRITE, };
+
+/**
+ * Configure soft and hard lifetime of a TLS record session
+ *
+ * Lifetime of a TLS record session would specify the maximum
+number of

packets that can be
+ * processed. TLS record processing operations would start
+ failing once hard
limit is reached.
+ *
+ * Soft limits can be specified to generate notification when the
+ TLS record

Quoted 8 lines

Quoted 8 lines

Quoted 4 lines

session is approaching
+ * hard limits for lifetime. This would result in a warning
+ returned in
``rte_crypto_op.aux_flags``.

Can we define "a warning" better? Perhaps an example of a soft-limit and hard-limit, what the user can check aux_flags for, to identify? Or link to the appropriate part of the crypto_op.aux_flags documentation

to help the user.

Quoted 6 lines

Quoted 1 line

[Anoob] The concept of lifetime is present in most protocols. Idea is to limit the max number of operations performed with a session. Soft expiry notification is to help application prepare for an expiry and setup a new session before the current one expires.

Understood, yes.

Quoted 4 lines

The idea was borrowed from IPsec which has the 'RTE_CRYPTO_OP_AUX_FLAGS_IPSEC_SOFT_EXPIRY' flag defined. But I realize, it should be better defined. I can rename the flag to 'RTE_CRYPTO_OP_AUX_FLAGS_SEC_SOFT_EXPIRY' to avoid redefining

same

Quoted 4 lines

flag for each security offload. Do you agree to this suggestion?

https://urldefense.proofpoint.com/v2/url?u=https-3A__elixir.bootlin.co
m_dpdk_latest_source_lib_cryptodev_rte-5Fcrypto.h-

23L67&d=DwIFAg&c=nKj

Quoted 1 line

Wec2b6R0mOyPaz7xtfQ&r=jPfB8rwwviRSxyLWs2n6B-

WYLn1v9SyTMrT5EQqh2TU&m=F6

Quoted 1 line

WuwwuvXG0eJ1IWAMFgcXlMdQwKFDx6C1qsQgSaDa2XGr3PZ6LEDtSw0OeC DstG&s=0iO8Y

Quoted 1 line

sr0f4cnE8ihg40sZfEEZfPzEXvJBvcNcyOdS98&e=

Quoted 8 lines

So we cannot "just rename" the flag, its an API break. It likely is possible to add an additional #define with the same value as IPSEC_SOFT_EXPIRY, and call it SEC_SOFT_EXPIRY.
Is that the best/most descriptive name? SYM_ALG_SOFT_EXPIRY? I'm not sure here, input welcomed.

Perhaps we can improve the doc-string there, to explain what it means a bit more verbosely.

[Anoob] Agreed. Let me try to improve these aspects in next version. We can revisit this topic after that and see if we are able to reach a conclusion.

Quoted 48 lines

Quoted 3 lines

Do note that once hard expiry is hit, the operation would fail. Expectation is, cryptodev would return 'RTE_CRYPTO_OP_STATUS_ERROR'

in case of errors.

That is good.

Quoted 40 lines

Quoted 40 lines

lib/security/rte_security.h struct rte_security_docsis_xform {

Quoted 13 lines

+ */

lib/security/rte_security.h +12 -0

+struct rte_security_tls_record_lifetime {
+	/** Soft expiry limit in number of packets */
+	uint64_t packets_soft_limit;
+	/** Hard expiry limit in number of packets */
+	uint64_t packets_hard_limit;
+};
+
+/**
+ * TLS record protocol session configuration.
+ *
+ * This structure contains data required to create a TLS record
+security

session.

Quoted 15 lines

+ */

lib/security/rte_security.h +14 -0

+struct rte_security_tls_record_xform {
+	/** TLS record version. */
+	enum rte_security_tls_version ver;
+	/** TLS record session type. */
+	enum rte_security_tls_sess_type type;
+	/** TLS record session lifetime. */
+	struct rte_security_tls_record_lifetime life;
+	union {
+		/** TLS 1.2 parameters. */
+		struct {
+			/** Starting sequence number. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_TLS_1_2_SALT_LEN];

lib/security/rte_security.h struct rte_security_docsis_xform {

Quoted 10 lines

lib/security/rte_security.h +10 -0

+		} tls_1_2;
+
+		/** TLS 1.3 parameters. */
+		struct {
+			/** Starting sequence number. */
+			uint64_t seq_no;
+			/** Salt to be used for AEAD algos. */
+			uint8_t salt[RTE_SECURITY_TLS_1_3_SALT_LEN];
+			/**
+			 * Minimum payload length (in case of write

sessions).

Quoted 2 lines

Quoted 2 lines

Quoted 2 lines

lib/security/rte_security.h

Quoted 2 lines

For shorter inputs,

lib/security/rte_security.h +1 -0

+			 * the payload would be padded appropriately

before

Quoted 8 lines

Quoted 7 lines

Quoted 4 lines

Quoted 1 line

performing crypto

Replace "would be" with "must be"? And who must do this step, is it the application?

[Anoob] Padding is performed by the PMD/cryptodev device. I'll change "would be" to "will be". Would that address your concern?

Quoted 7 lines

I suppose my concern is "is it clear to PMD authors that they must implement X in their PMD", and to ensure we (DPDK community) do our best to clarify API demands, and to ensure future contributions are of high quality too.

For example, could we have a security library unit-test that checks the padding case, to ensure correct & consistent behaviour across different crypto PMDs?

[Anoob] Glad that you brought up that point. For IPsec, we have rather extensive framework which covers all the features that are supported today in rte_security. Features like soft expiry & hard expiry are tested on platforms that support the same. As for TLS, we are working on adding unit test framework. It would be part of the next version.

Quoted 3 lines

Same thoughts for SOFT and HARD error variants, (although they might take... hours?) to execute.
But it is nice to automate-and-test these "corner cases".

[Anoob] It won't. Soft expiry can be very low value as well. It is already covered. Please check.
https://elixir.bootlin.com/dpdk/latest/source/app/test/test_cryptodev.c#L10272

Quoted 4 lines

It's not about wording, its about clarity between PMD devs, security library devs, and application facing APIs, to ensure that DPDK provides the most/best help it can to provide correctness. Does that clarify what I'd like to see?

[Anoob] I understand your concern. My understanding is that for security offloads (rte_security lib), documentation has complete details of application & PMD expectations. If we have missed some features, we can take a re-look at the features and add as required. Other than documentation, do you have any other suggestions in mind?

Quoted 5 lines

For this patchset, could we document a list of "caveats" when implementing PMD functionality for TLS-record security offload, and indicate that:
1) Padding must be added by the PMD based on security library flags& algo in use, not application layer (I know this is demanded by the sym algos anyway, but let's make it explicit)

[Anoob] Agreed. Will update documentation as required.

Quoted 3 lines

2) It is strongly recommended to build unit-tests for _SOFT and _HARD error cases (potentially by "fast forwarding" the internal counters via private APIs to avoid hours of enc/decryption)

[Anoob] For IPsec, it is already added. For TLS, we have plans to add the same.

Quoted 4 lines

I think that limits scope-impact to this patchset, but is clear for PMD implementations in future what expectations are.
Thoughts, is that a good way forward?

[Anoob] Indeed. Having a very well defined API interface for applications is a very positive change. I'm open to more ideas than just updating the documentation.

Appreciate your feedback.

<snip>

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Friday, August 11, 2023 8:17 AM
To: Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [RFC PATCH 3/3] cryptodev: add details of datapath handling of TLS records

TLS/DTLS record processing requires content type to be provided per packet (for record write operation). Extend usage of rte_crypto_op.aux_flags for the same purpose.

Signed-off-by Akhil Goyal <[email protected]>

Signed-off-by Anoob Joseph <[email protected]>

Signed-off-by Vidya Sagar Velumuri <[email protected]>

---
 doc/guides/prog_guide/rte_security.rst | 10 ++++++++++
 lib/cryptodev/rte_crypto.h             |  6 ++++++
 2 files changed, 16 insertions(+)

doc/guides/prog_guide/rte_security.rst +0 -0

index 7716d7239f..6cb69bc949 100644
@@ -451,6 +451,16 @@ Protocol. The TLS Record Protocol provides

connection security that has two basi
V V
TLSCiphertext TLSPlaintext

+TLS and DTLS header formation (in record write operation) would depend on the

doc/guides/prog_guide/rte_security.rst +6 -0

+type of content. It is a per packet variable and would need to be handled by
+the same session. Application may pass this info to a cryptodev performing
+lookaside protocol offload by passing the same in ``rte_crypto_op.aux_flags``.
+
+In record read operation, application is required to preserve any info it may
+need from the TLS/DTLS header (such as content type and sequence number)

as the
+cryptodev would remove the header and padding as part of the lookaside protocol

doc/guides/prog_guide/rte_security.rst +2 -0

+processing.
+
 Supported Versions
 ^^^^^^^^^^^^^^^^^^

lib/cryptodev/rte_crypto.h +0 -0

index 9b8d0331a4..7c12a2b705 100644

lib/cryptodev/rte_crypto.h +0 -1

 			uint8_t reserved[2];
 			/**< Reserved bytes to fill 64 bits for
--

2.25.1

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Friday, August 11, 2023 8:17 AM
To: Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob <[email protected]>; Konstantin Ananyev <[email protected]>
Cc: Hemant Agrawal <[email protected]>; [email protected]; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [RFC PATCH 0/3] add TLS record processing security offload

Add Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS). The protocols provide communications privacy for L4 protocols such as TCP & UDP.

TLS (and DTLS) protocol is composed of two layers,
1. TLS Record Protocol
2. TLS Handshake Protocol

While TLS Handshake Protocol helps in establishing security parameters by which client and server can communicate, TLS Record Protocol provides the connection security. TLS Record Protocol leverages symmetric cryptographic operations such as data encryption and authentication for providing security to the communications.

Cryptodevs that are capable of offloading TLS Record Protocol may perform other operations like IV generation, header insertion, atomic sequence number updates and anti-replay window check in addition to cryptographic transformations.

In record write operations, message content type is a per packet field which is used in constructing the TLS header. One session is expected to handle all types of content types and so, 'rte_crypto_op.aux_flags' is used for passing the same.

The support is added for TLS 1.2, TLS 1.3 and DTLS 1.2.

Akhil Goyal (1):
net: add headers for TLS/DTLS packets

Anoob Joseph (2):
security: add TLS record processing
cryptodev: add details of datapath handling of TLS records

-----Original Message-----
From: Anoob Joseph <[email protected]>
Sent: Tuesday, October 3, 2023 4:19 PM
To: Thomas Monjalon <[email protected]>; Akhil Goyal <[email protected]>; Jerin Jacob Kollanukkaran <[email protected]>; Harry van Haaren <[email protected]>
Cc: Konstantin Ananyev <[email protected]>; Hemant Agrawal <[email protected]>; [email protected]; Olivier Matz <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: [PATCH v2 0/5] add TLS record processing security offload

Add Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS). The protocols provide communications privacy for L4 protocols such as TCP & UDP.

TLS (and DTLS) protocol is composed of two layers,
1. TLS Record Protocol
2. TLS Handshake Protocol

While TLS Handshake Protocol helps in establishing security parameters by which client and server can communicate, TLS Record Protocol provides the connection security. TLS Record Protocol leverages symmetric cryptographic operations such as data encryption and authentication for providing security to the communications.

Cryptodevs that are capable of offloading TLS Record Protocol may perform other operations like IV generation, header insertion, atomic sequence number updates and anti-replay window check in addition to cryptographic transformations.

In record write operations, message content type is a per packet field which is used in constructing the TLS header. One session is expected to handle all types of content types and so, 'rte_crypto_op.aux_flags' is used for passing the same.

Support for TLS record protocol is added for TLS 1.2, TLS 1.3 and DTLS 1.2.

Changes in v2:
- Replaced CCS with CHANGE_CIPHER_SPEC (Harry)
- Split patches to clarify lifetime tracking and notification of the same in rte_crypto_op (Harry)
- Use 8 bits reserved space in rte_crypto_op to pass content type from application to PMD (in case of record write) and from PMD to application (in case of of record read). TLS 1.3 has content type as part of trailer which would be encrypted and would be removed by PMD.
- Updated documentation (Harry)

Akhil Goyal (1):
net: add headers for TLS/DTLS packets

Anoob Joseph (2):
security: add TLS record processing
security: support extra padding with TLS

Vidya Sagar Velumuri (2):
security: support TLS record lifetime notification
cryptodev: add details of datapath handling of TLS records

 doc/api/doxy-api-index.md              |   2 +
 doc/guides/prog_guide/rte_security.rst |  74 +++++++++++++
 doc/guides/rel_notes/release_23_11.rst |   6 ++
 lib/cryptodev/rte_crypto.h             |  50 ++++++++-
 lib/net/meson.build                    |   2 +
 lib/net/rte_dtls.h                     |  61 +++++++++++
 lib/net/rte_tls.h                      |  48 +++++++++
 lib/security/rte_security.c            |   4 +
 lib/security/rte_security.h            | 144 +++++++++++++++++++++++++
 9 files changed, 388 insertions(+), 3 deletions(-)
 create mode 100644 lib/net/rte_dtls.h
 create mode 100644 lib/net/rte_tls.h

--
2.25.1

-----Original Message-----
From: Akhil Goyal <[email protected]>
Sent: Wednesday, October 4, 2023 11:51 AM
To: Van Haaren, Harry <[email protected]>; Thomas Monjalon <[email protected]>
Cc: Konstantin Ananyev <[email protected]>; Hemant Agrawal <[email protected]>; [email protected]; Jerin Jacob Kollanukkaran <[email protected]>; Anoob Joseph <[email protected]>; Matz, Olivier <[email protected]>; Vidya Sagar Velumuri <[email protected]>
Subject: RE: [PATCH v2 0/5] add TLS record processing security offload

Hi Harry,

Do you have any further comments on this series?

Subject: [PATCH v2 0/5] add TLS record processing security offload

Add Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS). The protocols provide communications privacy for L4 protocols such as TCP & UDP.

TLS (and DTLS) protocol is composed of two layers,
1. TLS Record Protocol
2. TLS Handshake Protocol

While TLS Handshake Protocol helps in establishing security parameters by which client and server can communicate, TLS Record Protocol provides the connection security. TLS Record Protocol leverages symmetric cryptographic operations such as data encryption and authentication for providing security to the communications.

Cryptodevs that are capable of offloading TLS Record Protocol may perform other operations like IV generation, header insertion, atomic sequence number updates and anti-replay window check in addition to cryptographic transformations.

In record write operations, message content type is a per packet field which is used in constructing the TLS header. One session is expected to handle all types of content types and so, 'rte_crypto_op.aux_flags' is used for passing the same.

Support for TLS record protocol is added for TLS 1.2, TLS 1.3 and DTLS 1.2.

Changes in v2:
- Replaced CCS with CHANGE_CIPHER_SPEC (Harry)
- Split patches to clarify lifetime tracking and notification of the same in rte_crypto_op (Harry)
- Use 8 bits reserved space in rte_crypto_op to pass content type from application to PMD (in case of record write) and from PMD to application (in case of of record read). TLS 1.3 has content type as part of trailer which would be encrypted and would be removed by PMD.
- Updated documentation (Harry)

Akhil Goyal (1):
net: add headers for TLS/DTLS packets

Anoob Joseph (2):
security: add TLS record processing
security: support extra padding with TLS

Vidya Sagar Velumuri (2):
security: support TLS record lifetime notification
cryptodev: add details of datapath handling of TLS records

 doc/api/doxy-api-index.md              |   2 +
 doc/guides/prog_guide/rte_security.rst |  74 +++++++++++++
 doc/guides/rel_notes/release_23_11.rst |   6 ++
 lib/cryptodev/rte_crypto.h             |  50 ++++++++-
 lib/net/meson.build                    |   2 +
 lib/net/rte_dtls.h                     |  61 +++++++++++
 lib/net/rte_tls.h                      |  48 +++++++++
 lib/security/rte_security.c            |   4 +
 lib/security/rte_security.h            | 144 +++++++++++++++++++++++++
 9 files changed, 388 insertions(+), 3 deletions(-)
 create mode 100644 lib/net/rte_dtls.h
 create mode 100644 lib/net/rte_tls.h