root/include/crypto/aead.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


DEFINITIONS

This source file includes following definitions.
  1. __crypto_aead_cast
  2. crypto_aead_tfm
  3. crypto_free_aead
  4. crypto_aead_alg
  5. crypto_aead_alg_ivsize
  6. crypto_aead_ivsize
  7. crypto_aead_authsize
  8. crypto_aead_blocksize
  9. crypto_aead_alignmask
  10. crypto_aead_get_flags
  11. crypto_aead_set_flags
  12. crypto_aead_clear_flags
  13. crypto_aead_reqtfm
  14. crypto_aead_reqsize
  15. aead_request_set_tfm
  16. aead_request_alloc
  17. aead_request_free
  18. aead_request_set_callback
  19. aead_request_set_crypt
  20. aead_request_set_ad

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 /*
   3  * AEAD: Authenticated Encryption with Associated Data
   4  * 
   5  * Copyright (c) 2007-2015 Herbert Xu <herbert@gondor.apana.org.au>
   6  */
   7 
   8 #ifndef _CRYPTO_AEAD_H
   9 #define _CRYPTO_AEAD_H
  10 
  11 #include <linux/crypto.h>
  12 #include <linux/kernel.h>
  13 #include <linux/slab.h>
  14 
  15 /**
  16  * DOC: Authenticated Encryption With Associated Data (AEAD) Cipher API
  17  *
  18  * The AEAD cipher API is used with the ciphers of type CRYPTO_ALG_TYPE_AEAD
  19  * (listed as type "aead" in /proc/crypto)
  20  *
  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:
  24  *
  25  *      authenc(keyed message digest, block cipher)
  26  *
  27  * For example: authenc(hmac(sha256), cbc(aes))
  28  *
  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
  42  * modes.
  43  *
  44  * Memory Structure:
  45  *
  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
  48  * to.
  49  *
  50  * The scatter list pointing to the input data must contain:
  51  *
  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.
  58  *
  59  * * for "normal" AEAD ciphers, the concatenation of
  60  *   associated authentication data || plaintext or ciphertext.
  61  *
  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.
  67  */
  68 
  69 struct crypto_aead;
  70 
  71 /**
  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
  77  *      @src: Source data
  78  *      @dst: Destination data
  79  *      @__ctx: Start of private context data
  80  */
  81 struct aead_request {
  82         struct crypto_async_request base;
  83 
  84         unsigned int assoclen;
  85         unsigned int cryptlen;
  86 
  87         u8 *iv;
  88 
  89         struct scatterlist *src;
  90         struct scatterlist *dst;
  91 
  92         void *__ctx[] CRYPTO_MINALIGN_ATTR;
  93 };
  94 
  95 /**
  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
 102  *               variable.
 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
 109  *               validity.
 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
 122  *        in place.
 123  * @exit: Deinitialize the cryptographic transformation object. This is a
 124  *        counterpart to @init, used to remove various changes set in
 125  *        @init.
 126  * @base: Definition of a generic crypto cipher algorithm.
 127  *
 128  * All fields except @ivsize is mandatory and must be filled.
 129  */
 130 struct aead_alg {
 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);
 138 
 139         unsigned int ivsize;
 140         unsigned int maxauthsize;
 141         unsigned int chunksize;
 142 
 143         struct crypto_alg base;
 144 };
 145 
 146 struct crypto_aead {
 147         unsigned int authsize;
 148         unsigned int reqsize;
 149 
 150         struct crypto_tfm base;
 151 };
 152 
 153 static inline struct crypto_aead *__crypto_aead_cast(struct crypto_tfm *tfm)
 154 {
 155         return container_of(tfm, struct crypto_aead, base);
 156 }
 157 
 158 /**
 159  * crypto_alloc_aead() - allocate AEAD cipher handle
 160  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
 161  *           AEAD cipher
 162  * @type: specifies the type of the cipher
 163  * @mask: specifies the mask for the cipher
 164  *
 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.
 168  *
 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.
 171  */
 172 struct crypto_aead *crypto_alloc_aead(const char *alg_name, u32 type, u32 mask);
 173 
 174 static inline struct crypto_tfm *crypto_aead_tfm(struct crypto_aead *tfm)
 175 {
 176         return &tfm->base;
 177 }
 178 
 179 /**
 180  * crypto_free_aead() - zeroize and free aead handle
 181  * @tfm: cipher handle to be freed
 182  */
 183 static inline void crypto_free_aead(struct crypto_aead *tfm)
 184 {
 185         crypto_destroy_tfm(tfm, crypto_aead_tfm(tfm));
 186 }
 187 
 188 static inline struct aead_alg *crypto_aead_alg(struct crypto_aead *tfm)
 189 {
 190         return container_of(crypto_aead_tfm(tfm)->__crt_alg,
 191                             struct aead_alg, base);
 192 }
 193 
 194 static inline unsigned int crypto_aead_alg_ivsize(struct aead_alg *alg)
 195 {
 196         return alg->ivsize;
 197 }
 198 
 199 /**
 200  * crypto_aead_ivsize() - obtain IV size
 201  * @tfm: cipher handle
 202  *
 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.
 205  *
 206  * Return: IV size in bytes
 207  */
 208 static inline unsigned int crypto_aead_ivsize(struct crypto_aead *tfm)
 209 {
 210         return crypto_aead_alg_ivsize(crypto_aead_alg(tfm));
 211 }
 212 
 213 /**
 214  * crypto_aead_authsize() - obtain maximum authentication data size
 215  * @tfm: cipher handle
 216  *
 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.
 220  *
 221  * The authentication data may also be known as "tag value".
 222  *
 223  * Return: authentication data size / tag size in bytes
 224  */
 225 static inline unsigned int crypto_aead_authsize(struct crypto_aead *tfm)
 226 {
 227         return tfm->authsize;
 228 }
 229 
 230 /**
 231  * crypto_aead_blocksize() - obtain block size of cipher
 232  * @tfm: cipher handle
 233  *
 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
 237  *
 238  * Return: block size of cipher
 239  */
 240 static inline unsigned int crypto_aead_blocksize(struct crypto_aead *tfm)
 241 {
 242         return crypto_tfm_alg_blocksize(crypto_aead_tfm(tfm));
 243 }
 244 
 245 static inline unsigned int crypto_aead_alignmask(struct crypto_aead *tfm)
 246 {
 247         return crypto_tfm_alg_alignmask(crypto_aead_tfm(tfm));
 248 }
 249 
 250 static inline u32 crypto_aead_get_flags(struct crypto_aead *tfm)
 251 {
 252         return crypto_tfm_get_flags(crypto_aead_tfm(tfm));
 253 }
 254 
 255 static inline void crypto_aead_set_flags(struct crypto_aead *tfm, u32 flags)
 256 {
 257         crypto_tfm_set_flags(crypto_aead_tfm(tfm), flags);
 258 }
 259 
 260 static inline void crypto_aead_clear_flags(struct crypto_aead *tfm, u32 flags)
 261 {
 262         crypto_tfm_clear_flags(crypto_aead_tfm(tfm), flags);
 263 }
 264 
 265 /**
 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
 270  *
 271  * The caller provided key is set for the AEAD referenced by the cipher
 272  * handle.
 273  *
 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
 277  * is performed.
 278  *
 279  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
 280  */
 281 int crypto_aead_setkey(struct crypto_aead *tfm,
 282                        const u8 *key, unsigned int keylen);
 283 
 284 /**
 285  * crypto_aead_setauthsize() - set authentication data size
 286  * @tfm: cipher handle
 287  * @authsize: size of the authentication data / tag in bytes
 288  *
 289  * Set the authentication data size / tag size. AEAD requires an authentication
 290  * tag (or MAC) in addition to the associated data.
 291  *
 292  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
 293  */
 294 int crypto_aead_setauthsize(struct crypto_aead *tfm, unsigned int authsize);
 295 
 296 static inline struct crypto_aead *crypto_aead_reqtfm(struct aead_request *req)
 297 {
 298         return __crypto_aead_cast(req->base.tfm);
 299 }
 300 
 301 /**
 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
 305  *
 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_*
 308  * functions.
 309  *
 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.
 317  *
 318  * Return: 0 if the cipher operation was successful; < 0 if an error occurred
 319  */
 320 int crypto_aead_encrypt(struct aead_request *req);
 321 
 322 /**
 323  * crypto_aead_decrypt() - decrypt ciphertext
 324  * @req: reference to the ablkcipher_request handle that holds all information
 325  *       needed to perform the cipher operation
 326  *
 327  * Decrypt ciphertext data using the aead_request handle. That data structure
 328  * and how it is filled with data is discussed with the aead_request_*
 329  * functions.
 330  *
 331  * IMPORTANT NOTE The caller must concatenate the ciphertext followed by the
 332  *                authentication data / tag. That authentication data / tag
 333  *                must have the size defined by the crypto_aead_setauthsize
 334  *                invocation.
 335  *
 336  *
 337  * Return: 0 if the cipher operation was successful; -EBADMSG: The AEAD
 338  *         cipher operation performs the authentication of the data during the
 339  *         decryption operation. Therefore, the function returns this error if
 340  *         the authentication of the ciphertext was unsuccessful (i.e. the
 341  *         integrity of the ciphertext or the associated data was violated);
 342  *         < 0 if an error occurred.
 343  */
 344 int crypto_aead_decrypt(struct aead_request *req);
 345 
 346 /**
 347  * DOC: Asynchronous AEAD Request Handle
 348  *
 349  * The aead_request data structure contains all pointers to data required for
 350  * the AEAD cipher operation. This includes the cipher handle (which can be
 351  * used by multiple aead_request instances), pointer to plaintext and
 352  * ciphertext, asynchronous callback function, etc. It acts as a handle to the
 353  * aead_request_* API calls in a similar way as AEAD handle to the
 354  * crypto_aead_* API calls.
 355  */
 356 
 357 /**
 358  * crypto_aead_reqsize() - obtain size of the request data structure
 359  * @tfm: cipher handle
 360  *
 361  * Return: number of bytes
 362  */
 363 static inline unsigned int crypto_aead_reqsize(struct crypto_aead *tfm)
 364 {
 365         return tfm->reqsize;
 366 }
 367 
 368 /**
 369  * aead_request_set_tfm() - update cipher handle reference in request
 370  * @req: request handle to be modified
 371  * @tfm: cipher handle that shall be added to the request handle
 372  *
 373  * Allow the caller to replace the existing aead handle in the request
 374  * data structure with a different one.
 375  */
 376 static inline void aead_request_set_tfm(struct aead_request *req,
 377                                         struct crypto_aead *tfm)
 378 {
 379         req->base.tfm = crypto_aead_tfm(tfm);
 380 }
 381 
 382 /**
 383  * aead_request_alloc() - allocate request data structure
 384  * @tfm: cipher handle to be registered with the request
 385  * @gfp: memory allocation flag that is handed to kmalloc by the API call.
 386  *
 387  * Allocate the request data structure that must be used with the AEAD
 388  * encrypt and decrypt API calls. During the allocation, the provided aead
 389  * handle is registered in the request data structure.
 390  *
 391  * Return: allocated request handle in case of success, or NULL if out of memory
 392  */
 393 static inline struct aead_request *aead_request_alloc(struct crypto_aead *tfm,
 394                                                       gfp_t gfp)
 395 {
 396         struct aead_request *req;
 397 
 398         req = kmalloc(sizeof(*req) + crypto_aead_reqsize(tfm), gfp);
 399 
 400         if (likely(req))
 401                 aead_request_set_tfm(req, tfm);
 402 
 403         return req;
 404 }
 405 
 406 /**
 407  * aead_request_free() - zeroize and free request data structure
 408  * @req: request data structure cipher handle to be freed
 409  */
 410 static inline void aead_request_free(struct aead_request *req)
 411 {
 412         kzfree(req);
 413 }
 414 
 415 /**
 416  * aead_request_set_callback() - set asynchronous callback function
 417  * @req: request handle
 418  * @flags: specify zero or an ORing of the flags
 419  *         CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
 420  *         increase the wait queue beyond the initial maximum size;
 421  *         CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
 422  * @compl: callback function pointer to be registered with the request handle
 423  * @data: The data pointer refers to memory that is not used by the kernel
 424  *        crypto API, but provided to the callback function for it to use. Here,
 425  *        the caller can provide a reference to memory the callback function can
 426  *        operate on. As the callback function is invoked asynchronously to the
 427  *        related functionality, it may need to access data structures of the
 428  *        related functionality which can be referenced using this pointer. The
 429  *        callback function can access the memory via the "data" field in the
 430  *        crypto_async_request data structure provided to the callback function.
 431  *
 432  * Setting the callback function that is triggered once the cipher operation
 433  * completes
 434  *
 435  * The callback function is registered with the aead_request handle and
 436  * must comply with the following template::
 437  *
 438  *      void callback_function(struct crypto_async_request *req, int error)
 439  */
 440 static inline void aead_request_set_callback(struct aead_request *req,
 441                                              u32 flags,
 442                                              crypto_completion_t compl,
 443                                              void *data)
 444 {
 445         req->base.complete = compl;
 446         req->base.data = data;
 447         req->base.flags = flags;
 448 }
 449 
 450 /**
 451  * aead_request_set_crypt - set data buffers
 452  * @req: request handle
 453  * @src: source scatter / gather list
 454  * @dst: destination scatter / gather list
 455  * @cryptlen: number of bytes to process from @src
 456  * @iv: IV for the cipher operation which must comply with the IV size defined
 457  *      by crypto_aead_ivsize()
 458  *
 459  * Setting the source data and destination data scatter / gather lists which
 460  * hold the associated data concatenated with the plaintext or ciphertext. See
 461  * below for the authentication tag.
 462  *
 463  * For encryption, the source is treated as the plaintext and the
 464  * destination is the ciphertext. For a decryption operation, the use is
 465  * reversed - the source is the ciphertext and the destination is the plaintext.
 466  *
 467  * The memory structure for cipher operation has the following structure:
 468  *
 469  * - AEAD encryption input:  assoc data || plaintext
 470  * - AEAD encryption output: assoc data || cipherntext || auth tag
 471  * - AEAD decryption input:  assoc data || ciphertext || auth tag
 472  * - AEAD decryption output: assoc data || plaintext
 473  *
 474  * Albeit the kernel requires the presence of the AAD buffer, however,
 475  * the kernel does not fill the AAD buffer in the output case. If the
 476  * caller wants to have that data buffer filled, the caller must either
 477  * use an in-place cipher operation (i.e. same memory location for
 478  * input/output memory location).
 479  */
 480 static inline void aead_request_set_crypt(struct aead_request *req,
 481                                           struct scatterlist *src,
 482                                           struct scatterlist *dst,
 483                                           unsigned int cryptlen, u8 *iv)
 484 {
 485         req->src = src;
 486         req->dst = dst;
 487         req->cryptlen = cryptlen;
 488         req->iv = iv;
 489 }
 490 
 491 /**
 492  * aead_request_set_ad - set associated data information
 493  * @req: request handle
 494  * @assoclen: number of bytes in associated data
 495  *
 496  * Setting the AD information.  This function sets the length of
 497  * the associated data.
 498  */
 499 static inline void aead_request_set_ad(struct aead_request *req,
 500                                        unsigned int assoclen)
 501 {
 502         req->assoclen = assoclen;
 503 }
 504 
 505 #endif  /* _CRYPTO_AEAD_H */

/* [<][>][^][v][top][bottom][index][help] */