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 * If @tfm is a NULL or error pointer, this function does nothing. 286 */ 287 static inline void crypto_free_ahash(struct crypto_ahash *tfm) 288 { 289 crypto_destroy_tfm(tfm, crypto_ahash_tfm(tfm)); 290 } 291 292 /** 293 * crypto_has_ahash() - Search for the availability of an ahash. 294 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the 295 * ahash 296 * @type: specifies the type of the ahash 297 * @mask: specifies the mask for the ahash 298 * 299 * Return: true when the ahash is known to the kernel crypto API; false 300 * otherwise 301 */ 302 int crypto_has_ahash(const char *alg_name, u32 type, u32 mask); 303 304 static inline const char *crypto_ahash_alg_name(struct crypto_ahash *tfm) 305 { 306 return crypto_tfm_alg_name(crypto_ahash_tfm(tfm)); 307 } 308 309 static inline const char *crypto_ahash_driver_name(struct crypto_ahash *tfm) 310 { 311 return crypto_tfm_alg_driver_name(crypto_ahash_tfm(tfm)); 312 } 313 314 static inline unsigned int crypto_ahash_alignmask( 315 struct crypto_ahash *tfm) 316 { 317 return crypto_tfm_alg_alignmask(crypto_ahash_tfm(tfm)); 318 } 319 320 /** 321 * crypto_ahash_blocksize() - obtain block size for cipher 322 * @tfm: cipher handle 323 * 324 * The block size for the message digest cipher referenced with the cipher 325 * handle is returned. 326 * 327 * Return: block size of cipher 328 */ 329 static inline unsigned int crypto_ahash_blocksize(struct crypto_ahash *tfm) 330 { 331 return crypto_tfm_alg_blocksize(crypto_ahash_tfm(tfm)); 332 } 333 334 static inline struct hash_alg_common *__crypto_hash_alg_common( 335 struct crypto_alg *alg) 336 { 337 return container_of(alg, struct hash_alg_common, base); 338 } 339 340 static inline struct hash_alg_common *crypto_hash_alg_common( 341 struct crypto_ahash *tfm) 342 { 343 return __crypto_hash_alg_common(crypto_ahash_tfm(tfm)->__crt_alg); 344 } 345 346 /** 347 * crypto_ahash_digestsize() - obtain message digest size 348 * @tfm: cipher handle 349 * 350 * The size for the message digest created by the message digest cipher 351 * referenced with the cipher handle is returned. 352 * 353 * 354 * Return: message digest size of cipher 355 */ 356 static inline unsigned int crypto_ahash_digestsize(struct crypto_ahash *tfm) 357 { 358 return crypto_hash_alg_common(tfm)->digestsize; 359 } 360 361 /** 362 * crypto_ahash_statesize() - obtain size of the ahash state 363 * @tfm: cipher handle 364 * 365 * Return the size of the ahash state. With the crypto_ahash_export() 366 * function, the caller can export the state into a buffer whose size is 367 * defined with this function. 368 * 369 * Return: size of the ahash state 370 */ 371 static inline unsigned int crypto_ahash_statesize(struct crypto_ahash *tfm) 372 { 373 return crypto_hash_alg_common(tfm)->statesize; 374 } 375 376 static inline u32 crypto_ahash_get_flags(struct crypto_ahash *tfm) 377 { 378 return crypto_tfm_get_flags(crypto_ahash_tfm(tfm)); 379 } 380 381 static inline void crypto_ahash_set_flags(struct crypto_ahash *tfm, u32 flags) 382 { 383 crypto_tfm_set_flags(crypto_ahash_tfm(tfm), flags); 384 } 385 386 static inline void crypto_ahash_clear_flags(struct crypto_ahash *tfm, u32 flags) 387 { 388 crypto_tfm_clear_flags(crypto_ahash_tfm(tfm), flags); 389 } 390 391 /** 392 * crypto_ahash_reqtfm() - obtain cipher handle from request 393 * @req: asynchronous request handle that contains the reference to the ahash 394 * cipher handle 395 * 396 * Return the ahash cipher handle that is registered with the asynchronous 397 * request handle ahash_request. 398 * 399 * Return: ahash cipher handle 400 */ 401 static inline struct crypto_ahash *crypto_ahash_reqtfm( 402 struct ahash_request *req) 403 { 404 return __crypto_ahash_cast(req->base.tfm); 405 } 406 407 /** 408 * crypto_ahash_reqsize() - obtain size of the request data structure 409 * @tfm: cipher handle 410 * 411 * Return: size of the request data 412 */ 413 static inline unsigned int crypto_ahash_reqsize(struct crypto_ahash *tfm) 414 { 415 return tfm->reqsize; 416 } 417 418 static inline void *ahash_request_ctx(struct ahash_request *req) 419 { 420 return req->__ctx; 421 } 422 423 /** 424 * crypto_ahash_setkey - set key for cipher handle 425 * @tfm: cipher handle 426 * @key: buffer holding the key 427 * @keylen: length of the key in bytes 428 * 429 * The caller provided key is set for the ahash cipher. The cipher 430 * handle must point to a keyed hash in order for this function to succeed. 431 * 432 * Return: 0 if the setting of the key was successful; < 0 if an error occurred 433 */ 434 int crypto_ahash_setkey(struct crypto_ahash *tfm, const u8 *key, 435 unsigned int keylen); 436 437 /** 438 * crypto_ahash_finup() - update and finalize message digest 439 * @req: reference to the ahash_request handle that holds all information 440 * needed to perform the cipher operation 441 * 442 * This function is a "short-hand" for the function calls of 443 * crypto_ahash_update and crypto_ahash_final. The parameters have the same 444 * meaning as discussed for those separate functions. 445 * 446 * Return: see crypto_ahash_final() 447 */ 448 int crypto_ahash_finup(struct ahash_request *req); 449 450 /** 451 * crypto_ahash_final() - calculate message digest 452 * @req: reference to the ahash_request handle that holds all information 453 * needed to perform the cipher operation 454 * 455 * Finalize the message digest operation and create the message digest 456 * based on all data added to the cipher handle. The message digest is placed 457 * into the output buffer registered with the ahash_request handle. 458 * 459 * Return: 460 * 0 if the message digest was successfully calculated; 461 * -EINPROGRESS if data is fed into hardware (DMA) or queued for later; 462 * -EBUSY if queue is full and request should be resubmitted later; 463 * other < 0 if an error occurred 464 */ 465 int crypto_ahash_final(struct ahash_request *req); 466 467 /** 468 * crypto_ahash_digest() - calculate message digest for a buffer 469 * @req: reference to the ahash_request handle that holds all information 470 * needed to perform the cipher operation 471 * 472 * This function is a "short-hand" for the function calls of crypto_ahash_init, 473 * crypto_ahash_update and crypto_ahash_final. The parameters have the same 474 * meaning as discussed for those separate three functions. 475 * 476 * Return: see crypto_ahash_final() 477 */ 478 int crypto_ahash_digest(struct ahash_request *req); 479 480 /** 481 * crypto_ahash_export() - extract current message digest state 482 * @req: reference to the ahash_request handle whose state is exported 483 * @out: output buffer of sufficient size that can hold the hash state 484 * 485 * This function exports the hash state of the ahash_request handle into the 486 * caller-allocated output buffer out which must have sufficient size (e.g. by 487 * calling crypto_ahash_statesize()). 488 * 489 * Return: 0 if the export was successful; < 0 if an error occurred 490 */ 491 static inline int crypto_ahash_export(struct ahash_request *req, void *out) 492 { 493 return crypto_ahash_reqtfm(req)->export(req, out); 494 } 495 496 /** 497 * crypto_ahash_import() - import message digest state 498 * @req: reference to ahash_request handle the state is imported into 499 * @in: buffer holding the state 500 * 501 * This function imports the hash state into the ahash_request handle from the 502 * input buffer. That buffer should have been generated with the 503 * crypto_ahash_export function. 504 * 505 * Return: 0 if the import was successful; < 0 if an error occurred 506 */ 507 static inline int crypto_ahash_import(struct ahash_request *req, const void *in) 508 { 509 struct crypto_ahash *tfm = crypto_ahash_reqtfm(req); 510 511 if (crypto_ahash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY) 512 return -ENOKEY; 513 514 return tfm->import(req, in); 515 } 516 517 /** 518 * crypto_ahash_init() - (re)initialize message digest handle 519 * @req: ahash_request handle that already is initialized with all necessary 520 * data using the ahash_request_* API functions 521 * 522 * The call (re-)initializes the message digest referenced by the ahash_request 523 * handle. Any potentially existing state created by previous operations is 524 * discarded. 525 * 526 * Return: see crypto_ahash_final() 527 */ 528 static inline int crypto_ahash_init(struct ahash_request *req) 529 { 530 struct crypto_ahash *tfm = crypto_ahash_reqtfm(req); 531 532 if (crypto_ahash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY) 533 return -ENOKEY; 534 535 return tfm->init(req); 536 } 537 538 /** 539 * crypto_ahash_update() - add data to message digest for processing 540 * @req: ahash_request handle that was previously initialized with the 541 * crypto_ahash_init call. 542 * 543 * Updates the message digest state of the &ahash_request handle. The input data 544 * is pointed to by the scatter/gather list registered in the &ahash_request 545 * handle 546 * 547 * Return: see crypto_ahash_final() 548 */ 549 static inline int crypto_ahash_update(struct ahash_request *req) 550 { 551 struct crypto_ahash *tfm = crypto_ahash_reqtfm(req); 552 struct crypto_alg *alg = tfm->base.__crt_alg; 553 unsigned int nbytes = req->nbytes; 554 int ret; 555 556 crypto_stats_get(alg); 557 ret = crypto_ahash_reqtfm(req)->update(req); 558 crypto_stats_ahash_update(nbytes, ret, alg); 559 return ret; 560 } 561 562 /** 563 * DOC: Asynchronous Hash Request Handle 564 * 565 * The &ahash_request data structure contains all pointers to data 566 * required for the asynchronous cipher operation. This includes the cipher 567 * handle (which can be used by multiple &ahash_request instances), pointer 568 * to plaintext and the message digest output buffer, asynchronous callback 569 * function, etc. It acts as a handle to the ahash_request_* API calls in a 570 * similar way as ahash handle to the crypto_ahash_* API calls. 571 */ 572 573 /** 574 * ahash_request_set_tfm() - update cipher handle reference in request 575 * @req: request handle to be modified 576 * @tfm: cipher handle that shall be added to the request handle 577 * 578 * Allow the caller to replace the existing ahash handle in the request 579 * data structure with a different one. 580 */ 581 static inline void ahash_request_set_tfm(struct ahash_request *req, 582 struct crypto_ahash *tfm) 583 { 584 req->base.tfm = crypto_ahash_tfm(tfm); 585 } 586 587 /** 588 * ahash_request_alloc() - allocate request data structure 589 * @tfm: cipher handle to be registered with the request 590 * @gfp: memory allocation flag that is handed to kmalloc by the API call. 591 * 592 * Allocate the request data structure that must be used with the ahash 593 * message digest API calls. During 594 * the allocation, the provided ahash handle 595 * is registered in the request data structure. 596 * 597 * Return: allocated request handle in case of success, or NULL if out of memory 598 */ 599 static inline struct ahash_request *ahash_request_alloc( 600 struct crypto_ahash *tfm, gfp_t gfp) 601 { 602 struct ahash_request *req; 603 604 req = kmalloc(sizeof(struct ahash_request) + 605 crypto_ahash_reqsize(tfm), gfp); 606 607 if (likely(req)) 608 ahash_request_set_tfm(req, tfm); 609 610 return req; 611 } 612 613 /** 614 * ahash_request_free() - zeroize and free the request data structure 615 * @req: request data structure cipher handle to be freed 616 */ 617 static inline void ahash_request_free(struct ahash_request *req) 618 { 619 kfree_sensitive(req); 620 } 621 622 static inline void ahash_request_zero(struct ahash_request *req) 623 { 624 memzero_explicit(req, sizeof(*req) + 625 crypto_ahash_reqsize(crypto_ahash_reqtfm(req))); 626 } 627 628 static inline struct ahash_request *ahash_request_cast( 629 struct crypto_async_request *req) 630 { 631 return container_of(req, struct ahash_request, base); 632 } 633 634 /** 635 * ahash_request_set_callback() - set asynchronous callback function 636 * @req: request handle 637 * @flags: specify zero or an ORing of the flags 638 * CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and 639 * increase the wait queue beyond the initial maximum size; 640 * CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep 641 * @compl: callback function pointer to be registered with the request handle 642 * @data: The data pointer refers to memory that is not used by the kernel 643 * crypto API, but provided to the callback function for it to use. Here, 644 * the caller can provide a reference to memory the callback function can 645 * operate on. As the callback function is invoked asynchronously to the 646 * related functionality, it may need to access data structures of the 647 * related functionality which can be referenced using this pointer. The 648 * callback function can access the memory via the "data" field in the 649 * &crypto_async_request data structure provided to the callback function. 650 * 651 * This function allows setting the callback function that is triggered once 652 * the cipher operation completes. 653 * 654 * The callback function is registered with the &ahash_request handle and 655 * must comply with the following template:: 656 * 657 * void callback_function(struct crypto_async_request *req, int error) 658 */ 659 static inline void ahash_request_set_callback(struct ahash_request *req, 660 u32 flags, 661 crypto_completion_t compl, 662 void *data) 663 { 664 req->base.complete = compl; 665 req->base.data = data; 666 req->base.flags = flags; 667 } 668 669 /** 670 * ahash_request_set_crypt() - set data buffers 671 * @req: ahash_request handle to be updated 672 * @src: source scatter/gather list 673 * @result: buffer that is filled with the message digest -- the caller must 674 * ensure that the buffer has sufficient space by, for example, calling 675 * crypto_ahash_digestsize() 676 * @nbytes: number of bytes to process from the source scatter/gather list 677 * 678 * By using this call, the caller references the source scatter/gather list. 679 * The source scatter/gather list points to the data the message digest is to 680 * be calculated for. 681 */ 682 static inline void ahash_request_set_crypt(struct ahash_request *req, 683 struct scatterlist *src, u8 *result, 684 unsigned int nbytes) 685 { 686 req->src = src; 687 req->nbytes = nbytes; 688 req->result = result; 689 } 690 691 /** 692 * DOC: Synchronous Message Digest API 693 * 694 * The synchronous message digest API is used with the ciphers of type 695 * CRYPTO_ALG_TYPE_SHASH (listed as type "shash" in /proc/crypto) 696 * 697 * The message digest API is able to maintain state information for the 698 * caller. 699 * 700 * The synchronous message digest API can store user-related context in its 701 * shash_desc request data structure. 702 */ 703 704 /** 705 * crypto_alloc_shash() - allocate message digest handle 706 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the 707 * message digest cipher 708 * @type: specifies the type of the cipher 709 * @mask: specifies the mask for the cipher 710 * 711 * Allocate a cipher handle for a message digest. The returned &struct 712 * crypto_shash is the cipher handle that is required for any subsequent 713 * API invocation for that message digest. 714 * 715 * Return: allocated cipher handle in case of success; IS_ERR() is true in case 716 * of an error, PTR_ERR() returns the error code. 717 */ 718 struct crypto_shash *crypto_alloc_shash(const char *alg_name, u32 type, 719 u32 mask); 720 721 static inline struct crypto_tfm *crypto_shash_tfm(struct crypto_shash *tfm) 722 { 723 return &tfm->base; 724 } 725 726 /** 727 * crypto_free_shash() - zeroize and free the message digest handle 728 * @tfm: cipher handle to be freed 729 * 730 * If @tfm is a NULL or error pointer, this function does nothing. 731 */ 732 static inline void crypto_free_shash(struct crypto_shash *tfm) 733 { 734 crypto_destroy_tfm(tfm, crypto_shash_tfm(tfm)); 735 } 736 737 static inline const char *crypto_shash_alg_name(struct crypto_shash *tfm) 738 { 739 return crypto_tfm_alg_name(crypto_shash_tfm(tfm)); 740 } 741 742 static inline const char *crypto_shash_driver_name(struct crypto_shash *tfm) 743 { 744 return crypto_tfm_alg_driver_name(crypto_shash_tfm(tfm)); 745 } 746 747 static inline unsigned int crypto_shash_alignmask( 748 struct crypto_shash *tfm) 749 { 750 return crypto_tfm_alg_alignmask(crypto_shash_tfm(tfm)); 751 } 752 753 /** 754 * crypto_shash_blocksize() - obtain block size for cipher 755 * @tfm: cipher handle 756 * 757 * The block size for the message digest cipher referenced with the cipher 758 * handle is returned. 759 * 760 * Return: block size of cipher 761 */ 762 static inline unsigned int crypto_shash_blocksize(struct crypto_shash *tfm) 763 { 764 return crypto_tfm_alg_blocksize(crypto_shash_tfm(tfm)); 765 } 766 767 static inline struct shash_alg *__crypto_shash_alg(struct crypto_alg *alg) 768 { 769 return container_of(alg, struct shash_alg, base); 770 } 771 772 static inline struct shash_alg *crypto_shash_alg(struct crypto_shash *tfm) 773 { 774 return __crypto_shash_alg(crypto_shash_tfm(tfm)->__crt_alg); 775 } 776 777 /** 778 * crypto_shash_digestsize() - obtain message digest size 779 * @tfm: cipher handle 780 * 781 * The size for the message digest created by the message digest cipher 782 * referenced with the cipher handle is returned. 783 * 784 * Return: digest size of cipher 785 */ 786 static inline unsigned int crypto_shash_digestsize(struct crypto_shash *tfm) 787 { 788 return crypto_shash_alg(tfm)->digestsize; 789 } 790 791 static inline unsigned int crypto_shash_statesize(struct crypto_shash *tfm) 792 { 793 return crypto_shash_alg(tfm)->statesize; 794 } 795 796 static inline u32 crypto_shash_get_flags(struct crypto_shash *tfm) 797 { 798 return crypto_tfm_get_flags(crypto_shash_tfm(tfm)); 799 } 800 801 static inline void crypto_shash_set_flags(struct crypto_shash *tfm, u32 flags) 802 { 803 crypto_tfm_set_flags(crypto_shash_tfm(tfm), flags); 804 } 805 806 static inline void crypto_shash_clear_flags(struct crypto_shash *tfm, u32 flags) 807 { 808 crypto_tfm_clear_flags(crypto_shash_tfm(tfm), flags); 809 } 810 811 /** 812 * crypto_shash_descsize() - obtain the operational state size 813 * @tfm: cipher handle 814 * 815 * The size of the operational state the cipher needs during operation is 816 * returned for the hash referenced with the cipher handle. This size is 817 * required to calculate the memory requirements to allow the caller allocating 818 * sufficient memory for operational state. 819 * 820 * The operational state is defined with struct shash_desc where the size of 821 * that data structure is to be calculated as 822 * sizeof(struct shash_desc) + crypto_shash_descsize(alg) 823 * 824 * Return: size of the operational state 825 */ 826 static inline unsigned int crypto_shash_descsize(struct crypto_shash *tfm) 827 { 828 return tfm->descsize; 829 } 830 831 static inline void *shash_desc_ctx(struct shash_desc *desc) 832 { 833 return desc->__ctx; 834 } 835 836 /** 837 * crypto_shash_setkey() - set key for message digest 838 * @tfm: cipher handle 839 * @key: buffer holding the key 840 * @keylen: length of the key in bytes 841 * 842 * The caller provided key is set for the keyed message digest cipher. The 843 * cipher handle must point to a keyed message digest cipher in order for this 844 * function to succeed. 845 * 846 * Context: Any context. 847 * Return: 0 if the setting of the key was successful; < 0 if an error occurred 848 */ 849 int crypto_shash_setkey(struct crypto_shash *tfm, const u8 *key, 850 unsigned int keylen); 851 852 /** 853 * crypto_shash_digest() - calculate message digest for buffer 854 * @desc: see crypto_shash_final() 855 * @data: see crypto_shash_update() 856 * @len: see crypto_shash_update() 857 * @out: see crypto_shash_final() 858 * 859 * This function is a "short-hand" for the function calls of crypto_shash_init, 860 * crypto_shash_update and crypto_shash_final. The parameters have the same 861 * meaning as discussed for those separate three functions. 862 * 863 * Context: Any context. 864 * Return: 0 if the message digest creation was successful; < 0 if an error 865 * occurred 866 */ 867 int crypto_shash_digest(struct shash_desc *desc, const u8 *data, 868 unsigned int len, u8 *out); 869 870 /** 871 * crypto_shash_tfm_digest() - calculate message digest for buffer 872 * @tfm: hash transformation object 873 * @data: see crypto_shash_update() 874 * @len: see crypto_shash_update() 875 * @out: see crypto_shash_final() 876 * 877 * This is a simplified version of crypto_shash_digest() for users who don't 878 * want to allocate their own hash descriptor (shash_desc). Instead, 879 * crypto_shash_tfm_digest() takes a hash transformation object (crypto_shash) 880 * directly, and it allocates a hash descriptor on the stack internally. 881 * Note that this stack allocation may be fairly large. 882 * 883 * Context: Any context. 884 * Return: 0 on success; < 0 if an error occurred. 885 */ 886 int crypto_shash_tfm_digest(struct crypto_shash *tfm, const u8 *data, 887 unsigned int len, u8 *out); 888 889 /** 890 * crypto_shash_export() - extract operational state for message digest 891 * @desc: reference to the operational state handle whose state is exported 892 * @out: output buffer of sufficient size that can hold the hash state 893 * 894 * This function exports the hash state of the operational state handle into the 895 * caller-allocated output buffer out which must have sufficient size (e.g. by 896 * calling crypto_shash_descsize). 897 * 898 * Context: Any context. 899 * Return: 0 if the export creation was successful; < 0 if an error occurred 900 */ 901 static inline int crypto_shash_export(struct shash_desc *desc, void *out) 902 { 903 return crypto_shash_alg(desc->tfm)->export(desc, out); 904 } 905 906 /** 907 * crypto_shash_import() - import operational state 908 * @desc: reference to the operational state handle the state imported into 909 * @in: buffer holding the state 910 * 911 * This function imports the hash state into the operational state handle from 912 * the input buffer. That buffer should have been generated with the 913 * crypto_ahash_export function. 914 * 915 * Context: Any context. 916 * Return: 0 if the import was successful; < 0 if an error occurred 917 */ 918 static inline int crypto_shash_import(struct shash_desc *desc, const void *in) 919 { 920 struct crypto_shash *tfm = desc->tfm; 921 922 if (crypto_shash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY) 923 return -ENOKEY; 924 925 return crypto_shash_alg(tfm)->import(desc, in); 926 } 927 928 /** 929 * crypto_shash_init() - (re)initialize message digest 930 * @desc: operational state handle that is already filled 931 * 932 * The call (re-)initializes the message digest referenced by the 933 * operational state handle. Any potentially existing state created by 934 * previous operations is discarded. 935 * 936 * Context: Any context. 937 * Return: 0 if the message digest initialization was successful; < 0 if an 938 * error occurred 939 */ 940 static inline int crypto_shash_init(struct shash_desc *desc) 941 { 942 struct crypto_shash *tfm = desc->tfm; 943 944 if (crypto_shash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY) 945 return -ENOKEY; 946 947 return crypto_shash_alg(tfm)->init(desc); 948 } 949 950 /** 951 * crypto_shash_update() - add data to message digest for processing 952 * @desc: operational state handle that is already initialized 953 * @data: input data to be added to the message digest 954 * @len: length of the input data 955 * 956 * Updates the message digest state of the operational state handle. 957 * 958 * Context: Any context. 959 * Return: 0 if the message digest update was successful; < 0 if an error 960 * occurred 961 */ 962 int crypto_shash_update(struct shash_desc *desc, const u8 *data, 963 unsigned int len); 964 965 /** 966 * crypto_shash_final() - calculate message digest 967 * @desc: operational state handle that is already filled with data 968 * @out: output buffer filled with the message digest 969 * 970 * Finalize the message digest operation and create the message digest 971 * based on all data added to the cipher handle. The message digest is placed 972 * into the output buffer. The caller must ensure that the output buffer is 973 * large enough by using crypto_shash_digestsize. 974 * 975 * Context: Any context. 976 * Return: 0 if the message digest creation was successful; < 0 if an error 977 * occurred 978 */ 979 int crypto_shash_final(struct shash_desc *desc, u8 *out); 980 981 /** 982 * crypto_shash_finup() - calculate message digest of buffer 983 * @desc: see crypto_shash_final() 984 * @data: see crypto_shash_update() 985 * @len: see crypto_shash_update() 986 * @out: see crypto_shash_final() 987 * 988 * This function is a "short-hand" for the function calls of 989 * crypto_shash_update and crypto_shash_final. The parameters have the same 990 * meaning as discussed for those separate functions. 991 * 992 * Context: Any context. 993 * Return: 0 if the message digest creation was successful; < 0 if an error 994 * occurred 995 */ 996 int crypto_shash_finup(struct shash_desc *desc, const u8 *data, 997 unsigned int len, u8 *out); 998 999 static inline void shash_desc_zero(struct shash_desc *desc) 1000 { 1001 memzero_explicit(desc, 1002 sizeof(*desc) + crypto_shash_descsize(desc->tfm)); 1003 } 1004 1005 #endif /* _CRYPTO_HASH_H */ 1006