1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3 * AEAD: Authenticated Encryption with Associated Data
5 * Copyright (c) 2007-2015 Herbert Xu <herbert@gondor.apana.org.au>
11 #include <linux/crypto.h>
12 #include <linux/kernel.h>
13 #include <linux/slab.h>
16 * DOC: Authenticated Encryption With Associated Data (AEAD) Cipher API
18 * The AEAD cipher API is used with the ciphers of type CRYPTO_ALG_TYPE_AEAD
19 * (listed as type "aead" in /proc/crypto)
21 * The most prominent examples for this type of encryption is GCM and CCM.
22 * However, the kernel supports other types of AEAD ciphers which are defined
23 * with the following cipher string:
25 * authenc(keyed message digest, block cipher)
27 * For example: authenc(hmac(sha256), cbc(aes))
29 * The example code provided for the symmetric key cipher operation
30 * applies here as well. Naturally all *skcipher* symbols must be exchanged
31 * the *aead* pendants discussed in the following. In addition, for the AEAD
32 * operation, the aead_request_set_ad function must be used to set the
33 * pointer to the associated data memory location before performing the
34 * encryption or decryption operation. In case of an encryption, the associated
35 * data memory is filled during the encryption operation. For decryption, the
36 * associated data memory must contain data that is used to verify the integrity
37 * of the decrypted data. Another deviation from the asynchronous block cipher
38 * operation is that the caller should explicitly check for -EBADMSG of the
39 * crypto_aead_decrypt. That error indicates an authentication error, i.e.
40 * a breach in the integrity of the message. In essence, that -EBADMSG error
41 * code is the key bonus an AEAD cipher has over "standard" block chaining
46 * To support the needs of the most prominent user of AEAD ciphers, namely
47 * IPSEC, the AEAD ciphers have a special memory layout the caller must adhere
50 * The scatter list pointing to the input data must contain:
52 * * for RFC4106 ciphers, the concatenation of
53 * associated authentication data || IV || plaintext or ciphertext. Note, the
54 * same IV (buffer) is also set with the aead_request_set_crypt call. Note,
55 * the API call of aead_request_set_ad must provide the length of the AAD and
56 * the IV. The API call of aead_request_set_crypt only points to the size of
57 * the input plaintext or ciphertext.
59 * * for "normal" AEAD ciphers, the concatenation of
60 * associated authentication data || plaintext or ciphertext.
62 * It is important to note that if multiple scatter gather list entries form
63 * the input data mentioned above, the first entry must not point to a NULL
64 * buffer. If there is any potential where the AAD buffer can be NULL, the
65 * calling code must contain a precaution to ensure that this does not result
66 * in the first scatter gather list entry pointing to a NULL buffer.
72 * struct aead_request - AEAD request
73 * @base: Common attributes for async crypto requests
74 * @assoclen: Length in bytes of associated data for authentication
75 * @cryptlen: Length of data to be encrypted or decrypted
76 * @iv: Initialisation vector
78 * @dst: Destination data
79 * @__ctx: Start of private context data
82 struct crypto_async_request base
;
84 unsigned int assoclen
;
85 unsigned int cryptlen
;
89 struct scatterlist
*src
;
90 struct scatterlist
*dst
;
92 void *__ctx
[] CRYPTO_MINALIGN_ATTR
;
96 * struct aead_alg - AEAD cipher definition
97 * @maxauthsize: Set the maximum authentication tag size supported by the
98 * transformation. A transformation may support smaller tag sizes.
99 * As the authentication tag is a message digest to ensure the
100 * integrity of the encrypted data, a consumer typically wants the
101 * largest authentication tag possible as defined by this
103 * @setauthsize: Set authentication size for the AEAD transformation. This
104 * function is used to specify the consumer requested size of the
105 * authentication tag to be either generated by the transformation
106 * during encryption or the size of the authentication tag to be
107 * supplied during the decryption operation. This function is also
108 * responsible for checking the authentication tag size for
110 * @setkey: see struct skcipher_alg
111 * @encrypt: see struct skcipher_alg
112 * @decrypt: see struct skcipher_alg
113 * @ivsize: see struct skcipher_alg
114 * @chunksize: see struct skcipher_alg
115 * @init: Initialize the cryptographic transformation object. This function
116 * is used to initialize the cryptographic transformation object.
117 * This function is called only once at the instantiation time, right
118 * after the transformation context was allocated. In case the
119 * cryptographic hardware has some special requirements which need to
120 * be handled by software, this function shall check for the precise
121 * requirement of the transformation and put any software fallbacks
123 * @exit: Deinitialize the cryptographic transformation object. This is a
124 * counterpart to @init, used to remove various changes set in
126 * @base: Definition of a generic crypto cipher algorithm.
128 * All fields except @ivsize is mandatory and must be filled.
131 int (*setkey
)(struct crypto_aead
*tfm
, const u8
*key
,
132 unsigned int keylen
);
133 int (*setauthsize
)(struct crypto_aead
*tfm
, unsigned int authsize
);
134 int (*encrypt
)(struct aead_request
*req
);
135 int (*decrypt
)(struct aead_request
*req
);
136 int (*init
)(struct crypto_aead
*tfm
);
137 void (*exit
)(struct crypto_aead
*tfm
);
140 unsigned int maxauthsize
;
141 unsigned int chunksize
;
143 struct crypto_alg base
;
147 unsigned int authsize
;
148 unsigned int reqsize
;
150 struct crypto_tfm base
;
153 static inline struct crypto_aead
*__crypto_aead_cast(struct crypto_tfm
*tfm
)
155 return container_of(tfm
, struct crypto_aead
, base
);
159 * crypto_alloc_aead() - allocate AEAD cipher handle
160 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
162 * @type: specifies the type of the cipher
163 * @mask: specifies the mask for the cipher
165 * Allocate a cipher handle for an AEAD. The returned struct
166 * crypto_aead is the cipher handle that is required for any subsequent
167 * API invocation for that AEAD.
169 * Return: allocated cipher handle in case of success; IS_ERR() is true in case
170 * of an error, PTR_ERR() returns the error code.
172 struct crypto_aead
*crypto_alloc_aead(const char *alg_name
, u32 type
, u32 mask
);
174 static inline struct crypto_tfm
*crypto_aead_tfm(struct crypto_aead
*tfm
)
180 * crypto_free_aead() - zeroize and free aead handle
181 * @tfm: cipher handle to be freed
183 static inline void crypto_free_aead(struct crypto_aead
*tfm
)
185 crypto_destroy_tfm(tfm
, crypto_aead_tfm(tfm
));
188 static inline struct aead_alg
*crypto_aead_alg(struct crypto_aead
*tfm
)
190 return container_of(crypto_aead_tfm(tfm
)->__crt_alg
,
191 struct aead_alg
, base
);
194 static inline unsigned int crypto_aead_alg_ivsize(struct aead_alg
*alg
)
200 * crypto_aead_ivsize() - obtain IV size
201 * @tfm: cipher handle
203 * The size of the IV for the aead referenced by the cipher handle is
204 * returned. This IV size may be zero if the cipher does not need an IV.
206 * Return: IV size in bytes
208 static inline unsigned int crypto_aead_ivsize(struct crypto_aead
*tfm
)
210 return crypto_aead_alg_ivsize(crypto_aead_alg(tfm
));
214 * crypto_aead_authsize() - obtain maximum authentication data size
215 * @tfm: cipher handle
217 * The maximum size of the authentication data for the AEAD cipher referenced
218 * by the AEAD cipher handle is returned. The authentication data size may be
219 * zero if the cipher implements a hard-coded maximum.
221 * The authentication data may also be known as "tag value".
223 * Return: authentication data size / tag size in bytes
225 static inline unsigned int crypto_aead_authsize(struct crypto_aead
*tfm
)
227 return tfm
->authsize
;
231 * crypto_aead_blocksize() - obtain block size of cipher
232 * @tfm: cipher handle
234 * The block size for the AEAD referenced with the cipher handle is returned.
235 * The caller may use that information to allocate appropriate memory for the
236 * data returned by the encryption or decryption operation
238 * Return: block size of cipher
240 static inline unsigned int crypto_aead_blocksize(struct crypto_aead
*tfm
)
242 return crypto_tfm_alg_blocksize(crypto_aead_tfm(tfm
));
245 static inline unsigned int crypto_aead_alignmask(struct crypto_aead
*tfm
)
247 return crypto_tfm_alg_alignmask(crypto_aead_tfm(tfm
));
250 static inline u32
crypto_aead_get_flags(struct crypto_aead
*tfm
)
252 return crypto_tfm_get_flags(crypto_aead_tfm(tfm
));
255 static inline void crypto_aead_set_flags(struct crypto_aead
*tfm
, u32 flags
)
257 crypto_tfm_set_flags(crypto_aead_tfm(tfm
), flags
);
260 static inline void crypto_aead_clear_flags(struct crypto_aead
*tfm
, u32 flags
)
262 crypto_tfm_clear_flags(crypto_aead_tfm(tfm
), flags
);
266 * crypto_aead_setkey() - set key for cipher
267 * @tfm: cipher handle
268 * @key: buffer holding the key
269 * @keylen: length of the key in bytes
271 * The caller provided key is set for the AEAD referenced by the cipher
274 * Note, the key length determines the cipher type. Many block ciphers implement
275 * different cipher modes depending on the key size, such as AES-128 vs AES-192
276 * vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128
279 * Return: 0 if the setting of the key was successful; < 0 if an error occurred
281 int crypto_aead_setkey(struct crypto_aead
*tfm
,
282 const u8
*key
, unsigned int keylen
);
285 * crypto_aead_setauthsize() - set authentication data size
286 * @tfm: cipher handle
287 * @authsize: size of the authentication data / tag in bytes
289 * Set the authentication data size / tag size. AEAD requires an authentication
290 * tag (or MAC) in addition to the associated data.
292 * Return: 0 if the setting of the key was successful; < 0 if an error occurred
294 int crypto_aead_setauthsize(struct crypto_aead
*tfm
, unsigned int authsize
);
296 static inline struct crypto_aead
*crypto_aead_reqtfm(struct aead_request
*req
)
298 return __crypto_aead_cast(req
->base
.tfm
);
302 * crypto_aead_encrypt() - encrypt plaintext
303 * @req: reference to the aead_request handle that holds all information
304 * needed to perform the cipher operation
306 * Encrypt plaintext data using the aead_request handle. That data structure
307 * and how it is filled with data is discussed with the aead_request_*
310 * IMPORTANT NOTE The encryption operation creates the authentication data /
311 * tag. That data is concatenated with the created ciphertext.
312 * The ciphertext memory size is therefore the given number of
313 * block cipher blocks + the size defined by the
314 * crypto_aead_setauthsize invocation. The caller must ensure
315 * that sufficient memory is available for the ciphertext and
316 * the authentication tag.
318 * Return: 0 if the cipher operation was successful; < 0 if an error occurred
320 static inline int crypto_aead_encrypt(struct aead_request
*req
)
322 struct crypto_aead
*aead
= crypto_aead_reqtfm(req
);
323 struct crypto_alg
*alg
= aead
->base
.__crt_alg
;
324 unsigned int cryptlen
= req
->cryptlen
;
327 crypto_stats_get(alg
);
328 if (crypto_aead_get_flags(aead
) & CRYPTO_TFM_NEED_KEY
)
331 ret
= crypto_aead_alg(aead
)->encrypt(req
);
332 crypto_stats_aead_encrypt(cryptlen
, alg
, ret
);
337 * crypto_aead_decrypt() - decrypt ciphertext
338 * @req: reference to the ablkcipher_request handle that holds all information
339 * needed to perform the cipher operation
341 * Decrypt ciphertext data using the aead_request handle. That data structure
342 * and how it is filled with data is discussed with the aead_request_*
345 * IMPORTANT NOTE The caller must concatenate the ciphertext followed by the
346 * authentication data / tag. That authentication data / tag
347 * must have the size defined by the crypto_aead_setauthsize
351 * Return: 0 if the cipher operation was successful; -EBADMSG: The AEAD
352 * cipher operation performs the authentication of the data during the
353 * decryption operation. Therefore, the function returns this error if
354 * the authentication of the ciphertext was unsuccessful (i.e. the
355 * integrity of the ciphertext or the associated data was violated);
356 * < 0 if an error occurred.
358 static inline int crypto_aead_decrypt(struct aead_request
*req
)
360 struct crypto_aead
*aead
= crypto_aead_reqtfm(req
);
361 struct crypto_alg
*alg
= aead
->base
.__crt_alg
;
362 unsigned int cryptlen
= req
->cryptlen
;
365 crypto_stats_get(alg
);
366 if (crypto_aead_get_flags(aead
) & CRYPTO_TFM_NEED_KEY
)
368 else if (req
->cryptlen
< crypto_aead_authsize(aead
))
371 ret
= crypto_aead_alg(aead
)->decrypt(req
);
372 crypto_stats_aead_decrypt(cryptlen
, alg
, ret
);
377 * DOC: Asynchronous AEAD Request Handle
379 * The aead_request data structure contains all pointers to data required for
380 * the AEAD cipher operation. This includes the cipher handle (which can be
381 * used by multiple aead_request instances), pointer to plaintext and
382 * ciphertext, asynchronous callback function, etc. It acts as a handle to the
383 * aead_request_* API calls in a similar way as AEAD handle to the
384 * crypto_aead_* API calls.
388 * crypto_aead_reqsize() - obtain size of the request data structure
389 * @tfm: cipher handle
391 * Return: number of bytes
393 static inline unsigned int crypto_aead_reqsize(struct crypto_aead
*tfm
)
399 * aead_request_set_tfm() - update cipher handle reference in request
400 * @req: request handle to be modified
401 * @tfm: cipher handle that shall be added to the request handle
403 * Allow the caller to replace the existing aead handle in the request
404 * data structure with a different one.
406 static inline void aead_request_set_tfm(struct aead_request
*req
,
407 struct crypto_aead
*tfm
)
409 req
->base
.tfm
= crypto_aead_tfm(tfm
);
413 * aead_request_alloc() - allocate request data structure
414 * @tfm: cipher handle to be registered with the request
415 * @gfp: memory allocation flag that is handed to kmalloc by the API call.
417 * Allocate the request data structure that must be used with the AEAD
418 * encrypt and decrypt API calls. During the allocation, the provided aead
419 * handle is registered in the request data structure.
421 * Return: allocated request handle in case of success, or NULL if out of memory
423 static inline struct aead_request
*aead_request_alloc(struct crypto_aead
*tfm
,
426 struct aead_request
*req
;
428 req
= kmalloc(sizeof(*req
) + crypto_aead_reqsize(tfm
), gfp
);
431 aead_request_set_tfm(req
, tfm
);
437 * aead_request_free() - zeroize and free request data structure
438 * @req: request data structure cipher handle to be freed
440 static inline void aead_request_free(struct aead_request
*req
)
446 * aead_request_set_callback() - set asynchronous callback function
447 * @req: request handle
448 * @flags: specify zero or an ORing of the flags
449 * CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
450 * increase the wait queue beyond the initial maximum size;
451 * CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
452 * @compl: callback function pointer to be registered with the request handle
453 * @data: The data pointer refers to memory that is not used by the kernel
454 * crypto API, but provided to the callback function for it to use. Here,
455 * the caller can provide a reference to memory the callback function can
456 * operate on. As the callback function is invoked asynchronously to the
457 * related functionality, it may need to access data structures of the
458 * related functionality which can be referenced using this pointer. The
459 * callback function can access the memory via the "data" field in the
460 * crypto_async_request data structure provided to the callback function.
462 * Setting the callback function that is triggered once the cipher operation
465 * The callback function is registered with the aead_request handle and
466 * must comply with the following template::
468 * void callback_function(struct crypto_async_request *req, int error)
470 static inline void aead_request_set_callback(struct aead_request
*req
,
472 crypto_completion_t
compl,
475 req
->base
.complete
= compl;
476 req
->base
.data
= data
;
477 req
->base
.flags
= flags
;
481 * aead_request_set_crypt - set data buffers
482 * @req: request handle
483 * @src: source scatter / gather list
484 * @dst: destination scatter / gather list
485 * @cryptlen: number of bytes to process from @src
486 * @iv: IV for the cipher operation which must comply with the IV size defined
487 * by crypto_aead_ivsize()
489 * Setting the source data and destination data scatter / gather lists which
490 * hold the associated data concatenated with the plaintext or ciphertext. See
491 * below for the authentication tag.
493 * For encryption, the source is treated as the plaintext and the
494 * destination is the ciphertext. For a decryption operation, the use is
495 * reversed - the source is the ciphertext and the destination is the plaintext.
497 * The memory structure for cipher operation has the following structure:
499 * - AEAD encryption input: assoc data || plaintext
500 * - AEAD encryption output: assoc data || cipherntext || auth tag
501 * - AEAD decryption input: assoc data || ciphertext || auth tag
502 * - AEAD decryption output: assoc data || plaintext
504 * Albeit the kernel requires the presence of the AAD buffer, however,
505 * the kernel does not fill the AAD buffer in the output case. If the
506 * caller wants to have that data buffer filled, the caller must either
507 * use an in-place cipher operation (i.e. same memory location for
508 * input/output memory location).
510 static inline void aead_request_set_crypt(struct aead_request
*req
,
511 struct scatterlist
*src
,
512 struct scatterlist
*dst
,
513 unsigned int cryptlen
, u8
*iv
)
517 req
->cryptlen
= cryptlen
;
522 * aead_request_set_ad - set associated data information
523 * @req: request handle
524 * @assoclen: number of bytes in associated data
526 * Setting the AD information. This function sets the length of
527 * the associated data.
529 static inline void aead_request_set_ad(struct aead_request
*req
,
530 unsigned int assoclen
)
532 req
->assoclen
= assoclen
;
535 #endif /* _CRYPTO_AEAD_H */