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