diff options
author | Stephan Mueller <smueller@chronox.de> | 2016-10-20 22:59:24 -0400 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2016-12-13 18:38:06 -0500 |
commit | 3f692d5f97cb834a42bcfb3cc10f5e390a9d7867 (patch) | |
tree | a7663ecfa0067ea394140eb86bd5490fc4c81451 | |
parent | 71f3f027f8f8532d397ff2da7bdcd99bf0aa3867 (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.c | 14 | ||||
-rw-r--r-- | include/crypto/aead.h | 36 |
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 | */ |
511 | static inline void aead_request_set_crypt(struct aead_request *req, | 499 | static inline void aead_request_set_crypt(struct aead_request *req, |
512 | struct scatterlist *src, | 500 | struct scatterlist *src, |