From: Damian Nowak <damianx.nowak@intel.com>
Date: Wed, 3 Jul 2019 11:15:51 +0000 (+0200)
Subject: cryptodev: document usage of digest-appended operations
X-Git-Url: http://git.droids-corp.org/?a=commitdiff_plain;h=735b77dd85fc752b050f7bbe9d3aa4887a866df8;p=dpdk.git

cryptodev: document usage of digest-appended operations

This patch explains what are the conditions
and how to use digest appended for auth-cipher
operations.

Signed-off-by: Damian Nowak <damianx.nowak@intel.com>
Acked-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>
Acked-by: Fiona Trahe <fiona.trahe@intel.com>
---

diff --git a/lib/librte_cryptodev/rte_crypto_sym.h b/lib/librte_cryptodev/rte_crypto_sym.h
index bfce84a353..b7c55c262e 100644
--- a/lib/librte_cryptodev/rte_crypto_sym.h
+++ b/lib/librte_cryptodev/rte_crypto_sym.h
@@ -666,6 +666,50 @@ struct rte_crypto_sym_op {
 					 * For digest generation, the digest result
 					 * will overwrite any data at this location.
 					 *
+					 * @note
+					 * Digest-encrypted case.
+					 * Digest can be generated, appended to
+					 * the end of raw data and encrypted
+					 * together using chained digest
+					 * generation
+					 * (@ref RTE_CRYPTO_AUTH_OP_GENERATE)
+					 * and encryption
+					 * (@ref RTE_CRYPTO_CIPHER_OP_ENCRYPT)
+					 * xforms. Similarly, authentication
+					 * of the raw data against appended,
+					 * decrypted digest, can be performed
+					 * using decryption
+					 * (@ref RTE_CRYPTO_CIPHER_OP_DECRYPT)
+					 * and digest verification
+					 * (@ref RTE_CRYPTO_AUTH_OP_VERIFY)
+					 * chained xforms.
+					 * To perform those operations, a few
+					 * additional conditions must be met:
+					 * - caller must allocate at least
+					 * digest_length of memory at the end of
+					 * source and (in case of out-of-place
+					 * operations) destination buffer; those
+					 * buffers can be linear or split using
+					 * scatter-gather lists,
+					 * - digest data pointer must point to
+					 * the end of source or (in case of
+					 * out-of-place operations) destination
+					 * data, which is pointer to the
+					 * data buffer + auth.data.offset +
+					 * auth.data.length,
+					 * - cipher.data.offset +
+					 * cipher.data.length must be greater
+					 * than auth.data.offset +
+					 * auth.data.length and is typically
+					 * equal to auth.data.offset +
+					 * auth.data.length + digest_length.
+					 *
+					 * Note, that for security reasons, it
+					 * is PMDs' responsibility to not
+					 * leave an unencrypted digest in any
+					 * buffer after performing auth-cipher
+					 * operations.
+					 *
 					 */
 					rte_iova_t phys_addr;
 					/**< Physical address of digest */