summaryrefslogtreecommitdiff
path: root/include/crypto
diff options
context:
space:
mode:
authorStephan Mueller <smueller@chronox.de>2016-10-21 05:59:24 +0300
committerJonathan Corbet <corbet@lwn.net>2016-12-14 02:38:06 +0300
commit3f692d5f97cb834a42bcfb3cc10f5e390a9d7867 (patch)
treea7663ecfa0067ea394140eb86bd5490fc4c81451 /include/crypto
parent71f3f027f8f8532d397ff2da7bdcd99bf0aa3867 (diff)
downloadlinux-3f692d5f97cb834a42bcfb3cc10f5e390a9d7867.tar.xz
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.h36
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,