Commit 3f692d5f authored by Stephan Mueller's avatar Stephan Mueller Committed by Jonathan Corbet

crypto: doc - clarify AEAD memory structure

The previous description have been misleading and partially incorrect.
Reported-by: default avatarHarsh Jain <harshjain.prof@gmail.com>
Signed-off-by: default avatarStephan Mueller <smueller@chronox.de>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 71f3f027
......@@ -551,18 +551,8 @@ static int aead_recvmsg_sync(struct socket *sock, struct msghdr *msg, int flags)
lock_sock(sk);
/*
* AEAD memory structure: For encryption, the tag is appended to the
* ciphertext which implies that the memory allocated for the ciphertext
* must be increased by the tag length. For decryption, the tag
* is expected to be concatenated to the ciphertext. The plaintext
* therefore has a memory size of the ciphertext minus the tag length.
*
* The memory structure for cipher operation has the following
* structure:
* AEAD encryption input: assoc data || plaintext
* AEAD encryption output: cipherntext || auth tag
* AEAD decryption input: assoc data || ciphertext || auth tag
* AEAD decryption output: plaintext
* Please see documentation of aead_request_set_crypt for the
* description of the AEAD memory structure expected from the caller.
*/
if (ctx->more) {
......
......@@ -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,
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment