[dpdk-dev] [PATCH v2 1/9] cryptodev: clarify API for AES-CCM

[Pablo de Lara <pablo.de.lara.guarch@intel.com>]

AES-CCM algorithm has some restrictions when
handling nonce (IV) and AAD information.

As the API stated, the nonce needs to be place 1 byte
after the start of the IV field. This field needs
to be 16 bytes long, regardless the length of the nonce,
but it is important to clarify that the first byte
and the padding added after the nonce may be modified
by the PMDs using this algorithm.

Same happens with the AAD. It needs to be placed 18 bytes
after the start of the AAD field. The field also needs
to be multiple of 16 bytes long and all memory reserved
(the first bytes and the padding (may be modified by the PMDs).

Lastly, nonce is not needed to be placed in the first 16 bytes
of the AAD, as the API stated, as that depends on the PMD
used, so the comment has been removed.

Signed-off-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>
---
 lib/librte_cryptodev/rte_crypto_sym.h | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/lib/librte_cryptodev/rte_crypto_sym.h b/lib/librte_cryptodev/rte_crypto_sym.h
index 0ceaa91..5f859ec 100644
--- a/lib/librte_cryptodev/rte_crypto_sym.h
+++ b/lib/librte_cryptodev/rte_crypto_sym.h
@@ -196,7 +196,9 @@ struct rte_crypto_cipher_xform {
 		 * 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.
+		 * have a value less than this. Note that the PMDs may
+		 * modify the memory reserved (the first byte and the
+		 * final padding)
 		 *
 		 * - For AES-XTS, this is the 128bit tweak, i, from
 		 * IEEE Std 1619-2007.
@@ -555,20 +557,19 @@ struct rte_crypto_sym_op {
 				 * Specifically for CCM (@ref RTE_CRYPTO_AEAD_AES_CCM),
 				 * the caller should setup this field as follows:
 				 *
-				 * - the nonce should be written starting at an offset
-				 * of one byte into the array, leaving room for the
-				 * implementation to write in the flags to the first
-				 * byte.
-				 *
-				 * - the additional  authentication data itself should
+				 * - the additional authentication data itself should
 				 * be written starting at an offset of 18 bytes into
-				 * the array, leaving room for the length encoding in
-				 * the first two bytes of the second block.
+				 * the array, leaving room for the first block (16 bytes)
+				 * and the length encoding in the first two bytes of the
+				 * second block.
 				 *
 				 * - the array should be big enough to hold the above
-				 *  fields, plus any padding to round this up to the
-				 *  nearest multiple of the block size (16 bytes).
-				 *  Padding will be added by the implementation.
+				 * fields, plus any padding to round this up to the
+				 * nearest multiple of the block size (16 bytes).
+				 * Padding will be added by the implementation.
+				 *
+				 * - Note that PMDs may modify the memory reserved
+				 * (first 18 bytes and the final padding).
 				 *
 				 * Finally, for GCM (@ref RTE_CRYPTO_AEAD_AES_GCM), the
 				 * caller should setup this field as follows:
-- 
2.9.4