diff options
author | Stephan Mueller <smueller@chronox.de> | 2016-10-21 04:59:24 +0200 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2016-12-14 00:38:06 +0100 |
commit | 3f692d5f97cb834a42bcfb3cc10f5e390a9d7867 (patch) | |
tree | a7663ecfa0067ea394140eb86bd5490fc4c81451 /include/crypto | |
parent | crypto: doc - remove crypto_alloc_ablkcipher (diff) | |
download | linux-3f692d5f97cb834a42bcfb3cc10f5e390a9d7867.tar.xz linux-3f692d5f97cb834a42bcfb3cc10f5e390a9d7867.zip |
crypto: doc - clarify AEAD memory structure
The previous description have been misleading and partially incorrect.
Reported-by: Harsh Jain <harshjain.prof@gmail.com>
Signed-off-by: Stephan Mueller <smueller@chronox.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'include/crypto')
-rw-r--r-- | include/crypto/aead.h | 36 |
1 files changed, 12 insertions, 24 deletions
diff --git a/include/crypto/aead.h b/include/crypto/aead.h index e725155c6389..03b97629442c 100644 --- a/include/crypto/aead.h +++ b/include/crypto/aead.h @@ -483,30 +483,18 @@ static inline void aead_request_set_callback(struct aead_request *req, * destination is the ciphertext. For a decryption operation, the use is * reversed - the source is the ciphertext and the destination is the plaintext. * - * For both src/dst the layout is associated data, plain/cipher text, - * authentication tag. - * - * The content of the AD in the destination buffer after processing - * will either be untouched, or it will contain a copy of the AD - * from the source buffer. In order to ensure that it always has - * a copy of the AD, the user must copy the AD over either before - * or after processing. Of course this is not relevant if the user - * is doing in-place processing where src == dst. - * - * IMPORTANT NOTE AEAD requires an authentication tag (MAC). For decryption, - * the caller must concatenate the ciphertext followed by the - * authentication tag and provide the entire data stream to the - * decryption operation (i.e. the data length used for the - * initialization of the scatterlist and the data length for the - * decryption operation is identical). For encryption, however, - * the authentication tag is created while encrypting the data. - * The destination buffer must hold sufficient space for the - * ciphertext and the authentication tag while the encryption - * invocation must only point to the plaintext data size. The - * following code snippet illustrates the memory usage - * buffer = kmalloc(ptbuflen + (enc ? authsize : 0)); - * sg_init_one(&sg, buffer, ptbuflen + (enc ? authsize : 0)); - * aead_request_set_crypt(req, &sg, &sg, ptbuflen, iv); + * The memory structure for cipher operation has the following structure: + * + * - AEAD encryption input: assoc data || plaintext + * - AEAD encryption output: assoc data || cipherntext || auth tag + * - AEAD decryption input: assoc data || ciphertext || auth tag + * - AEAD decryption output: assoc data || plaintext + * + * Albeit the kernel requires the presence of the AAD buffer, however, + * the kernel does not fill the AAD buffer in the output case. If the + * caller wants to have that data buffer filled, the caller must either + * use an in-place cipher operation (i.e. same memory location for + * input/output memory location). */ static inline void aead_request_set_crypt(struct aead_request *req, struct scatterlist *src, |