include/crypto/aead.h

   1 /*
   2  * AEAD: Authenticated Encryption with Associated Data
   3  *
   4  * Copyright (c) 2007 Herbert Xu <herbert@gondor.apana.org.au>
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the Free
   8  * Software Foundation; either version 2 of the License, or (at your option)
   9  * any later version.
  10  *
  11  */
  12
  13 #ifndef _CRYPTO_AEAD_H
  14 #define _CRYPTO_AEAD_H
  15
  16 #include <linux/crypto.h>
  17 #include <linux/kernel.h>
  18 #include <linux/slab.h>
  19
  20 /**
  21  * DOC: Authenticated Encryption With Associated Data (AEAD) Cipher API
  22  *
  23  * The AEAD cipher API is used with the ciphers of type CRYPTO_ALG_TYPE_AEAD
  24  * (listed as type "aead" in /proc/crypto)
  25  *
  26  * The most prominent examples for this type of encryption is GCM and CCM.
  27  * However, the kernel supports other types of AEAD ciphers which are defined
  28  * with the following cipher string:
  29  *
  30  *      authenc(keyed message digest, block cipher)
  31  *
  32  * For example: authenc(hmac(sha256), cbc(aes))
  33  *
  34  * The example code provided for the asynchronous block cipher operation
  35  * applies here as well. Naturally all *ablkcipher* symbols must be exchanged
  36  * the *aead* pendants discussed in the following. In addtion, for the AEAD
  37  * operation, the aead_request_set_assoc function must be used to set the
  38  * pointer to the associated data memory location before performing the
  39  * encryption or decryption operation. In case of an encryption, the associated
  40  * data memory is filled during the encryption operation. For decryption, the
  41  * associated data memory must contain data that is used to verify the integrity
  42  * of the decrypted data. Another deviation from the asynchronous block cipher
  43  * operation is that the caller should explicitly check for -EBADMSG of the
  44  * crypto_aead_decrypt. That error indicates an authentication error, i.e.
  45  * a breach in the integrity of the message. In essence, that -EBADMSG error
  46  * code is the key bonus an AEAD cipher has over "standard" block chaining
  47  * modes.
  48  */
  49
  50 /**
  51  *      struct aead_request - AEAD request
  52  *      @base: Common attributes for async crypto requests
  53  *      @old: Boolean whether the old or new AEAD API is used
  54  *      @assoclen: Length in bytes of associated data for authentication
  55  *      @cryptlen: Length of data to be encrypted or decrypted
  56  *      @iv: Initialisation vector
  57  *      @assoc: Associated data
  58  *      @src: Source data
  59  *      @dst: Destination data
  60  *      @__ctx: Start of private context data
  61  */
  62 struct aead_request {
  63         struct crypto_async_request base;
  64
  65         bool old;
  66
  67         unsigned int assoclen;
  68         unsigned int cryptlen;
  69
  70         u8 *iv;
  71
  72         struct scatterlist *assoc;
  73         struct scatterlist *src;
  74         struct scatterlist *dst;
  75
  76         void *__ctx[] CRYPTO_MINALIGN_ATTR;
  77 };
  78
  79 /**
  80  *      struct aead_givcrypt_request - AEAD request with IV generation
  81  *      @seq: Sequence number for IV generation
  82  *      @giv: Space for generated IV
  83  *      @areq: The AEAD request itself
  84  */
  85 struct aead_givcrypt_request {
  86         u64 seq;
  87         u8 *giv;
  88
  89         struct aead_request areq;
  90 };
  91
  92 /**
  93  * struct aead_alg - AEAD cipher definition
  94  * @maxauthsize: Set the maximum authentication tag size supported by the
  95  *               transformation. A transformation may support smaller tag sizes.
  96  *               As the authentication tag is a message digest to ensure the
  97  *               integrity of the encrypted data, a consumer typically wants the
  98  *               largest authentication tag possible as defined by this
  99  *               variable.
 100  * @setauthsize: Set authentication size for the AEAD transformation. This
 101  *               function is used to specify the consumer requested size of the
 102  *               authentication tag to be either generated by the transformation
 103  *               during encryption or the size of the authentication tag to be
 104  *               supplied during the decryption operation. This function is also
 105  *               responsible for checking the authentication tag size for
 106  *               validity.
 107  * @setkey: see struct ablkcipher_alg
 108  * @encrypt: see struct ablkcipher_alg
 109  * @decrypt: see struct ablkcipher_alg
 110  * @geniv: see struct ablkcipher_alg
 111  * @ivsize: see struct ablkcipher_alg
 112  *
 113  * All fields except @ivsize is mandatory and must be filled.
 114  */
 115 struct aead_alg {
 116         int (*setkey)(struct crypto_aead *tfm, const u8 *key,
 117                       unsigned int keylen);
 118         int (*setauthsize)(struct crypto_aead *tfm, unsigned int authsize);
 119         int (*encrypt)(struct aead_request *req);
 120         int (*decrypt)(struct aead_request *req);
 121
 122         const char *geniv;
 123
 124         unsigned int ivsize;
 125         unsigned int maxauthsize;
 126
 127         struct crypto_alg base;
 128 };
 129
 130 struct crypto_aead {
 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 (*givencrypt)(struct aead_givcrypt_request *req);
 137         int (*givdecrypt)(struct aead_givcrypt_request *req);
 138
 139         struct crypto_aead *child;
 140
 141         unsigned int authsize;
 142         unsigned int reqsize;
 143
 144         struct crypto_tfm base;
 145 };
 146
 147 static inline struct crypto_aead *__crypto_aead_cast(struct crypto_tfm *tfm)
 148 {
 149         return container_of(tfm, struct crypto_aead, base);
 150 }
 151
 152 /**
 153  * crypto_alloc_aead() - allocate AEAD cipher handle
 154  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
 155  *           AEAD cipher
 156  * @type: specifies the type of the cipher
 157  * @mask: specifies the mask for the cipher
 158  *
 159  * Allocate a cipher handle for an AEAD. The returned struct
 160  * crypto_aead is the cipher handle that is required for any subsequent
 161  * API invocation for that AEAD.
 162  *
 163  * Return: allocated cipher handle in case of success; IS_ERR() is true in case
 164  *         of an error, PTR_ERR() returns the error code.
 165  */
 166 struct crypto_aead *crypto_alloc_aead(const char *alg_name, u32 type, u32 mask);
 167
 168 static inline struct crypto_tfm *crypto_aead_tfm(struct crypto_aead *tfm)
 169 {
 170         return &tfm->base;
 171 }
 172
 173 /**
 174  * crypto_free_aead() - zeroize and free aead handle
 175  * @tfm: cipher handle to be freed
 176  */
 177 static inline void crypto_free_aead(struct crypto_aead *tfm)
 178 {
 179         crypto_destroy_tfm(tfm, crypto_aead_tfm(tfm));
 180 }
 181
 182 static inline struct crypto_aead *crypto_aead_crt(struct crypto_aead *tfm)
 183 {
 184         return tfm;
 185 }
 186
 187 static inline struct old_aead_alg *crypto_old_aead_alg(struct crypto_aead *tfm)
 188 {
 189         return &crypto_aead_tfm(tfm)->__crt_alg->cra_aead;
 190 }
 191
 192 static inline struct aead_alg *crypto_aead_alg(struct crypto_aead *tfm)
 193 {
 194         return container_of(crypto_aead_tfm(tfm)->__crt_alg,
 195                             struct aead_alg, base);
 196 }
 197
 198 static inline unsigned int crypto_aead_alg_ivsize(struct aead_alg *alg)
 199 {
 200         return alg->base.cra_aead.encrypt ? alg->base.cra_aead.ivsize :
 201                                             alg->ivsize;
 202 }
 203
 204 /**
 205  * crypto_aead_ivsize() - obtain IV size
 206  * @tfm: cipher handle
 207  *
 208  * The size of the IV for the aead referenced by the cipher handle is
 209  * returned. This IV size may be zero if the cipher does not need an IV.
 210  *
 211  * Return: IV size in bytes
 212  */
 213 static inline unsigned int crypto_aead_ivsize(struct crypto_aead *tfm)
 214 {
 215         return crypto_aead_alg_ivsize(crypto_aead_alg(tfm));
 216 }
 217
 218 /**
 219  * crypto_aead_authsize() - obtain maximum authentication data size
 220  * @tfm: cipher handle
 221  *
 222  * The maximum size of the authentication data for the AEAD cipher referenced
 223  * by the AEAD cipher handle is returned. The authentication data size may be
 224  * zero if the cipher implements a hard-coded maximum.
 225  *
 226  * The authentication data may also be known as "tag value".
 227  *
 228  * Return: authentication data size / tag size in bytes
 229  */
 230 static inline unsigned int crypto_aead_authsize(struct crypto_aead *tfm)
 231 {
 232         return tfm->authsize;
 233 }
 234
 235 /**
 236  * crypto_aead_blocksize() - obtain block size of cipher
 237  * @tfm: cipher handle
 238  *
 239  * The block size for the AEAD referenced with the cipher handle is returned.
 240  * The caller may use that information to allocate appropriate memory for the
 241  * data returned by the encryption or decryption operation
 242  *
 243  * Return: block size of cipher
 244  */
 245 static inline unsigned int crypto_aead_blocksize(struct crypto_aead *tfm)
 246 {
 247         return crypto_tfm_alg_blocksize(crypto_aead_tfm(tfm));
 248 }
 249
 250 static inline unsigned int crypto_aead_alignmask(struct crypto_aead *tfm)
 251 {
 252         return crypto_tfm_alg_alignmask(crypto_aead_tfm(tfm));
 253 }
 254
 255 static inline u32 crypto_aead_get_flags(struct crypto_aead *tfm)
 256 {
 257         return crypto_tfm_get_flags(crypto_aead_tfm(tfm));
 258 }
 259
 260 static inline void crypto_aead_set_flags(struct crypto_aead *tfm, u32 flags)
 261 {
 262         crypto_tfm_set_flags(crypto_aead_tfm(tfm), flags);
 263 }
 264
 265 static inline void crypto_aead_clear_flags(struct crypto_aead *tfm, u32 flags)
 266 {
 267         crypto_tfm_clear_flags(crypto_aead_tfm(tfm), flags);
 268 }
 269
 270 /**
 271  * crypto_aead_setkey() - set key for cipher
 272  * @tfm: cipher handle
 273  * @key: buffer holding the key
 274  * @keylen: length of the key in bytes
 275  *
 276  * The caller provided key is set for the AEAD referenced by the cipher
 277  * handle.
 278  *
 279  * Note, the key length determines the cipher type. Many block ciphers implement
 280  * different cipher modes depending on the key size, such as AES-128 vs AES-192
 281  * vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128
 282  * is performed.
 283  *
 284  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
 285  */
 286 int crypto_aead_setkey(struct crypto_aead *tfm,
 287                        const u8 *key, unsigned int keylen);
 288
 289 /**
 290  * crypto_aead_setauthsize() - set authentication data size
 291  * @tfm: cipher handle
 292  * @authsize: size of the authentication data / tag in bytes
 293  *
 294  * Set the authentication data size / tag size. AEAD requires an authentication
 295  * tag (or MAC) in addition to the associated data.
 296  *
 297  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
 298  */
 299 int crypto_aead_setauthsize(struct crypto_aead *tfm, unsigned int authsize);
 300
 301 static inline struct crypto_aead *crypto_aead_reqtfm(struct aead_request *req)
 302 {
 303         return __crypto_aead_cast(req->base.tfm);
 304 }
 305
 306 /**
 307  * crypto_aead_encrypt() - encrypt plaintext
 308  * @req: reference to the aead_request handle that holds all information
 309  *       needed to perform the cipher operation
 310  *
 311  * Encrypt plaintext data using the aead_request handle. That data structure
 312  * and how it is filled with data is discussed with the aead_request_*
 313  * functions.
 314  *
 315  * IMPORTANT NOTE The encryption operation creates the authentication data /
 316  *                tag. That data is concatenated with the created ciphertext.
 317  *                The ciphertext memory size is therefore the given number of
 318  *                block cipher blocks + the size defined by the
 319  *                crypto_aead_setauthsize invocation. The caller must ensure
 320  *                that sufficient memory is available for the ciphertext and
 321  *                the authentication tag.
 322  *
 323  * Return: 0 if the cipher operation was successful; < 0 if an error occurred
 324  */
 325 static inline int crypto_aead_encrypt(struct aead_request *req)
 326 {
 327         return crypto_aead_reqtfm(req)->encrypt(req);
 328 }
 329
 330 /**
 331  * crypto_aead_decrypt() - decrypt ciphertext
 332  * @req: reference to the ablkcipher_request handle that holds all information
 333  *       needed to perform the cipher operation
 334  *
 335  * Decrypt ciphertext data using the aead_request handle. That data structure
 336  * and how it is filled with data is discussed with the aead_request_*
 337  * functions.
 338  *
 339  * IMPORTANT NOTE The caller must concatenate the ciphertext followed by the
 340  *                authentication data / tag. That authentication data / tag
 341  *                must have the size defined by the crypto_aead_setauthsize
 342  *                invocation.
 343  *
 344  *
 345  * Return: 0 if the cipher operation was successful; -EBADMSG: The AEAD
 346  *         cipher operation performs the authentication of the data during the
 347  *         decryption operation. Therefore, the function returns this error if
 348  *         the authentication of the ciphertext was unsuccessful (i.e. the
 349  *         integrity of the ciphertext or the associated data was violated);
 350  *         < 0 if an error occurred.
 351  */
 352 static inline int crypto_aead_decrypt(struct aead_request *req)
 353 {
 354         if (req->cryptlen < crypto_aead_authsize(crypto_aead_reqtfm(req)))
 355                 return -EINVAL;
 356
 357         return crypto_aead_reqtfm(req)->decrypt(req);
 358 }
 359
 360 /**
 361  * DOC: Asynchronous AEAD Request Handle
 362  *
 363  * The aead_request data structure contains all pointers to data required for
 364  * the AEAD cipher operation. This includes the cipher handle (which can be
 365  * used by multiple aead_request instances), pointer to plaintext and
 366  * ciphertext, asynchronous callback function, etc. It acts as a handle to the
 367  * aead_request_* API calls in a similar way as AEAD handle to the
 368  * crypto_aead_* API calls.
 369  */
 370
 371 /**
 372  * crypto_aead_reqsize() - obtain size of the request data structure
 373  * @tfm: cipher handle
 374  *
 375  * Return: number of bytes
 376  */
 377 unsigned int crypto_aead_reqsize(struct crypto_aead *tfm);
 378
 379 /**
 380  * aead_request_set_tfm() - update cipher handle reference in request
 381  * @req: request handle to be modified
 382  * @tfm: cipher handle that shall be added to the request handle
 383  *
 384  * Allow the caller to replace the existing aead handle in the request
 385  * data structure with a different one.
 386  */
 387 static inline void aead_request_set_tfm(struct aead_request *req,
 388                                         struct crypto_aead *tfm)
 389 {
 390         req->base.tfm = crypto_aead_tfm(tfm->child);
 391 }
 392
 393 /**
 394  * aead_request_alloc() - allocate request data structure
 395  * @tfm: cipher handle to be registered with the request
 396  * @gfp: memory allocation flag that is handed to kmalloc by the API call.
 397  *
 398  * Allocate the request data structure that must be used with the AEAD
 399  * encrypt and decrypt API calls. During the allocation, the provided aead
 400  * handle is registered in the request data structure.
 401  *
 402  * Return: allocated request handle in case of success; IS_ERR() is true in case
 403  *         of an error, PTR_ERR() returns the error code.
 404  */
 405 static inline struct aead_request *aead_request_alloc(struct crypto_aead *tfm,
 406                                                       gfp_t gfp)
 407 {
 408         struct aead_request *req;
 409
 410         req = kmalloc(sizeof(*req) + crypto_aead_reqsize(tfm), gfp);
 411
 412         if (likely(req))
 413                 aead_request_set_tfm(req, tfm);
 414
 415         return req;
 416 }
 417
 418 /**
 419  * aead_request_free() - zeroize and free request data structure
 420  * @req: request data structure cipher handle to be freed
 421  */
 422 static inline void aead_request_free(struct aead_request *req)
 423 {
 424         kzfree(req);
 425 }
 426
 427 /**
 428  * aead_request_set_callback() - set asynchronous callback function
 429  * @req: request handle
 430  * @flags: specify zero or an ORing of the flags
 431  *         CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
 432  *         increase the wait queue beyond the initial maximum size;
 433  *         CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
 434  * @compl: callback function pointer to be registered with the request handle
 435  * @data: The data pointer refers to memory that is not used by the kernel
 436  *        crypto API, but provided to the callback function for it to use. Here,
 437  *        the caller can provide a reference to memory the callback function can
 438  *        operate on. As the callback function is invoked asynchronously to the
 439  *        related functionality, it may need to access data structures of the
 440  *        related functionality which can be referenced using this pointer. The
 441  *        callback function can access the memory via the "data" field in the
 442  *        crypto_async_request data structure provided to the callback function.
 443  *
 444  * Setting the callback function that is triggered once the cipher operation
 445  * completes
 446  *
 447  * The callback function is registered with the aead_request handle and
 448  * must comply with the following template
 449  *
 450  *      void callback_function(struct crypto_async_request *req, int error)
 451  */
 452 static inline void aead_request_set_callback(struct aead_request *req,
 453                                              u32 flags,
 454                                              crypto_completion_t compl,
 455                                              void *data)
 456 {
 457         req->base.complete = compl;
 458         req->base.data = data;
 459         req->base.flags = flags;
 460 }
 461
 462 /**
 463  * aead_request_set_crypt - set data buffers
 464  * @req: request handle
 465  * @src: source scatter / gather list
 466  * @dst: destination scatter / gather list
 467  * @cryptlen: number of bytes to process from @src
 468  * @iv: IV for the cipher operation which must comply with the IV size defined
 469  *      by crypto_aead_ivsize()
 470  *
 471  * Setting the source data and destination data scatter / gather lists which
 472  * hold the associated data concatenated with the plaintext or ciphertext. See
 473  * below for the authentication tag.
 474  *
 475  * For encryption, the source is treated as the plaintext and the
 476  * destination is the ciphertext. For a decryption operation, the use is
 477  * reversed - the source is the ciphertext and the destination is the plaintext.
 478  *
 479  * For both src/dst the layout is associated data, plain/cipher text,
 480  * authentication tag.
 481  *
 482  * The content of the AD in the destination buffer after processing
 483  * will either be untouched, or it will contain a copy of the AD
 484  * from the source buffer.  In order to ensure that it always has
 485  * a copy of the AD, the user must copy the AD over either before
 486  * or after processing.  Of course this is not relevant if the user
 487  * is doing in-place processing where src == dst.
 488  *
 489  * IMPORTANT NOTE AEAD requires an authentication tag (MAC). For decryption,
 490  *                the caller must concatenate the ciphertext followed by the
 491  *                authentication tag and provide the entire data stream to the
 492  *                decryption operation (i.e. the data length used for the
 493  *                initialization of the scatterlist and the data length for the
 494  *                decryption operation is identical). For encryption, however,
 495  *                the authentication tag is created while encrypting the data.
 496  *                The destination buffer must hold sufficient space for the
 497  *                ciphertext and the authentication tag while the encryption
 498  *                invocation must only point to the plaintext data size. The
 499  *                following code snippet illustrates the memory usage
 500  *                buffer = kmalloc(ptbuflen + (enc ? authsize : 0));
 501  *                sg_init_one(&sg, buffer, ptbuflen + (enc ? authsize : 0));
 502  *                aead_request_set_crypt(req, &sg, &sg, ptbuflen, iv);
 503  */
 504 static inline void aead_request_set_crypt(struct aead_request *req,
 505                                           struct scatterlist *src,
 506                                           struct scatterlist *dst,
 507                                           unsigned int cryptlen, u8 *iv)
 508 {
 509         req->src = src;
 510         req->dst = dst;
 511         req->cryptlen = cryptlen;
 512         req->iv = iv;
 513 }
 514
 515 /**
 516  * aead_request_set_assoc() - set the associated data scatter / gather list
 517  * @req: request handle
 518  * @assoc: associated data scatter / gather list
 519  * @assoclen: number of bytes to process from @assoc
 520  *
 521  * Obsolete, do not use.
 522  */
 523 static inline void aead_request_set_assoc(struct aead_request *req,
 524                                           struct scatterlist *assoc,
 525                                           unsigned int assoclen)
 526 {
 527         req->assoc = assoc;
 528         req->assoclen = assoclen;
 529         req->old = true;
 530 }
 531
 532 /**
 533  * aead_request_set_ad - set associated data information
 534  * @req: request handle
 535  * @assoclen: number of bytes in associated data
 536  *
 537  * Setting the AD information.  This function sets the length of
 538  * the associated data.
 539  */
 540 static inline void aead_request_set_ad(struct aead_request *req,
 541                                        unsigned int assoclen)
 542 {
 543         req->assoclen = assoclen;
 544         req->old = false;
 545 }
 546
 547 static inline struct crypto_aead *aead_givcrypt_reqtfm(
 548         struct aead_givcrypt_request *req)
 549 {
 550         return crypto_aead_reqtfm(&req->areq);
 551 }
 552
 553 static inline int crypto_aead_givencrypt(struct aead_givcrypt_request *req)
 554 {
 555         return aead_givcrypt_reqtfm(req)->givencrypt(req);
 556 };
 557
 558 static inline int crypto_aead_givdecrypt(struct aead_givcrypt_request *req)
 559 {
 560         return aead_givcrypt_reqtfm(req)->givdecrypt(req);
 561 };
 562
 563 static inline void aead_givcrypt_set_tfm(struct aead_givcrypt_request *req,
 564                                          struct crypto_aead *tfm)
 565 {
 566         req->areq.base.tfm = crypto_aead_tfm(tfm);
 567 }
 568
 569 static inline struct aead_givcrypt_request *aead_givcrypt_alloc(
 570         struct crypto_aead *tfm, gfp_t gfp)
 571 {
 572         struct aead_givcrypt_request *req;
 573
 574         req = kmalloc(sizeof(struct aead_givcrypt_request) +
 575                       crypto_aead_reqsize(tfm), gfp);
 576
 577         if (likely(req))
 578                 aead_givcrypt_set_tfm(req, tfm);
 579
 580         return req;
 581 }
 582
 583 static inline void aead_givcrypt_free(struct aead_givcrypt_request *req)
 584 {
 585         kfree(req);
 586 }
 587
 588 static inline void aead_givcrypt_set_callback(
 589         struct aead_givcrypt_request *req, u32 flags,
 590         crypto_completion_t compl, void *data)
 591 {
 592         aead_request_set_callback(&req->areq, flags, compl, data);
 593 }
 594
 595 static inline void aead_givcrypt_set_crypt(struct aead_givcrypt_request *req,
 596                                            struct scatterlist *src,
 597                                            struct scatterlist *dst,
 598                                            unsigned int nbytes, void *iv)
 599 {
 600         aead_request_set_crypt(&req->areq, src, dst, nbytes, iv);
 601 }
 602
 603 static inline void aead_givcrypt_set_assoc(struct aead_givcrypt_request *req,
 604                                            struct scatterlist *assoc,
 605                                            unsigned int assoclen)
 606 {
 607         aead_request_set_assoc(&req->areq, assoc, assoclen);
 608 }
 609
 610 static inline void aead_givcrypt_set_giv(struct aead_givcrypt_request *req,
 611                                          u8 *giv, u64 seq)
 612 {
 613         req->giv = giv;
 614         req->seq = seq;
 615 }
 616
 617 #endif  /* _CRYPTO_AEAD_H */