include/crypto/hash.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 /*
   3  * Hash: Hash algorithms under the crypto API
   4  *
   5  * Copyright (c) 2008 Herbert Xu <herbert@gondor.apana.org.au>
   6  */
   7
   8 #ifndef _CRYPTO_HASH_H
   9 #define _CRYPTO_HASH_H
  10
  11 #include <linux/crypto.h>
  12 #include <linux/string.h>
  13
  14 struct crypto_ahash;
  15
  16 /**
  17  * DOC: Message Digest Algorithm Definitions
  18  *
  19  * These data structures define modular message digest algorithm
  20  * implementations, managed via crypto_register_ahash(),
  21  * crypto_register_shash(), crypto_unregister_ahash() and
  22  * crypto_unregister_shash().
  23  */
  24
  25 /**
  26  * struct hash_alg_common - define properties of message digest
  27  * @digestsize: Size of the result of the transformation. A buffer of this size
  28  *              must be available to the @final and @finup calls, so they can
  29  *              store the resulting hash into it. For various predefined sizes,
  30  *              search include/crypto/ using
  31  *              git grep _DIGEST_SIZE include/crypto.
  32  * @statesize: Size of the block for partial state of the transformation. A
  33  *             buffer of this size must be passed to the @export function as it
  34  *             will save the partial state of the transformation into it. On the
  35  *             other side, the @import function will load the state from a
  36  *             buffer of this size as well.
  37  * @base: Start of data structure of cipher algorithm. The common data
  38  *        structure of crypto_alg contains information common to all ciphers.
  39  *        The hash_alg_common data structure now adds the hash-specific
  40  *        information.
  41  */
  42 struct hash_alg_common {
  43         unsigned int digestsize;
  44         unsigned int statesize;
  45
  46         struct crypto_alg base;
  47 };
  48
  49 struct ahash_request {
  50         struct crypto_async_request base;
  51
  52         unsigned int nbytes;
  53         struct scatterlist *src;
  54         u8 *result;
  55
  56         /* This field may only be used by the ahash API code. */
  57         void *priv;
  58
  59         void *__ctx[] CRYPTO_MINALIGN_ATTR;
  60 };
  61
  62 #define AHASH_REQUEST_ON_STACK(name, ahash) \
  63         char __##name##_desc[sizeof(struct ahash_request) + \
  64                 crypto_ahash_reqsize(ahash)] CRYPTO_MINALIGN_ATTR; \
  65         struct ahash_request *name = (void *)__##name##_desc
  66
  67 /**
  68  * struct ahash_alg - asynchronous message digest definition
  69  * @init: **[mandatory]** Initialize the transformation context. Intended only to initialize the
  70  *        state of the HASH transformation at the beginning. This shall fill in
  71  *        the internal structures used during the entire duration of the whole
  72  *        transformation. No data processing happens at this point. Driver code
  73  *        implementation must not use req->result.
  74  * @update: **[mandatory]** Push a chunk of data into the driver for transformation. This
  75  *         function actually pushes blocks of data from upper layers into the
  76  *         driver, which then passes those to the hardware as seen fit. This
  77  *         function must not finalize the HASH transformation by calculating the
  78  *         final message digest as this only adds more data into the
  79  *         transformation. This function shall not modify the transformation
  80  *         context, as this function may be called in parallel with the same
  81  *         transformation object. Data processing can happen synchronously
  82  *         [SHASH] or asynchronously [AHASH] at this point. Driver must not use
  83  *         req->result.
  84  * @final: **[mandatory]** Retrieve result from the driver. This function finalizes the
  85  *         transformation and retrieves the resulting hash from the driver and
  86  *         pushes it back to upper layers. No data processing happens at this
  87  *         point unless hardware requires it to finish the transformation
  88  *         (then the data buffered by the device driver is processed).
  89  * @finup: **[optional]** Combination of @update and @final. This function is effectively a
  90  *         combination of @update and @final calls issued in sequence. As some
  91  *         hardware cannot do @update and @final separately, this callback was
  92  *         added to allow such hardware to be used at least by IPsec. Data
  93  *         processing can happen synchronously [SHASH] or asynchronously [AHASH]
  94  *         at this point.
  95  * @digest: Combination of @init and @update and @final. This function
  96  *          effectively behaves as the entire chain of operations, @init,
  97  *          @update and @final issued in sequence. Just like @finup, this was
  98  *          added for hardware which cannot do even the @finup, but can only do
  99  *          the whole transformation in one run. Data processing can happen
 100  *          synchronously [SHASH] or asynchronously [AHASH] at this point.
 101  * @setkey: Set optional key used by the hashing algorithm. Intended to push
 102  *          optional key used by the hashing algorithm from upper layers into
 103  *          the driver. This function can store the key in the transformation
 104  *          context or can outright program it into the hardware. In the former
 105  *          case, one must be careful to program the key into the hardware at
 106  *          appropriate time and one must be careful that .setkey() can be
 107  *          called multiple times during the existence of the transformation
 108  *          object. Not  all hashing algorithms do implement this function as it
 109  *          is only needed for keyed message digests. SHAx/MDx/CRCx do NOT
 110  *          implement this function. HMAC(MDx)/HMAC(SHAx)/CMAC(AES) do implement
 111  *          this function. This function must be called before any other of the
 112  *          @init, @update, @final, @finup, @digest is called. No data
 113  *          processing happens at this point.
 114  * @export: Export partial state of the transformation. This function dumps the
 115  *          entire state of the ongoing transformation into a provided block of
 116  *          data so it can be @import 'ed back later on. This is useful in case
 117  *          you want to save partial result of the transformation after
 118  *          processing certain amount of data and reload this partial result
 119  *          multiple times later on for multiple re-use. No data processing
 120  *          happens at this point. Driver must not use req->result.
 121  * @import: Import partial state of the transformation. This function loads the
 122  *          entire state of the ongoing transformation from a provided block of
 123  *          data so the transformation can continue from this point onward. No
 124  *          data processing happens at this point. Driver must not use
 125  *          req->result.
 126  * @halg: see struct hash_alg_common
 127  */
 128 struct ahash_alg {
 129         int (*init)(struct ahash_request *req);
 130         int (*update)(struct ahash_request *req);
 131         int (*final)(struct ahash_request *req);
 132         int (*finup)(struct ahash_request *req);
 133         int (*digest)(struct ahash_request *req);
 134         int (*export)(struct ahash_request *req, void *out);
 135         int (*import)(struct ahash_request *req, const void *in);
 136         int (*setkey)(struct crypto_ahash *tfm, const u8 *key,
 137                       unsigned int keylen);
 138
 139         struct hash_alg_common halg;
 140 };
 141
 142 struct shash_desc {
 143         struct crypto_shash *tfm;
 144         void *__ctx[] CRYPTO_MINALIGN_ATTR;
 145 };
 146
 147 #define HASH_MAX_DIGESTSIZE      64
 148
 149 /*
 150  * Worst case is hmac(sha3-224-generic).  Its context is a nested 'shash_desc'
 151  * containing a 'struct sha3_state'.
 152  */
 153 #define HASH_MAX_DESCSIZE       (sizeof(struct shash_desc) + 360)
 154
 155 #define HASH_MAX_STATESIZE      512
 156
 157 #define SHASH_DESC_ON_STACK(shash, ctx)                           \
 158         char __##shash##_desc[sizeof(struct shash_desc) +         \
 159                 HASH_MAX_DESCSIZE] CRYPTO_MINALIGN_ATTR; \
 160         struct shash_desc *shash = (struct shash_desc *)__##shash##_desc
 161
 162 /**
 163  * struct shash_alg - synchronous message digest definition
 164  * @init: see struct ahash_alg
 165  * @update: see struct ahash_alg
 166  * @final: see struct ahash_alg
 167  * @finup: see struct ahash_alg
 168  * @digest: see struct ahash_alg
 169  * @export: see struct ahash_alg
 170  * @import: see struct ahash_alg
 171  * @setkey: see struct ahash_alg
 172  * @digestsize: see struct ahash_alg
 173  * @statesize: see struct ahash_alg
 174  * @descsize: Size of the operational state for the message digest. This state
 175  *            size is the memory size that needs to be allocated for
 176  *            shash_desc.__ctx
 177  * @base: internally used
 178  */
 179 struct shash_alg {
 180         int (*init)(struct shash_desc *desc);
 181         int (*update)(struct shash_desc *desc, const u8 *data,
 182                       unsigned int len);
 183         int (*final)(struct shash_desc *desc, u8 *out);
 184         int (*finup)(struct shash_desc *desc, const u8 *data,
 185                      unsigned int len, u8 *out);
 186         int (*digest)(struct shash_desc *desc, const u8 *data,
 187                       unsigned int len, u8 *out);
 188         int (*export)(struct shash_desc *desc, void *out);
 189         int (*import)(struct shash_desc *desc, const void *in);
 190         int (*setkey)(struct crypto_shash *tfm, const u8 *key,
 191                       unsigned int keylen);
 192
 193         unsigned int descsize;
 194
 195         /* These fields must match hash_alg_common. */
 196         unsigned int digestsize
 197                 __attribute__ ((aligned(__alignof__(struct hash_alg_common))));
 198         unsigned int statesize;
 199
 200         struct crypto_alg base;
 201 };
 202
 203 struct crypto_ahash {
 204         int (*init)(struct ahash_request *req);
 205         int (*update)(struct ahash_request *req);
 206         int (*final)(struct ahash_request *req);
 207         int (*finup)(struct ahash_request *req);
 208         int (*digest)(struct ahash_request *req);
 209         int (*export)(struct ahash_request *req, void *out);
 210         int (*import)(struct ahash_request *req, const void *in);
 211         int (*setkey)(struct crypto_ahash *tfm, const u8 *key,
 212                       unsigned int keylen);
 213
 214         unsigned int reqsize;
 215         struct crypto_tfm base;
 216 };
 217
 218 struct crypto_shash {
 219         unsigned int descsize;
 220         struct crypto_tfm base;
 221 };
 222
 223 /**
 224  * DOC: Asynchronous Message Digest API
 225  *
 226  * The asynchronous message digest API is used with the ciphers of type
 227  * CRYPTO_ALG_TYPE_AHASH (listed as type "ahash" in /proc/crypto)
 228  *
 229  * The asynchronous cipher operation discussion provided for the
 230  * CRYPTO_ALG_TYPE_ABLKCIPHER API applies here as well.
 231  */
 232
 233 static inline struct crypto_ahash *__crypto_ahash_cast(struct crypto_tfm *tfm)
 234 {
 235         return container_of(tfm, struct crypto_ahash, base);
 236 }
 237
 238 /**
 239  * crypto_alloc_ahash() - allocate ahash cipher handle
 240  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
 241  *            ahash cipher
 242  * @type: specifies the type of the cipher
 243  * @mask: specifies the mask for the cipher
 244  *
 245  * Allocate a cipher handle for an ahash. The returned struct
 246  * crypto_ahash is the cipher handle that is required for any subsequent
 247  * API invocation for that ahash.
 248  *
 249  * Return: allocated cipher handle in case of success; IS_ERR() is true in case
 250  *         of an error, PTR_ERR() returns the error code.
 251  */
 252 struct crypto_ahash *crypto_alloc_ahash(const char *alg_name, u32 type,
 253                                         u32 mask);
 254
 255 static inline struct crypto_tfm *crypto_ahash_tfm(struct crypto_ahash *tfm)
 256 {
 257         return &tfm->base;
 258 }
 259
 260 /**
 261  * crypto_free_ahash() - zeroize and free the ahash handle
 262  * @tfm: cipher handle to be freed
 263  */
 264 static inline void crypto_free_ahash(struct crypto_ahash *tfm)
 265 {
 266         crypto_destroy_tfm(tfm, crypto_ahash_tfm(tfm));
 267 }
 268
 269 /**
 270  * crypto_has_ahash() - Search for the availability of an ahash.
 271  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
 272  *            ahash
 273  * @type: specifies the type of the ahash
 274  * @mask: specifies the mask for the ahash
 275  *
 276  * Return: true when the ahash is known to the kernel crypto API; false
 277  *         otherwise
 278  */
 279 int crypto_has_ahash(const char *alg_name, u32 type, u32 mask);
 280
 281 static inline const char *crypto_ahash_alg_name(struct crypto_ahash *tfm)
 282 {
 283         return crypto_tfm_alg_name(crypto_ahash_tfm(tfm));
 284 }
 285
 286 static inline const char *crypto_ahash_driver_name(struct crypto_ahash *tfm)
 287 {
 288         return crypto_tfm_alg_driver_name(crypto_ahash_tfm(tfm));
 289 }
 290
 291 static inline unsigned int crypto_ahash_alignmask(
 292         struct crypto_ahash *tfm)
 293 {
 294         return crypto_tfm_alg_alignmask(crypto_ahash_tfm(tfm));
 295 }
 296
 297 /**
 298  * crypto_ahash_blocksize() - obtain block size for cipher
 299  * @tfm: cipher handle
 300  *
 301  * The block size for the message digest cipher referenced with the cipher
 302  * handle is returned.
 303  *
 304  * Return: block size of cipher
 305  */
 306 static inline unsigned int crypto_ahash_blocksize(struct crypto_ahash *tfm)
 307 {
 308         return crypto_tfm_alg_blocksize(crypto_ahash_tfm(tfm));
 309 }
 310
 311 static inline struct hash_alg_common *__crypto_hash_alg_common(
 312         struct crypto_alg *alg)
 313 {
 314         return container_of(alg, struct hash_alg_common, base);
 315 }
 316
 317 static inline struct hash_alg_common *crypto_hash_alg_common(
 318         struct crypto_ahash *tfm)
 319 {
 320         return __crypto_hash_alg_common(crypto_ahash_tfm(tfm)->__crt_alg);
 321 }
 322
 323 /**
 324  * crypto_ahash_digestsize() - obtain message digest size
 325  * @tfm: cipher handle
 326  *
 327  * The size for the message digest created by the message digest cipher
 328  * referenced with the cipher handle is returned.
 329  *
 330  *
 331  * Return: message digest size of cipher
 332  */
 333 static inline unsigned int crypto_ahash_digestsize(struct crypto_ahash *tfm)
 334 {
 335         return crypto_hash_alg_common(tfm)->digestsize;
 336 }
 337
 338 /**
 339  * crypto_ahash_statesize() - obtain size of the ahash state
 340  * @tfm: cipher handle
 341  *
 342  * Return the size of the ahash state. With the crypto_ahash_export()
 343  * function, the caller can export the state into a buffer whose size is
 344  * defined with this function.
 345  *
 346  * Return: size of the ahash state
 347  */
 348 static inline unsigned int crypto_ahash_statesize(struct crypto_ahash *tfm)
 349 {
 350         return crypto_hash_alg_common(tfm)->statesize;
 351 }
 352
 353 static inline u32 crypto_ahash_get_flags(struct crypto_ahash *tfm)
 354 {
 355         return crypto_tfm_get_flags(crypto_ahash_tfm(tfm));
 356 }
 357
 358 static inline void crypto_ahash_set_flags(struct crypto_ahash *tfm, u32 flags)
 359 {
 360         crypto_tfm_set_flags(crypto_ahash_tfm(tfm), flags);
 361 }
 362
 363 static inline void crypto_ahash_clear_flags(struct crypto_ahash *tfm, u32 flags)
 364 {
 365         crypto_tfm_clear_flags(crypto_ahash_tfm(tfm), flags);
 366 }
 367
 368 /**
 369  * crypto_ahash_reqtfm() - obtain cipher handle from request
 370  * @req: asynchronous request handle that contains the reference to the ahash
 371  *       cipher handle
 372  *
 373  * Return the ahash cipher handle that is registered with the asynchronous
 374  * request handle ahash_request.
 375  *
 376  * Return: ahash cipher handle
 377  */
 378 static inline struct crypto_ahash *crypto_ahash_reqtfm(
 379         struct ahash_request *req)
 380 {
 381         return __crypto_ahash_cast(req->base.tfm);
 382 }
 383
 384 /**
 385  * crypto_ahash_reqsize() - obtain size of the request data structure
 386  * @tfm: cipher handle
 387  *
 388  * Return: size of the request data
 389  */
 390 static inline unsigned int crypto_ahash_reqsize(struct crypto_ahash *tfm)
 391 {
 392         return tfm->reqsize;
 393 }
 394
 395 static inline void *ahash_request_ctx(struct ahash_request *req)
 396 {
 397         return req->__ctx;
 398 }
 399
 400 /**
 401  * crypto_ahash_setkey - set key for cipher handle
 402  * @tfm: cipher handle
 403  * @key: buffer holding the key
 404  * @keylen: length of the key in bytes
 405  *
 406  * The caller provided key is set for the ahash cipher. The cipher
 407  * handle must point to a keyed hash in order for this function to succeed.
 408  *
 409  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
 410  */
 411 int crypto_ahash_setkey(struct crypto_ahash *tfm, const u8 *key,
 412                         unsigned int keylen);
 413
 414 /**
 415  * crypto_ahash_finup() - update and finalize message digest
 416  * @req: reference to the ahash_request handle that holds all information
 417  *       needed to perform the cipher operation
 418  *
 419  * This function is a "short-hand" for the function calls of
 420  * crypto_ahash_update and crypto_ahash_final. The parameters have the same
 421  * meaning as discussed for those separate functions.
 422  *
 423  * Return: see crypto_ahash_final()
 424  */
 425 int crypto_ahash_finup(struct ahash_request *req);
 426
 427 /**
 428  * crypto_ahash_final() - calculate message digest
 429  * @req: reference to the ahash_request handle that holds all information
 430  *       needed to perform the cipher operation
 431  *
 432  * Finalize the message digest operation and create the message digest
 433  * based on all data added to the cipher handle. The message digest is placed
 434  * into the output buffer registered with the ahash_request handle.
 435  *
 436  * Return:
 437  * 0            if the message digest was successfully calculated;
 438  * -EINPROGRESS if data is feeded into hardware (DMA) or queued for later;
 439  * -EBUSY       if queue is full and request should be resubmitted later;
 440  * other < 0    if an error occurred
 441  */
 442 int crypto_ahash_final(struct ahash_request *req);
 443
 444 /**
 445  * crypto_ahash_digest() - calculate message digest for a buffer
 446  * @req: reference to the ahash_request handle that holds all information
 447  *       needed to perform the cipher operation
 448  *
 449  * This function is a "short-hand" for the function calls of crypto_ahash_init,
 450  * crypto_ahash_update and crypto_ahash_final. The parameters have the same
 451  * meaning as discussed for those separate three functions.
 452  *
 453  * Return: see crypto_ahash_final()
 454  */
 455 int crypto_ahash_digest(struct ahash_request *req);
 456
 457 /**
 458  * crypto_ahash_export() - extract current message digest state
 459  * @req: reference to the ahash_request handle whose state is exported
 460  * @out: output buffer of sufficient size that can hold the hash state
 461  *
 462  * This function exports the hash state of the ahash_request handle into the
 463  * caller-allocated output buffer out which must have sufficient size (e.g. by
 464  * calling crypto_ahash_statesize()).
 465  *
 466  * Return: 0 if the export was successful; < 0 if an error occurred
 467  */
 468 static inline int crypto_ahash_export(struct ahash_request *req, void *out)
 469 {
 470         return crypto_ahash_reqtfm(req)->export(req, out);
 471 }
 472
 473 /**
 474  * crypto_ahash_import() - import message digest state
 475  * @req: reference to ahash_request handle the state is imported into
 476  * @in: buffer holding the state
 477  *
 478  * This function imports the hash state into the ahash_request handle from the
 479  * input buffer. That buffer should have been generated with the
 480  * crypto_ahash_export function.
 481  *
 482  * Return: 0 if the import was successful; < 0 if an error occurred
 483  */
 484 static inline int crypto_ahash_import(struct ahash_request *req, const void *in)
 485 {
 486         struct crypto_ahash *tfm = crypto_ahash_reqtfm(req);
 487
 488         if (crypto_ahash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY)
 489                 return -ENOKEY;
 490
 491         return tfm->import(req, in);
 492 }
 493
 494 /**
 495  * crypto_ahash_init() - (re)initialize message digest handle
 496  * @req: ahash_request handle that already is initialized with all necessary
 497  *       data using the ahash_request_* API functions
 498  *
 499  * The call (re-)initializes the message digest referenced by the ahash_request
 500  * handle. Any potentially existing state created by previous operations is
 501  * discarded.
 502  *
 503  * Return: see crypto_ahash_final()
 504  */
 505 static inline int crypto_ahash_init(struct ahash_request *req)
 506 {
 507         struct crypto_ahash *tfm = crypto_ahash_reqtfm(req);
 508
 509         if (crypto_ahash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY)
 510                 return -ENOKEY;
 511
 512         return tfm->init(req);
 513 }
 514
 515 /**
 516  * crypto_ahash_update() - add data to message digest for processing
 517  * @req: ahash_request handle that was previously initialized with the
 518  *       crypto_ahash_init call.
 519  *
 520  * Updates the message digest state of the &ahash_request handle. The input data
 521  * is pointed to by the scatter/gather list registered in the &ahash_request
 522  * handle
 523  *
 524  * Return: see crypto_ahash_final()
 525  */
 526 static inline int crypto_ahash_update(struct ahash_request *req)
 527 {
 528         struct crypto_ahash *tfm = crypto_ahash_reqtfm(req);
 529         struct crypto_alg *alg = tfm->base.__crt_alg;
 530         unsigned int nbytes = req->nbytes;
 531         int ret;
 532
 533         crypto_stats_get(alg);
 534         ret = crypto_ahash_reqtfm(req)->update(req);
 535         crypto_stats_ahash_update(nbytes, ret, alg);
 536         return ret;
 537 }
 538
 539 /**
 540  * DOC: Asynchronous Hash Request Handle
 541  *
 542  * The &ahash_request data structure contains all pointers to data
 543  * required for the asynchronous cipher operation. This includes the cipher
 544  * handle (which can be used by multiple &ahash_request instances), pointer
 545  * to plaintext and the message digest output buffer, asynchronous callback
 546  * function, etc. It acts as a handle to the ahash_request_* API calls in a
 547  * similar way as ahash handle to the crypto_ahash_* API calls.
 548  */
 549
 550 /**
 551  * ahash_request_set_tfm() - update cipher handle reference in request
 552  * @req: request handle to be modified
 553  * @tfm: cipher handle that shall be added to the request handle
 554  *
 555  * Allow the caller to replace the existing ahash handle in the request
 556  * data structure with a different one.
 557  */
 558 static inline void ahash_request_set_tfm(struct ahash_request *req,
 559                                          struct crypto_ahash *tfm)
 560 {
 561         req->base.tfm = crypto_ahash_tfm(tfm);
 562 }
 563
 564 /**
 565  * ahash_request_alloc() - allocate request data structure
 566  * @tfm: cipher handle to be registered with the request
 567  * @gfp: memory allocation flag that is handed to kmalloc by the API call.
 568  *
 569  * Allocate the request data structure that must be used with the ahash
 570  * message digest API calls. During
 571  * the allocation, the provided ahash handle
 572  * is registered in the request data structure.
 573  *
 574  * Return: allocated request handle in case of success, or NULL if out of memory
 575  */
 576 static inline struct ahash_request *ahash_request_alloc(
 577         struct crypto_ahash *tfm, gfp_t gfp)
 578 {
 579         struct ahash_request *req;
 580
 581         req = kmalloc(sizeof(struct ahash_request) +
 582                       crypto_ahash_reqsize(tfm), gfp);
 583
 584         if (likely(req))
 585                 ahash_request_set_tfm(req, tfm);
 586
 587         return req;
 588 }
 589
 590 /**
 591  * ahash_request_free() - zeroize and free the request data structure
 592  * @req: request data structure cipher handle to be freed
 593  */
 594 static inline void ahash_request_free(struct ahash_request *req)
 595 {
 596         kzfree(req);
 597 }
 598
 599 static inline void ahash_request_zero(struct ahash_request *req)
 600 {
 601         memzero_explicit(req, sizeof(*req) +
 602                               crypto_ahash_reqsize(crypto_ahash_reqtfm(req)));
 603 }
 604
 605 static inline struct ahash_request *ahash_request_cast(
 606         struct crypto_async_request *req)
 607 {
 608         return container_of(req, struct ahash_request, base);
 609 }
 610
 611 /**
 612  * ahash_request_set_callback() - set asynchronous callback function
 613  * @req: request handle
 614  * @flags: specify zero or an ORing of the flags
 615  *         CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
 616  *         increase the wait queue beyond the initial maximum size;
 617  *         CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
 618  * @compl: callback function pointer to be registered with the request handle
 619  * @data: The data pointer refers to memory that is not used by the kernel
 620  *        crypto API, but provided to the callback function for it to use. Here,
 621  *        the caller can provide a reference to memory the callback function can
 622  *        operate on. As the callback function is invoked asynchronously to the
 623  *        related functionality, it may need to access data structures of the
 624  *        related functionality which can be referenced using this pointer. The
 625  *        callback function can access the memory via the "data" field in the
 626  *        &crypto_async_request data structure provided to the callback function.
 627  *
 628  * This function allows setting the callback function that is triggered once
 629  * the cipher operation completes.
 630  *
 631  * The callback function is registered with the &ahash_request handle and
 632  * must comply with the following template::
 633  *
 634  *      void callback_function(struct crypto_async_request *req, int error)
 635  */
 636 static inline void ahash_request_set_callback(struct ahash_request *req,
 637                                               u32 flags,
 638                                               crypto_completion_t compl,
 639                                               void *data)
 640 {
 641         req->base.complete = compl;
 642         req->base.data = data;
 643         req->base.flags = flags;
 644 }
 645
 646 /**
 647  * ahash_request_set_crypt() - set data buffers
 648  * @req: ahash_request handle to be updated
 649  * @src: source scatter/gather list
 650  * @result: buffer that is filled with the message digest -- the caller must
 651  *          ensure that the buffer has sufficient space by, for example, calling
 652  *          crypto_ahash_digestsize()
 653  * @nbytes: number of bytes to process from the source scatter/gather list
 654  *
 655  * By using this call, the caller references the source scatter/gather list.
 656  * The source scatter/gather list points to the data the message digest is to
 657  * be calculated for.
 658  */
 659 static inline void ahash_request_set_crypt(struct ahash_request *req,
 660                                            struct scatterlist *src, u8 *result,
 661                                            unsigned int nbytes)
 662 {
 663         req->src = src;
 664         req->nbytes = nbytes;
 665         req->result = result;
 666 }
 667
 668 /**
 669  * DOC: Synchronous Message Digest API
 670  *
 671  * The synchronous message digest API is used with the ciphers of type
 672  * CRYPTO_ALG_TYPE_SHASH (listed as type "shash" in /proc/crypto)
 673  *
 674  * The message digest API is able to maintain state information for the
 675  * caller.
 676  *
 677  * The synchronous message digest API can store user-related context in in its
 678  * shash_desc request data structure.
 679  */
 680
 681 /**
 682  * crypto_alloc_shash() - allocate message digest handle
 683  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
 684  *            message digest cipher
 685  * @type: specifies the type of the cipher
 686  * @mask: specifies the mask for the cipher
 687  *
 688  * Allocate a cipher handle for a message digest. The returned &struct
 689  * crypto_shash is the cipher handle that is required for any subsequent
 690  * API invocation for that message digest.
 691  *
 692  * Return: allocated cipher handle in case of success; IS_ERR() is true in case
 693  *         of an error, PTR_ERR() returns the error code.
 694  */
 695 struct crypto_shash *crypto_alloc_shash(const char *alg_name, u32 type,
 696                                         u32 mask);
 697
 698 static inline struct crypto_tfm *crypto_shash_tfm(struct crypto_shash *tfm)
 699 {
 700         return &tfm->base;
 701 }
 702
 703 /**
 704  * crypto_free_shash() - zeroize and free the message digest handle
 705  * @tfm: cipher handle to be freed
 706  */
 707 static inline void crypto_free_shash(struct crypto_shash *tfm)
 708 {
 709         crypto_destroy_tfm(tfm, crypto_shash_tfm(tfm));
 710 }
 711
 712 static inline const char *crypto_shash_alg_name(struct crypto_shash *tfm)
 713 {
 714         return crypto_tfm_alg_name(crypto_shash_tfm(tfm));
 715 }
 716
 717 static inline const char *crypto_shash_driver_name(struct crypto_shash *tfm)
 718 {
 719         return crypto_tfm_alg_driver_name(crypto_shash_tfm(tfm));
 720 }
 721
 722 static inline unsigned int crypto_shash_alignmask(
 723         struct crypto_shash *tfm)
 724 {
 725         return crypto_tfm_alg_alignmask(crypto_shash_tfm(tfm));
 726 }
 727
 728 /**
 729  * crypto_shash_blocksize() - obtain block size for cipher
 730  * @tfm: cipher handle
 731  *
 732  * The block size for the message digest cipher referenced with the cipher
 733  * handle is returned.
 734  *
 735  * Return: block size of cipher
 736  */
 737 static inline unsigned int crypto_shash_blocksize(struct crypto_shash *tfm)
 738 {
 739         return crypto_tfm_alg_blocksize(crypto_shash_tfm(tfm));
 740 }
 741
 742 static inline struct shash_alg *__crypto_shash_alg(struct crypto_alg *alg)
 743 {
 744         return container_of(alg, struct shash_alg, base);
 745 }
 746
 747 static inline struct shash_alg *crypto_shash_alg(struct crypto_shash *tfm)
 748 {
 749         return __crypto_shash_alg(crypto_shash_tfm(tfm)->__crt_alg);
 750 }
 751
 752 /**
 753  * crypto_shash_digestsize() - obtain message digest size
 754  * @tfm: cipher handle
 755  *
 756  * The size for the message digest created by the message digest cipher
 757  * referenced with the cipher handle is returned.
 758  *
 759  * Return: digest size of cipher
 760  */
 761 static inline unsigned int crypto_shash_digestsize(struct crypto_shash *tfm)
 762 {
 763         return crypto_shash_alg(tfm)->digestsize;
 764 }
 765
 766 static inline unsigned int crypto_shash_statesize(struct crypto_shash *tfm)
 767 {
 768         return crypto_shash_alg(tfm)->statesize;
 769 }
 770
 771 static inline u32 crypto_shash_get_flags(struct crypto_shash *tfm)
 772 {
 773         return crypto_tfm_get_flags(crypto_shash_tfm(tfm));
 774 }
 775
 776 static inline void crypto_shash_set_flags(struct crypto_shash *tfm, u32 flags)
 777 {
 778         crypto_tfm_set_flags(crypto_shash_tfm(tfm), flags);
 779 }
 780
 781 static inline void crypto_shash_clear_flags(struct crypto_shash *tfm, u32 flags)
 782 {
 783         crypto_tfm_clear_flags(crypto_shash_tfm(tfm), flags);
 784 }
 785
 786 /**
 787  * crypto_shash_descsize() - obtain the operational state size
 788  * @tfm: cipher handle
 789  *
 790  * The size of the operational state the cipher needs during operation is
 791  * returned for the hash referenced with the cipher handle. This size is
 792  * required to calculate the memory requirements to allow the caller allocating
 793  * sufficient memory for operational state.
 794  *
 795  * The operational state is defined with struct shash_desc where the size of
 796  * that data structure is to be calculated as
 797  * sizeof(struct shash_desc) + crypto_shash_descsize(alg)
 798  *
 799  * Return: size of the operational state
 800  */
 801 static inline unsigned int crypto_shash_descsize(struct crypto_shash *tfm)
 802 {
 803         return tfm->descsize;
 804 }
 805
 806 static inline void *shash_desc_ctx(struct shash_desc *desc)
 807 {
 808         return desc->__ctx;
 809 }
 810
 811 /**
 812  * crypto_shash_setkey() - set key for message digest
 813  * @tfm: cipher handle
 814  * @key: buffer holding the key
 815  * @keylen: length of the key in bytes
 816  *
 817  * The caller provided key is set for the keyed message digest cipher. The
 818  * cipher handle must point to a keyed message digest cipher in order for this
 819  * function to succeed.
 820  *
 821  * Context: Any context.
 822  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
 823  */
 824 int crypto_shash_setkey(struct crypto_shash *tfm, const u8 *key,
 825                         unsigned int keylen);
 826
 827 /**
 828  * crypto_shash_digest() - calculate message digest for buffer
 829  * @desc: see crypto_shash_final()
 830  * @data: see crypto_shash_update()
 831  * @len: see crypto_shash_update()
 832  * @out: see crypto_shash_final()
 833  *
 834  * This function is a "short-hand" for the function calls of crypto_shash_init,
 835  * crypto_shash_update and crypto_shash_final. The parameters have the same
 836  * meaning as discussed for those separate three functions.
 837  *
 838  * Context: Any context.
 839  * Return: 0 if the message digest creation was successful; < 0 if an error
 840  *         occurred
 841  */
 842 int crypto_shash_digest(struct shash_desc *desc, const u8 *data,
 843                         unsigned int len, u8 *out);
 844
 845 /**
 846  * crypto_shash_export() - extract operational state for message digest
 847  * @desc: reference to the operational state handle whose state is exported
 848  * @out: output buffer of sufficient size that can hold the hash state
 849  *
 850  * This function exports the hash state of the operational state handle into the
 851  * caller-allocated output buffer out which must have sufficient size (e.g. by
 852  * calling crypto_shash_descsize).
 853  *
 854  * Context: Any context.
 855  * Return: 0 if the export creation was successful; < 0 if an error occurred
 856  */
 857 static inline int crypto_shash_export(struct shash_desc *desc, void *out)
 858 {
 859         return crypto_shash_alg(desc->tfm)->export(desc, out);
 860 }
 861
 862 /**
 863  * crypto_shash_import() - import operational state
 864  * @desc: reference to the operational state handle the state imported into
 865  * @in: buffer holding the state
 866  *
 867  * This function imports the hash state into the operational state handle from
 868  * the input buffer. That buffer should have been generated with the
 869  * crypto_ahash_export function.
 870  *
 871  * Context: Any context.
 872  * Return: 0 if the import was successful; < 0 if an error occurred
 873  */
 874 static inline int crypto_shash_import(struct shash_desc *desc, const void *in)
 875 {
 876         struct crypto_shash *tfm = desc->tfm;
 877
 878         if (crypto_shash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY)
 879                 return -ENOKEY;
 880
 881         return crypto_shash_alg(tfm)->import(desc, in);
 882 }
 883
 884 /**
 885  * crypto_shash_init() - (re)initialize message digest
 886  * @desc: operational state handle that is already filled
 887  *
 888  * The call (re-)initializes the message digest referenced by the
 889  * operational state handle. Any potentially existing state created by
 890  * previous operations is discarded.
 891  *
 892  * Context: Any context.
 893  * Return: 0 if the message digest initialization was successful; < 0 if an
 894  *         error occurred
 895  */
 896 static inline int crypto_shash_init(struct shash_desc *desc)
 897 {
 898         struct crypto_shash *tfm = desc->tfm;
 899
 900         if (crypto_shash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY)
 901                 return -ENOKEY;
 902
 903         return crypto_shash_alg(tfm)->init(desc);
 904 }
 905
 906 /**
 907  * crypto_shash_update() - add data to message digest for processing
 908  * @desc: operational state handle that is already initialized
 909  * @data: input data to be added to the message digest
 910  * @len: length of the input data
 911  *
 912  * Updates the message digest state of the operational state handle.
 913  *
 914  * Context: Any context.
 915  * Return: 0 if the message digest update was successful; < 0 if an error
 916  *         occurred
 917  */
 918 int crypto_shash_update(struct shash_desc *desc, const u8 *data,
 919                         unsigned int len);
 920
 921 /**
 922  * crypto_shash_final() - calculate message digest
 923  * @desc: operational state handle that is already filled with data
 924  * @out: output buffer filled with the message digest
 925  *
 926  * Finalize the message digest operation and create the message digest
 927  * based on all data added to the cipher handle. The message digest is placed
 928  * into the output buffer. The caller must ensure that the output buffer is
 929  * large enough by using crypto_shash_digestsize.
 930  *
 931  * Context: Any context.
 932  * Return: 0 if the message digest creation was successful; < 0 if an error
 933  *         occurred
 934  */
 935 int crypto_shash_final(struct shash_desc *desc, u8 *out);
 936
 937 /**
 938  * crypto_shash_finup() - calculate message digest of buffer
 939  * @desc: see crypto_shash_final()
 940  * @data: see crypto_shash_update()
 941  * @len: see crypto_shash_update()
 942  * @out: see crypto_shash_final()
 943  *
 944  * This function is a "short-hand" for the function calls of
 945  * crypto_shash_update and crypto_shash_final. The parameters have the same
 946  * meaning as discussed for those separate functions.
 947  *
 948  * Context: Any context.
 949  * Return: 0 if the message digest creation was successful; < 0 if an error
 950  *         occurred
 951  */
 952 int crypto_shash_finup(struct shash_desc *desc, const u8 *data,
 953                        unsigned int len, u8 *out);
 954
 955 static inline void shash_desc_zero(struct shash_desc *desc)
 956 {
 957         memzero_explicit(desc,
 958                          sizeof(*desc) + crypto_shash_descsize(desc->tfm));
 959 }
 960
 961 #endif  /* _CRYPTO_HASH_H */