crypto: aead - improve documentation for scatterlist layout

 *

 * 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 scatter list pointing to the input data must contain:

 *

 * * 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.

 *

 * * for "normal" AEAD ciphers, the concatenation of

 *   associated authentication data || plaintext or ciphertext.

 *

 * 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.

 * The source scatterlist must contain the concatenation of

 * associated data || plaintext or ciphertext.

 *

 * 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).

 *

 * In-place encryption/decryption is enabled by using the same scatterlist

 * pointer for both the source and destination.

 *

 * 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.

 *

 * 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;