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

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

crypto/algif_aead.c

+2 −12
Original line number Diff line number Diff line
@@ -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) {

include/crypto/aead.h

+12 −24
Original line number Diff line number Diff line
@@ -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,