include/crypto/aead.h

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>
18  * DOC: Authenticated Encryption With Associated Data (AEAD) Cipher API
35  * associated data memory location before performing the encryption or
37  * operation is that the caller should explicitly check for -EBADMSG of the
39  * a breach in the integrity of the message. In essence, that -EBADMSG error
46  * associated data || plaintext or ciphertext.
49  * (resp. ciphertext) will grow (resp. shrink) by the authentication tag size
53  * used to verify the integrity of the plaintext and the associated data.
55  * In-place encryption/decryption is enabled by using the same scatterlist
58  * Even in the out-of-place case, space must be reserved in the destination for
59  * the associated data, even though it won't be written to.  This makes the
60  * in-place and out-of-place cases more consistent.  It is permissible for the
61  * "destination" associated data to alias the "source" associated data.
63  * As with the other scatterlist crypto APIs, zero-length scatterlist elements
65  * associated data, the first element must point to the plaintext/ciphertext.
69  * of the associated data buffer must contain a second copy of the IV.  This is
73  * treat the IV as associated data; nevertheless the length passed to
81  *	struct aead_request - AEAD request
83  *	@assoclen: Length in bytes of associated data for authentication
84  *	@cryptlen: Length of data to be encrypted or decrypted
86  *	@src: Source data
87  *	@dst: Destination data
88  *	@__ctx: Start of private context data
105  * struct aead_alg - AEAD cipher definition
106  * @maxauthsize: Set the maximum authentication tag size supported by the
109  *		 integrity of the encrypted data, a consumer typically wants the
112  * @setauthsize: Set authentication size for the AEAD transformation. This
113  *		 function is used to specify the consumer requested size of the
115  *		 during encryption or the size of the authentication tag to be
117  *		 responsible for checking the authentication tag size for
168  * crypto_alloc_aead() - allocate AEAD cipher handle
185 	return &tfm->base;  in crypto_aead_tfm()
189  * crypto_free_aead() - zeroize and free aead handle
200  * crypto_has_aead() - Search for the availability of an aead.
218 	return container_of(crypto_aead_tfm(tfm)->__crt_alg,  in crypto_aead_alg()
224 	return alg->ivsize;  in crypto_aead_alg_ivsize()
228  * crypto_aead_ivsize() - obtain IV size
231  * The size of the IV for the aead referenced by the cipher handle is
232  * returned. This IV size may be zero if the cipher does not need an IV.
234  * Return: IV size in bytes
242  * crypto_aead_authsize() - obtain maximum authentication data size
245  * The maximum size of the authentication data for the AEAD cipher referenced
246  * by the AEAD cipher handle is returned. The authentication data size may be
247  * zero if the cipher implements a hard-coded maximum.
249  * The authentication data may also be known as "tag value".
251  * Return: authentication data size / tag size in bytes
255 	return tfm->authsize;  in crypto_aead_authsize()
260 	return alg->maxauthsize;  in crypto_aead_alg_maxauthsize()
269  * crypto_aead_blocksize() - obtain block size of cipher
272  * The block size for the AEAD referenced with the cipher handle is returned.
274  * data returned by the encryption or decryption operation
276  * Return: block size of cipher
304  * crypto_aead_setkey() - set key for cipher
313  * different cipher modes depending on the key size, such as AES-128 vs AES-192
314  * vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128
323  * crypto_aead_setauthsize() - set authentication data size
325  * @authsize: size of the authentication data / tag in bytes
327  * Set the authentication data size / tag size. AEAD requires an authentication
328  * tag (or MAC) in addition to the associated data.
336 	return __crypto_aead_cast(req->base.tfm);  in crypto_aead_reqtfm()
340  * crypto_aead_encrypt() - encrypt plaintext
344  * Encrypt plaintext data using the aead_request handle. That data structure
345  * and how it is filled with data is discussed with the aead_request_*
348  * IMPORTANT NOTE The encryption operation creates the authentication data /
349  *		  tag. That data is concatenated with the created ciphertext.
350  *		  The ciphertext memory size is therefore the given number of
351  *		  block cipher blocks + the size defined by the
361  * crypto_aead_decrypt() - decrypt ciphertext
365  * Decrypt ciphertext data using the aead_request handle. That data structure
366  * and how it is filled with data is discussed with the aead_request_*
370  *		  authentication data / tag. That authentication data / tag
371  *		  must have the size defined by the crypto_aead_setauthsize
375  * Return: 0 if the cipher operation was successful; -EBADMSG: The AEAD
376  *	   cipher operation performs the authentication of the data during the
379  *	   integrity of the ciphertext or the associated data was violated);
387  * The aead_request data structure contains all pointers to data required for
396  * crypto_aead_reqsize() - obtain size of the request data structure
403 	return tfm->reqsize;  in crypto_aead_reqsize()
407  * aead_request_set_tfm() - update cipher handle reference in request
412  * data structure with a different one.
417 	req->base.tfm = crypto_aead_tfm(tfm);  in aead_request_set_tfm()
421  * aead_request_alloc() - allocate request data structure
425  * Allocate the request data structure that must be used with the AEAD
427  * handle is registered in the request data structure.
445  * aead_request_free() - zeroize and free request data structure
446  * @req: request data structure cipher handle to be freed
454  * aead_request_set_callback() - set asynchronous callback function
458  *	   increase the wait queue beyond the initial maximum size;
461  * @data: The data pointer refers to memory that is not used by the kernel
465  *	  related functionality, it may need to access data structures of the
467  *	  callback function can access the memory via the "data" field in the
468  *	  crypto_async_request data structure provided to the callback function.
481 					     void *data)  in aead_request_set_callback()  argument
483 	req->base.complete = compl;  in aead_request_set_callback()
484 	req->base.data = data;  in aead_request_set_callback()
485 	req->base.flags = flags;  in aead_request_set_callback()
489  * aead_request_set_crypt - set data buffers
494  * @iv: IV for the cipher operation which must comply with the IV size defined
497  * Setting the source data and destination data scatter / gather lists which
498  * hold the associated data concatenated with the plaintext or ciphertext. See
503  * reversed - the source is the ciphertext and the destination is the plaintext.
507  * - AEAD encryption input:  assoc data || plaintext
508  * - AEAD encryption output: assoc data || ciphertext || auth tag
509  * - AEAD decryption input:  assoc data || ciphertext || auth tag
510  * - AEAD decryption output: assoc data || plaintext
514  * caller wants to have that data buffer filled, the caller must either
515  * use an in-place cipher operation (i.e. same memory location for
523 	req->src = src;  in aead_request_set_crypt()
524 	req->dst = dst;  in aead_request_set_crypt()
525 	req->cryptlen = cryptlen;  in aead_request_set_crypt()
526 	req->iv = iv;  in aead_request_set_crypt()
530  * aead_request_set_ad - set associated data information
532  * @assoclen: number of bytes in associated data
535  * the associated data.
540 	req->assoclen = assoclen;  in aead_request_set_ad()