openkylin
/
platform_kernel-5.15
mirror of https://gitee.com/openkylin/platform_kernel-5.15.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

crypto: aead - improve documentation for scatterlist layout 

Properly document the scatterlist layout for AEAD ciphers.

Reported-by: Gilad Ben-Yossef <gilad@benyossef.com>
Cc: Stephan Mueller <smueller@chronox.de>
Signed-off-by: Eric Biggers <ebiggers@google.com>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
This commit is contained in:
Eric Biggers 2020-03-04 14:44:05 -08:00 committed by Herbert Xu
parent 8ff357a9d1
commit 3cd54a4c3c
1 changed files with 23 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
include/crypto/aead.h
View File

@ -43,27 +43,33 @@
*
* Memory Structure:
*
* To support the needs of the most prominent user of AEAD ciphers, namely
* IPSEC, the AEAD ciphers have a special memory layout the caller must adhere
* to.
* The source scatterlist must contain the concatenation of
* associated data || plaintext or ciphertext.
*
* The scatter list pointing to the input data must contain:
* The destination scatterlist has the same layout, except that the plaintext
* (resp. ciphertext) will grow (resp. shrink) by the authentication tag size
* during encryption (resp. decryption).
*
* * for RFC4106 ciphers, the concatenation of
* associated authentication data || IV || plaintext or ciphertext. Note, the
* same IV (buffer) is also set with the aead_request_set_crypt call. Note,
* the API call of aead_request_set_ad must provide the length of the AAD and
* the IV. The API call of aead_request_set_crypt only points to the size of
* the input plaintext or ciphertext.
* In-place encryption/decryption is enabled by using the same scatterlist
* pointer for both the source and destination.
*
* * for "normal" AEAD ciphers, the concatenation of
* associated authentication data || plaintext or ciphertext.
* Even in the out-of-place case, space must be reserved in the destination for
* the associated data, even though it won't be written to. This makes the
* in-place and out-of-place cases more consistent. It is permissible for the
* "destination" associated data to alias the "source" associated data.
*
* It is important to note that if multiple scatter gather list entries form
* the input data mentioned above, the first entry must not point to a NULL
* buffer. If there is any potential where the AAD buffer can be NULL, the
* calling code must contain a precaution to ensure that this does not result
* in the first scatter gather list entry pointing to a NULL buffer.
* As with the other scatterlist crypto APIs, zero-length scatterlist elements
* are not allowed in the used part of the scatterlist. Thus, if there is no
* associated data, the first element must point to the plaintext/ciphertext.
*
* To meet the needs of IPsec, a special quirk applies to rfc4106, rfc4309,
* rfc4543, and rfc7539esp ciphers. For these ciphers, the final 'ivsize' bytes
* of the associated data buffer must contain a second copy of the IV. This is
* in addition to the copy passed to aead_request_set_crypt(). These two IV
* copies must not differ; different implementations of the same algorithm may
* behave differently in that case. Note that the algorithm might not actually
* treat the IV as associated data; nevertheless the length passed to
* aead_request_set_ad() must include it.
*/
struct crypto_aead;