Hi Damian,
> -----Original Message-----
> From: Nowak, DamianX
> Sent: Friday, June 7, 2019 11:06 AM
> To: dev@dpdk.org
> Cc: Trahe, Fiona <fiona.tr...@intel.com>; Kusztal, ArkadiuszX
> <arkadiuszx.kusz...@intel.com>; Nowak,
> DamianX <damianx.no...@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.no...@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
