[v2,01/10] cryptodev: document usage of digest-appended operations
diff mbox series

Message ID 20190607100608.16212-2-damianx.nowak@intel.com
State Superseded, archived
Delegated to: akhil goyal
Headers show
Series
  • cryptodev: support encrypted-digest use-cases
Related show

Checks

Context Check Description
ci/mellanox-Performance-Testing success Performance Testing PASS
ci/intel-Performance-Testing success Performance Testing PASS
ci/Intel-compilation fail Compilation issues
ci/checkpatch success coding style OK

Commit Message

Damian Nowak June 7, 2019, 10:05 a.m. UTC
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>
---
 lib/librte_cryptodev/rte_crypto_sym.h | 43 +++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

Comments

Trahe, Fiona June 13, 2019, 1:56 p.m. UTC | #1
Hi Damian,

> -----Original Message-----
> From: Nowak, DamianX
> Sent: Friday, June 7, 2019 11:06 AM
> To: dev@dpdk.org
> Cc: Trahe, Fiona <fiona.trahe@intel.com>; Kusztal, ArkadiuszX <arkadiuszx.kusztal@intel.com>; Nowak,
> DamianX <damianx.nowak@intel.com>
> Subject: [PATCH v2 01/10] 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>
> ---
>  lib/librte_cryptodev/rte_crypto_sym.h | 43 +++++++++++++++++++++++++++++++++++
>  1 file changed, 43 insertions(+)
> 
> diff --git a/lib/librte_cryptodev/rte_crypto_sym.h b/lib/librte_cryptodev/rte_crypto_sym.h
> index c80e90e..b211bf5 100644
> --- a/lib/librte_cryptodev/rte_crypto_sym.h
> +++ b/lib/librte_cryptodev/rte_crypto_sym.h
> @@ -662,6 +662,49 @@ struct rte_crypto_sym_op {
>  					 * physically contiguous memory at this
>  					 * location.
>  					 *
> +					 * @note
[Fiona] I suggest adding "Digest-encrypted case." at start of this note. 
> +					 * 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 raw
> +					 * data buffer + auth.data.offset +
> +					 * auth.data.length,
[Fiona] The word raw is confusing here - better leave it out.
i.e. in auth-then-encrypt direction and OOP, the dest buffer doesn't hold raw data, it holds encrypted data.
Copying Pablo - this is slightly different to what we suggested in RFC - can you review for the aesni-mb PMD please.

 
> +					 * - 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.
> +					 *
[Fiona] below this is a separate note, which applies to all cases, not just to digest-encrypted case
so better move it back to above the digest-encrypted note
>  					 * For digest generation, the digest result
>  					 * will overwrite any data at this location.
>  					 *
> --
> 2.7.4

Patch
diff mbox series

diff --git a/lib/librte_cryptodev/rte_crypto_sym.h b/lib/librte_cryptodev/rte_crypto_sym.h
index c80e90e..b211bf5 100644
--- a/lib/librte_cryptodev/rte_crypto_sym.h
+++ b/lib/librte_cryptodev/rte_crypto_sym.h
@@ -662,6 +662,49 @@  struct rte_crypto_sym_op {
 					 * physically contiguous memory at this
 					 * location.
 					 *
+					 * @note
+					 * 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 raw
+					 * 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.
+					 *
 					 * For digest generation, the digest result
 					 * will overwrite any data at this location.
 					 *