[dpdk-dev] [PATCH v2 20/27] cryptodev: add AEAD specific data

Pablo de Lara pablo.de.lara.guarch at intel.com
Mon Jun 26 12:22:53 CEST 2017


AEAD algorithms such as AES-GCM needed to be
used as a concatenation of a cipher transform and
an authentication transform.

Instead, a new transform and functions to handle it
are created to support these kind of algorithms,
making their use easier.

Signed-off-by: Pablo de Lara <pablo.de.lara.guarch at intel.com>
---
 doc/guides/prog_guide/cryptodev_lib.rst          | 14 +++--
 doc/guides/prog_guide/img/crypto_xform_chain.svg |  8 ++-
 doc/guides/rel_notes/release_17_08.rst           |  6 ++
 lib/librte_cryptodev/rte_crypto_sym.h            | 80 +++++++++++++++++++++++-
 lib/librte_cryptodev/rte_cryptodev.c             | 61 ++++++++++++++++++
 lib/librte_cryptodev/rte_cryptodev.h             | 52 ++++++++++++++-
 lib/librte_cryptodev/rte_cryptodev_version.map   | 10 +++
 7 files changed, 221 insertions(+), 10 deletions(-)

diff --git a/doc/guides/prog_guide/cryptodev_lib.rst b/doc/guides/prog_guide/cryptodev_lib.rst
index e036611..b888554 100644
--- a/doc/guides/prog_guide/cryptodev_lib.rst
+++ b/doc/guides/prog_guide/cryptodev_lib.rst
@@ -188,8 +188,9 @@ the device having hardware acceleration or supporting symmetric Crypto
 operations,
 
 The capabilities mechanism defines the individual algorithms/functions which
-the device supports, such as a specific symmetric Crypto cipher or
-authentication operation.
+the device supports, such as a specific symmetric Crypto cipher,
+authentication operation or Authenticated Encryption with Associated Data
+(AEAD) operation.
 
 
 Device Features
@@ -477,9 +478,8 @@ operations such as cipher encrypt and authentication generate, the next pointer
 allows transform to be chained together. Crypto devices which support chaining
 must publish the chaining of symmetric Crypto operations feature flag.
 
-Currently there are two transforms types cipher and authentication, to specify
-an AEAD operation it is required to chain a cipher and an authentication
-transform together. Also it is important to note that the order in which the
+Currently there are three transforms types cipher, authentication and AEAD.
+Also it is important to note that the order in which the
 transforms are passed indicates the order of the chaining.
 
 .. code-block:: c
@@ -494,6 +494,8 @@ transforms are passed indicates the order of the chaining.
             /**< Authentication / hash xform */
             struct rte_crypto_cipher_xform cipher;
             /**< Cipher xform */
+            struct rte_crypto_aead_xform aead;
+            /**< AEAD xform */
         };
     };
 
@@ -514,7 +516,7 @@ operations.
 
 As a minimum the symmetric operation must have a source data buffer (``m_src``),
 a valid session (or transform chain if in session-less mode) and the minimum
-authentication/ cipher parameters required depending on the type of operation
+authentication/ cipher/ AEAD parameters required depending on the type of operation
 specified in the session or the transform
 chain.
 
diff --git a/doc/guides/prog_guide/img/crypto_xform_chain.svg b/doc/guides/prog_guide/img/crypto_xform_chain.svg
index 4670a07..1368163 100644
--- a/doc/guides/prog_guide/img/crypto_xform_chain.svg
+++ b/doc/guides/prog_guide/img/crypto_xform_chain.svg
@@ -69,7 +69,9 @@
 						class="st3">auth</tspan><tspan class="st3">_</tspan><tspan class="st3">xform  </tspan><tspan x="16.02"
 						dy="1.425em" class="st4">struct </tspan><tspan class="st3">rte</tspan><tspan class="st3">_</tspan><tspan
 						class="st3">crypto</tspan><tspan class="st3">_</tspan><tspan class="st3">cipher</tspan><tspan class="st3">_</tspan><tspan
-						class="st3">xform</tspan></text>		</g>
+						class="st3">xform</tspan><tspan x="18.76" dy="1.425em" class="st4">struct </tspan><tspan
+                                                class="st3">rte</tspan><tspan class="st3">_</tspan><tspan class="st3">crypto</tspan><tspan class="st3">_</tspan><tspan
+                                                class="st3">aead</tspan><tspan class="st3">_</tspan><tspan class="st3">xform</tspan></text>		</g>
 		<g id="shape11-38" transform="translate(10.6711,-238.133)">
 			<title>Rounded Rectangle.26</title>
 			<desc>next transform (struct rte_crypto_sym_xform *)</desc>
@@ -116,7 +118,9 @@
 						class="st3">auth</tspan><tspan class="st3">_</tspan><tspan class="st3">xform  </tspan><tspan x="16.02"
 						dy="1.425em" class="st4">struct </tspan><tspan class="st3">rte</tspan><tspan class="st3">_</tspan><tspan
 						class="st3">crypto</tspan><tspan class="st3">_</tspan><tspan class="st3">cipher</tspan><tspan class="st3">_</tspan><tspan
-						class="st3">xform</tspan></text>		</g>
+						class="st3">xform</tspan><tspan x="18.76" dy="1.425em" class="st4">struct </tspan><tspan
+                                                class="st3">rte</tspan><tspan class="st3">_</tspan><tspan class="st3">crypto</tspan><tspan class="st3">_</tspan><tspan
+                                                class="st3">aead</tspan><tspan class="st3">_</tspan><tspan class="st3">xform</tspan></text>		</g>
 		<g id="shape15-102" transform="translate(209.592,-163.865)">
 			<title>Rounded Rectangle.32</title>
 			<desc>next transform (struct rte_crypto_sym_xform *)</desc>
diff --git a/doc/guides/rel_notes/release_17_08.rst b/doc/guides/rel_notes/release_17_08.rst
index a544639..b920142 100644
--- a/doc/guides/rel_notes/release_17_08.rst
+++ b/doc/guides/rel_notes/release_17_08.rst
@@ -75,6 +75,12 @@ New Features
 
   Added support for firmwares with multiple Ethernet ports per physical port.
 
+* **Updated cryptodev library.**
+
+  Added AEAD algorithm specific functions and structures, so it is not
+  necessary to use a combination of cipher and authentication
+  structures anymore.
+
 
 Resolved Issues
 ---------------
diff --git a/lib/librte_cryptodev/rte_crypto_sym.h b/lib/librte_cryptodev/rte_crypto_sym.h
index f174e12..db3957e 100644
--- a/lib/librte_cryptodev/rte_crypto_sym.h
+++ b/lib/librte_cryptodev/rte_crypto_sym.h
@@ -404,11 +404,87 @@ struct rte_crypto_auth_xform {
 	} iv;	/**< Initialisation vector parameters */
 };
 
+
+/** Symmetric AEAD Algorithms */
+enum rte_crypto_aead_algorithm {
+	RTE_CRYPTO_AEAD_AES_CCM = 1,
+	/**< AES algorithm in CCM mode. */
+	RTE_CRYPTO_AEAD_AES_GCM,
+	/**< AES algorithm in GCM mode. */
+	RTE_CRYPTO_AEAD_LIST_END
+};
+
+/** AEAD algorithm name strings */
+extern const char *
+rte_crypto_aead_algorithm_strings[];
+
+/** Symmetric AEAD Operations */
+enum rte_crypto_aead_operation {
+	RTE_CRYPTO_AEAD_OP_ENCRYPT,
+	/**< Encrypt and generate digest */
+	RTE_CRYPTO_AEAD_OP_DECRYPT
+	/**< Verify digest and decrypt */
+};
+
+/** Authentication operation name strings */
+extern const char *
+rte_crypto_aead_operation_strings[];
+
+struct rte_crypto_aead_xform {
+	enum rte_crypto_aead_operation op;
+	/**< AEAD operation type */
+	enum rte_crypto_aead_algorithm algo;
+	/**< AEAD algorithm selection */
+
+	struct {
+		uint8_t *data;  /**< pointer to key data */
+		size_t length;   /**< key length in bytes */
+	} key;
+
+	struct {
+		uint16_t offset;
+		/**< Starting point for Initialisation Vector or Counter,
+		 * specified as number of bytes from start of crypto
+		 * operation (rte_crypto_op).
+		 *
+		 * - For GCM mode, this is either the IV (if the length
+		 * is 96 bits) or J0 (for other sizes), where J0 is as
+		 * defined by NIST SP800-38D. Regardless of the IV
+		 * length, a full 16 bytes needs to be allocated.
+		 *
+		 * - For CCM mode, the first byte is reserved, and the
+		 * nonce should be written starting at &iv[1] (to allow
+		 * space for the implementation to write in the flags
+		 * in the first byte). Note that a full 16 bytes should
+		 * be allocated, even though the length field will
+		 * have a value less than this.
+		 *
+		 * For optimum performance, the data pointed to SHOULD
+		 * be 8-byte aligned.
+		 */
+		uint16_t length;
+		/**< Length of valid IV data.
+		 *
+		 * - For GCM mode, this is either 12 (for 96-bit IVs)
+		 * or 16, in which case data points to J0.
+		 *
+		 * - For CCM mode, this is the length of the nonce,
+		 * which can be in the range 7 to 13 inclusive.
+		 */
+	} iv;	/**< Initialisation vector parameters */
+
+	uint32_t digest_length;
+
+	uint16_t add_auth_data_length;
+	/**< The length of the additional authenticated data (AAD) in bytes. */
+};
+
 /** Crypto transformation types */
 enum rte_crypto_sym_xform_type {
 	RTE_CRYPTO_SYM_XFORM_NOT_SPECIFIED = 0,	/**< No xform specified */
 	RTE_CRYPTO_SYM_XFORM_AUTH,		/**< Authentication xform */
-	RTE_CRYPTO_SYM_XFORM_CIPHER		/**< Cipher xform  */
+	RTE_CRYPTO_SYM_XFORM_CIPHER,		/**< Cipher xform  */
+	RTE_CRYPTO_SYM_XFORM_AEAD		/**< AEAD xform  */
 };
 
 /**
@@ -431,6 +507,8 @@ struct rte_crypto_sym_xform {
 		/**< Authentication / hash xform */
 		struct rte_crypto_cipher_xform cipher;
 		/**< Cipher xform */
+		struct rte_crypto_aead_xform aead;
+		/**< AEAD xform */
 	};
 };
 
diff --git a/lib/librte_cryptodev/rte_cryptodev.c b/lib/librte_cryptodev/rte_cryptodev.c
index 5aa177f..60dc5e5 100644
--- a/lib/librte_cryptodev/rte_cryptodev.c
+++ b/lib/librte_cryptodev/rte_cryptodev.c
@@ -176,6 +176,26 @@ rte_crypto_auth_algorithm_strings[] = {
 	[RTE_CRYPTO_AUTH_ZUC_EIA3]	= "zuc-eia3"
 };
 
+/**
+ * The crypto AEAD algorithm strings identifiers.
+ * It could be used in application command line.
+ */
+const char *
+rte_crypto_aead_algorithm_strings[] = {
+	[RTE_CRYPTO_AEAD_AES_CCM]	= "aes-ccm",
+	[RTE_CRYPTO_AEAD_AES_GCM]	= "aes-gcm",
+};
+
+/**
+ * The crypto AEAD operation strings identifiers.
+ * It could be used in application command line.
+ */
+const char *
+rte_crypto_aead_operation_strings[] = {
+	[RTE_CRYPTO_AEAD_OP_ENCRYPT]	= "encrypt",
+	[RTE_CRYPTO_AEAD_OP_DECRYPT]	= "decrypt"
+};
+
 int
 rte_cryptodev_get_cipher_algo_enum(enum rte_crypto_cipher_algorithm *algo_enum,
 		const char *algo_string)
@@ -210,6 +230,23 @@ rte_cryptodev_get_auth_algo_enum(enum rte_crypto_auth_algorithm *algo_enum,
 	return -1;
 }
 
+int
+rte_cryptodev_get_aead_algo_enum(enum rte_crypto_aead_algorithm *algo_enum,
+		const char *algo_string)
+{
+	unsigned int i;
+
+	for (i = 1; i < RTE_DIM(rte_crypto_aead_algorithm_strings); i++) {
+		if (strcmp(algo_string, rte_crypto_aead_algorithm_strings[i]) == 0) {
+			*algo_enum = (enum rte_crypto_aead_algorithm) i;
+			return 0;
+		}
+	}
+
+	/* Invalid string */
+	return -1;
+}
+
 /**
  * The crypto auth operation strings identifiers.
  * It could be used in application command line.
@@ -245,6 +282,10 @@ rte_cryptodev_sym_capability_get(uint8_t dev_id,
 		if (idx->type == RTE_CRYPTO_SYM_XFORM_CIPHER &&
 			capability->sym.cipher.algo == idx->algo.cipher)
 			return &capability->sym;
+
+		if (idx->type == RTE_CRYPTO_SYM_XFORM_AEAD &&
+				capability->sym.aead.algo == idx->algo.aead)
+			return &capability->sym;
 	}
 
 	return NULL;
@@ -290,6 +331,26 @@ rte_cryptodev_sym_capability_check_auth(
 	return 0;
 }
 
+int
+rte_cryptodev_sym_capability_check_aead(
+		const struct rte_cryptodev_symmetric_capability *capability,
+		uint16_t key_size, uint16_t digest_size, uint16_t aad_size,
+		uint16_t iv_size)
+{
+	if (param_range_check(key_size, capability->aead.key_size))
+		return -1;
+
+	if (param_range_check(digest_size, capability->aead.digest_size))
+		return -1;
+
+	if (param_range_check(aad_size, capability->aead.aad_size))
+		return -1;
+
+	if (param_range_check(iv_size, capability->aead.iv_size))
+		return -1;
+
+	return 0;
+}
 
 const char *
 rte_cryptodev_get_feature_name(uint64_t flag)
diff --git a/lib/librte_cryptodev/rte_cryptodev.h b/lib/librte_cryptodev/rte_cryptodev.h
index 75b423a..c47a3f6 100644
--- a/lib/librte_cryptodev/rte_cryptodev.h
+++ b/lib/librte_cryptodev/rte_cryptodev.h
@@ -170,7 +170,7 @@ struct rte_crypto_param_range {
  */
 struct rte_cryptodev_symmetric_capability {
 	enum rte_crypto_sym_xform_type xform_type;
-	/**< Transform type : Authentication / Cipher */
+	/**< Transform type : Authentication / Cipher / AEAD */
 	RTE_STD_C11
 	union {
 		struct {
@@ -199,6 +199,20 @@ struct rte_cryptodev_symmetric_capability {
 			/**< Initialisation vector data size range */
 		} cipher;
 		/**< Symmetric Cipher transform capabilities */
+		struct {
+			enum rte_crypto_aead_algorithm algo;
+			/**< AEAD algorithm */
+			uint16_t block_size;
+			/**< algorithm block size */
+			struct rte_crypto_param_range key_size;
+			/**< AEAD key size range */
+			struct rte_crypto_param_range digest_size;
+			/**< digest size range */
+			struct rte_crypto_param_range aad_size;
+			/**< Additional authentication data size range */
+			struct rte_crypto_param_range iv_size;
+			/**< Initialisation vector data size range */
+		} aead;
 	};
 };
 
@@ -220,6 +234,7 @@ struct rte_cryptodev_sym_capability_idx {
 	union {
 		enum rte_crypto_cipher_algorithm cipher;
 		enum rte_crypto_auth_algorithm auth;
+		enum rte_crypto_aead_algorithm aead;
 	} algo;
 };
 
@@ -275,6 +290,26 @@ rte_cryptodev_sym_capability_check_auth(
 		uint16_t iv_size);
 
 /**
+ * Check if key, digest, AAD and initial vector sizes are supported
+ * in crypto AEAD capability
+ *
+ * @param	capability	Description of the symmetric crypto capability.
+ * @param	key_size	AEAD key size.
+ * @param	digest_size	AEAD digest size.
+ * @param	aad_size	AEAD AAD size.
+ * @param	iv_size		AEAD IV size.
+ *
+ * @return
+ *   - Return 0 if the parameters are in range of the capability.
+ *   - Return -1 if the parameters are out of range of the capability.
+ */
+int
+rte_cryptodev_sym_capability_check_aead(
+		const struct rte_cryptodev_symmetric_capability *capability,
+		uint16_t key_size, uint16_t digest_size, uint16_t aad_size,
+		uint16_t iv_size);
+
+/**
  * Provide the cipher algorithm enum, given an algorithm string
  *
  * @param	algo_enum	A pointer to the cipher algorithm
@@ -304,6 +339,21 @@ int
 rte_cryptodev_get_auth_algo_enum(enum rte_crypto_auth_algorithm *algo_enum,
 		const char *algo_string);
 
+/**
+ * Provide the AEAD algorithm enum, given an algorithm string
+ *
+ * @param	algo_enum	A pointer to the AEAD algorithm
+ *				enum to be filled
+ * @param	algo_string	AEAD algorithm string
+ *
+ * @return
+ * - Return -1 if string is not valid
+ * - Return 0 is the string is valid
+ */
+int
+rte_cryptodev_get_aead_algo_enum(enum rte_crypto_aead_algorithm *algo_enum,
+		const char *algo_string);
+
 /** Macro used at end of crypto PMD list */
 #define RTE_CRYPTODEV_END_OF_CAPABILITIES_LIST() \
 	{ RTE_CRYPTO_OP_TYPE_UNDEFINED }
diff --git a/lib/librte_cryptodev/rte_cryptodev_version.map b/lib/librte_cryptodev/rte_cryptodev_version.map
index b6c8ab8..fe79a4a 100644
--- a/lib/librte_cryptodev/rte_cryptodev_version.map
+++ b/lib/librte_cryptodev/rte_cryptodev_version.map
@@ -58,3 +58,13 @@ DPDK_17.05 {
 	rte_cryptodev_queue_pair_detach_sym_session;
 
 } DPDK_17.02;
+
+DPDK_17.08 {
+	global:
+
+	rte_cryptodev_get_aead_algo_enum;
+	rte_cryptodev_sym_capability_check_aead;
+	rte_crypto_aead_algorithm_strings;
+	rte_crypto_aead_operation_strings;
+
+} DPDK_17.05;
-- 
2.9.4



More information about the dev mailing list