aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorStephan Mueller <smueller@chronox.de>2016-10-20 22:59:24 -0400
committerJonathan Corbet <corbet@lwn.net>2016-12-13 18:38:06 -0500
commit3f692d5f97cb834a42bcfb3cc10f5e390a9d7867 (patch)
treea7663ecfa0067ea394140eb86bd5490fc4c81451
parent71f3f027f8f8532d397ff2da7bdcd99bf0aa3867 (diff)
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>
-rw-r--r--crypto/algif_aead.c14
-rw-r--r--include/crypto/aead.h36
2 files changed, 14 insertions, 36 deletions
diff --git a/crypto/algif_aead.c b/crypto/algif_aead.c
index 80a0f1a78551..a0d8377729a4 100644
--- a/crypto/algif_aead.c
+++ b/crypto/algif_aead.c
@@ -551,18 +551,8 @@ static int aead_recvmsg_sync(struct socket *sock, struct msghdr *msg, int flags)
551 lock_sock(sk); 551 lock_sock(sk);
552 552
553 /* 553 /*
554 * AEAD memory structure: For encryption, the tag is appended to the 554 * Please see documentation of aead_request_set_crypt for the
555 * ciphertext which implies that the memory allocated for the ciphertext 555 * description of the AEAD memory structure expected from the caller.
556 * must be increased by the tag length. For decryption, the tag
557 * is expected to be concatenated to the ciphertext. The plaintext
558 * therefore has a memory size of the ciphertext minus the tag length.
559 *
560 * The memory structure for cipher operation has the following
561 * structure:
562 * AEAD encryption input: assoc data || plaintext
563 * AEAD encryption output: cipherntext || auth tag
564 * AEAD decryption input: assoc data || ciphertext || auth tag
565 * AEAD decryption output: plaintext
566 */ 556 */
567 557
568 if (ctx->more) { 558 if (ctx->more) {
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,
483 * destination is the ciphertext. For a decryption operation, the use is 483 * destination is the ciphertext. For a decryption operation, the use is
484 * reversed - the source is the ciphertext and the destination is the plaintext. 484 * reversed - the source is the ciphertext and the destination is the plaintext.
485 * 485 *
486 * For both src/dst the layout is associated data, plain/cipher text, 486 * The memory structure for cipher operation has the following structure:
487 * authentication tag. 487 *
488 * 488 * - AEAD encryption input: assoc data || plaintext
489 * The content of the AD in the destination buffer after processing 489 * - AEAD encryption output: assoc data || cipherntext || auth tag
490 * will either be untouched, or it will contain a copy of the AD 490 * - AEAD decryption input: assoc data || ciphertext || auth tag
491 * from the source buffer. In order to ensure that it always has 491 * - AEAD decryption output: assoc data || plaintext
492 * a copy of the AD, the user must copy the AD over either before 492 *
493 * or after processing. Of course this is not relevant if the user 493 * Albeit the kernel requires the presence of the AAD buffer, however,
494 * is doing in-place processing where src == dst. 494 * the kernel does not fill the AAD buffer in the output case. If the
495 * 495 * caller wants to have that data buffer filled, the caller must either
496 * IMPORTANT NOTE AEAD requires an authentication tag (MAC). For decryption, 496 * use an in-place cipher operation (i.e. same memory location for
497 * the caller must concatenate the ciphertext followed by the 497 * input/output memory location).
498 * authentication tag and provide the entire data stream to the
499 * decryption operation (i.e. the data length used for the
500 * initialization of the scatterlist and the data length for the
501 * decryption operation is identical). For encryption, however,
502 * the authentication tag is created while encrypting the data.
503 * The destination buffer must hold sufficient space for the
504 * ciphertext and the authentication tag while the encryption
505 * invocation must only point to the plaintext data size. The
506 * following code snippet illustrates the memory usage
507 * buffer = kmalloc(ptbuflen + (enc ? authsize : 0));
508 * sg_init_one(&sg, buffer, ptbuflen + (enc ? authsize : 0));
509 * aead_request_set_crypt(req, &sg, &sg, ptbuflen, iv);
510 */ 498 */
511static inline void aead_request_set_crypt(struct aead_request *req, 499static inline void aead_request_set_crypt(struct aead_request *req,
512 struct scatterlist *src, 500 struct scatterlist *src,