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