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 struct crypto_tfm base; 208 }; 209 210 struct crypto_shash { 211 unsigned int descsize; 212 struct crypto_tfm base; 213 }; 214 215 /** 216 * DOC: Asynchronous Message Digest API 217 * 218 * The asynchronous message digest API is used with the ciphers of type 219 * CRYPTO_ALG_TYPE_AHASH (listed as type "ahash" in /proc/crypto) 220 * 221 * The asynchronous cipher operation discussion provided for the 222 * CRYPTO_ALG_TYPE_ABLKCIPHER API applies here as well. 223 */ 224 225 static inline struct crypto_ahash *__crypto_ahash_cast(struct crypto_tfm *tfm) 226 { 227 return container_of(tfm, struct crypto_ahash, base); 228 } 229 230 /** 231 * crypto_alloc_ahash() - allocate ahash cipher handle 232 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the 233 * ahash cipher 234 * @type: specifies the type of the cipher 235 * @mask: specifies the mask for the cipher 236 * 237 * Allocate a cipher handle for an ahash. The returned struct 238 * crypto_ahash is the cipher handle that is required for any subsequent 239 * API invocation for that ahash. 240 * 241 * Return: allocated cipher handle in case of success; IS_ERR() is true in case 242 * of an error, PTR_ERR() returns the error code. 243 */ 244 struct crypto_ahash *crypto_alloc_ahash(const char *alg_name, u32 type, 245 u32 mask); 246 247 static inline struct crypto_tfm *crypto_ahash_tfm(struct crypto_ahash *tfm) 248 { 249 return &tfm->base; 250 } 251 252 /** 253 * crypto_free_ahash() - zeroize and free the ahash handle 254 * @tfm: cipher handle to be freed 255 */ 256 static inline void crypto_free_ahash(struct crypto_ahash *tfm) 257 { 258 crypto_destroy_tfm(tfm, crypto_ahash_tfm(tfm)); 259 } 260 261 static inline unsigned int crypto_ahash_alignmask( 262 struct crypto_ahash *tfm) 263 { 264 return crypto_tfm_alg_alignmask(crypto_ahash_tfm(tfm)); 265 } 266 267 static inline struct hash_alg_common *__crypto_hash_alg_common( 268 struct crypto_alg *alg) 269 { 270 return container_of(alg, struct hash_alg_common, base); 271 } 272 273 static inline struct hash_alg_common *crypto_hash_alg_common( 274 struct crypto_ahash *tfm) 275 { 276 return __crypto_hash_alg_common(crypto_ahash_tfm(tfm)->__crt_alg); 277 } 278 279 /** 280 * crypto_ahash_digestsize() - obtain message digest size 281 * @tfm: cipher handle 282 * 283 * The size for the message digest created by the message digest cipher 284 * referenced with the cipher handle is returned. 285 * 286 * 287 * Return: message digest size of cipher 288 */ 289 static inline unsigned int crypto_ahash_digestsize(struct crypto_ahash *tfm) 290 { 291 return crypto_hash_alg_common(tfm)->digestsize; 292 } 293 294 static inline unsigned int crypto_ahash_statesize(struct crypto_ahash *tfm) 295 { 296 return crypto_hash_alg_common(tfm)->statesize; 297 } 298 299 static inline u32 crypto_ahash_get_flags(struct crypto_ahash *tfm) 300 { 301 return crypto_tfm_get_flags(crypto_ahash_tfm(tfm)); 302 } 303 304 static inline void crypto_ahash_set_flags(struct crypto_ahash *tfm, u32 flags) 305 { 306 crypto_tfm_set_flags(crypto_ahash_tfm(tfm), flags); 307 } 308 309 static inline void crypto_ahash_clear_flags(struct crypto_ahash *tfm, u32 flags) 310 { 311 crypto_tfm_clear_flags(crypto_ahash_tfm(tfm), flags); 312 } 313 314 /** 315 * crypto_ahash_reqtfm() - obtain cipher handle from request 316 * @req: asynchronous request handle that contains the reference to the ahash 317 * cipher handle 318 * 319 * Return the ahash cipher handle that is registered with the asynchronous 320 * request handle ahash_request. 321 * 322 * Return: ahash cipher handle 323 */ 324 static inline struct crypto_ahash *crypto_ahash_reqtfm( 325 struct ahash_request *req) 326 { 327 return __crypto_ahash_cast(req->base.tfm); 328 } 329 330 /** 331 * crypto_ahash_reqsize() - obtain size of the request data structure 332 * @tfm: cipher handle 333 * 334 * Return the size of the ahash state size. With the crypto_ahash_export 335 * function, the caller can export the state into a buffer whose size is 336 * defined with this function. 337 * 338 * Return: size of the ahash state 339 */ 340 static inline unsigned int crypto_ahash_reqsize(struct crypto_ahash *tfm) 341 { 342 return tfm->reqsize; 343 } 344 345 static inline void *ahash_request_ctx(struct ahash_request *req) 346 { 347 return req->__ctx; 348 } 349 350 /** 351 * crypto_ahash_setkey - set key for cipher handle 352 * @tfm: cipher handle 353 * @key: buffer holding the key 354 * @keylen: length of the key in bytes 355 * 356 * The caller provided key is set for the ahash cipher. The cipher 357 * handle must point to a keyed hash in order for this function to succeed. 358 * 359 * Return: 0 if the setting of the key was successful; < 0 if an error occurred 360 */ 361 int crypto_ahash_setkey(struct crypto_ahash *tfm, const u8 *key, 362 unsigned int keylen); 363 364 /** 365 * crypto_ahash_finup() - update and finalize message digest 366 * @req: reference to the ahash_request handle that holds all information 367 * needed to perform the cipher operation 368 * 369 * This function is a "short-hand" for the function calls of 370 * crypto_ahash_update and crypto_shash_final. The parameters have the same 371 * meaning as discussed for those separate functions. 372 * 373 * Return: 0 if the message digest creation was successful; < 0 if an error 374 * occurred 375 */ 376 int crypto_ahash_finup(struct ahash_request *req); 377 378 /** 379 * crypto_ahash_final() - calculate message digest 380 * @req: reference to the ahash_request handle that holds all information 381 * needed to perform the cipher operation 382 * 383 * Finalize the message digest operation and create the message digest 384 * based on all data added to the cipher handle. The message digest is placed 385 * into the output buffer registered with the ahash_request handle. 386 * 387 * Return: 0 if the message digest creation was successful; < 0 if an error 388 * occurred 389 */ 390 int crypto_ahash_final(struct ahash_request *req); 391 392 /** 393 * crypto_ahash_digest() - calculate message digest for a buffer 394 * @req: reference to the ahash_request handle that holds all information 395 * needed to perform the cipher operation 396 * 397 * This function is a "short-hand" for the function calls of crypto_ahash_init, 398 * crypto_ahash_update and crypto_ahash_final. The parameters have the same 399 * meaning as discussed for those separate three functions. 400 * 401 * Return: 0 if the message digest creation was successful; < 0 if an error 402 * occurred 403 */ 404 int crypto_ahash_digest(struct ahash_request *req); 405 406 /** 407 * crypto_ahash_export() - extract current message digest state 408 * @req: reference to the ahash_request handle whose state is exported 409 * @out: output buffer of sufficient size that can hold the hash state 410 * 411 * This function exports the hash state of the ahash_request handle into the 412 * caller-allocated output buffer out which must have sufficient size (e.g. by 413 * calling crypto_ahash_reqsize). 414 * 415 * Return: 0 if the export was successful; < 0 if an error occurred 416 */ 417 static inline int crypto_ahash_export(struct ahash_request *req, void *out) 418 { 419 return crypto_ahash_reqtfm(req)->export(req, out); 420 } 421 422 /** 423 * crypto_ahash_import() - import message digest state 424 * @req: reference to ahash_request handle the state is imported into 425 * @in: buffer holding the state 426 * 427 * This function imports the hash state into the ahash_request handle from the 428 * input buffer. That buffer should have been generated with the 429 * crypto_ahash_export function. 430 * 431 * Return: 0 if the import was successful; < 0 if an error occurred 432 */ 433 static inline int crypto_ahash_import(struct ahash_request *req, const void *in) 434 { 435 return crypto_ahash_reqtfm(req)->import(req, in); 436 } 437 438 /** 439 * crypto_ahash_init() - (re)initialize message digest handle 440 * @req: ahash_request handle that already is initialized with all necessary 441 * data using the ahash_request_* API functions 442 * 443 * The call (re-)initializes the message digest referenced by the ahash_request 444 * handle. Any potentially existing state created by previous operations is 445 * discarded. 446 * 447 * Return: 0 if the message digest initialization was successful; < 0 if an 448 * error occurred 449 */ 450 static inline int crypto_ahash_init(struct ahash_request *req) 451 { 452 return crypto_ahash_reqtfm(req)->init(req); 453 } 454 455 /** 456 * crypto_ahash_update() - add data to message digest for processing 457 * @req: ahash_request handle that was previously initialized with the 458 * crypto_ahash_init call. 459 * 460 * Updates the message digest state of the &ahash_request handle. The input data 461 * is pointed to by the scatter/gather list registered in the &ahash_request 462 * handle 463 * 464 * Return: 0 if the message digest update was successful; < 0 if an error 465 * occurred 466 */ 467 static inline int crypto_ahash_update(struct ahash_request *req) 468 { 469 return crypto_ahash_reqtfm(req)->update(req); 470 } 471 472 /** 473 * DOC: Asynchronous Hash Request Handle 474 * 475 * The &ahash_request data structure contains all pointers to data 476 * required for the asynchronous cipher operation. This includes the cipher 477 * handle (which can be used by multiple &ahash_request instances), pointer 478 * to plaintext and the message digest output buffer, asynchronous callback 479 * function, etc. It acts as a handle to the ahash_request_* API calls in a 480 * similar way as ahash handle to the crypto_ahash_* API calls. 481 */ 482 483 /** 484 * ahash_request_set_tfm() - update cipher handle reference in request 485 * @req: request handle to be modified 486 * @tfm: cipher handle that shall be added to the request handle 487 * 488 * Allow the caller to replace the existing ahash handle in the request 489 * data structure with a different one. 490 */ 491 static inline void ahash_request_set_tfm(struct ahash_request *req, 492 struct crypto_ahash *tfm) 493 { 494 req->base.tfm = crypto_ahash_tfm(tfm); 495 } 496 497 /** 498 * ahash_request_alloc() - allocate request data structure 499 * @tfm: cipher handle to be registered with the request 500 * @gfp: memory allocation flag that is handed to kmalloc by the API call. 501 * 502 * Allocate the request data structure that must be used with the ahash 503 * message digest API calls. During 504 * the allocation, the provided ahash handle 505 * is registered in the request data structure. 506 * 507 * Return: allocated request handle in case of success; IS_ERR() is true in case 508 * of an error, PTR_ERR() returns the error code. 509 */ 510 static inline struct ahash_request *ahash_request_alloc( 511 struct crypto_ahash *tfm, gfp_t gfp) 512 { 513 struct ahash_request *req; 514 515 req = kmalloc(sizeof(struct ahash_request) + 516 crypto_ahash_reqsize(tfm), gfp); 517 518 if (likely(req)) 519 ahash_request_set_tfm(req, tfm); 520 521 return req; 522 } 523 524 /** 525 * ahash_request_free() - zeroize and free the request data structure 526 * @req: request data structure cipher handle to be freed 527 */ 528 static inline void ahash_request_free(struct ahash_request *req) 529 { 530 kzfree(req); 531 } 532 533 static inline struct ahash_request *ahash_request_cast( 534 struct crypto_async_request *req) 535 { 536 return container_of(req, struct ahash_request, base); 537 } 538 539 /** 540 * ahash_request_set_callback() - set asynchronous callback function 541 * @req: request handle 542 * @flags: specify zero or an ORing of the flags 543 * CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and 544 * increase the wait queue beyond the initial maximum size; 545 * CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep 546 * @compl: callback function pointer to be registered with the request handle 547 * @data: The data pointer refers to memory that is not used by the kernel 548 * crypto API, but provided to the callback function for it to use. Here, 549 * the caller can provide a reference to memory the callback function can 550 * operate on. As the callback function is invoked asynchronously to the 551 * related functionality, it may need to access data structures of the 552 * related functionality which can be referenced using this pointer. The 553 * callback function can access the memory via the "data" field in the 554 * &crypto_async_request data structure provided to the callback function. 555 * 556 * This function allows setting the callback function that is triggered once 557 * the cipher operation completes. 558 * 559 * The callback function is registered with the &ahash_request handle and 560 * must comply with the following template 561 * 562 * void callback_function(struct crypto_async_request *req, int error) 563 */ 564 static inline void ahash_request_set_callback(struct ahash_request *req, 565 u32 flags, 566 crypto_completion_t compl, 567 void *data) 568 { 569 req->base.complete = compl; 570 req->base.data = data; 571 req->base.flags = flags; 572 } 573 574 /** 575 * ahash_request_set_crypt() - set data buffers 576 * @req: ahash_request handle to be updated 577 * @src: source scatter/gather list 578 * @result: buffer that is filled with the message digest -- the caller must 579 * ensure that the buffer has sufficient space by, for example, calling 580 * crypto_ahash_digestsize() 581 * @nbytes: number of bytes to process from the source scatter/gather list 582 * 583 * By using this call, the caller references the source scatter/gather list. 584 * The source scatter/gather list points to the data the message digest is to 585 * be calculated for. 586 */ 587 static inline void ahash_request_set_crypt(struct ahash_request *req, 588 struct scatterlist *src, u8 *result, 589 unsigned int nbytes) 590 { 591 req->src = src; 592 req->nbytes = nbytes; 593 req->result = result; 594 } 595 596 /** 597 * DOC: Synchronous Message Digest API 598 * 599 * The synchronous message digest API is used with the ciphers of type 600 * CRYPTO_ALG_TYPE_SHASH (listed as type "shash" in /proc/crypto) 601 * 602 * The message digest API is able to maintain state information for the 603 * caller. 604 * 605 * The synchronous message digest API can store user-related context in in its 606 * shash_desc request data structure. 607 */ 608 609 /** 610 * crypto_alloc_shash() - allocate message digest handle 611 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the 612 * message digest cipher 613 * @type: specifies the type of the cipher 614 * @mask: specifies the mask for the cipher 615 * 616 * Allocate a cipher handle for a message digest. The returned &struct 617 * crypto_shash is the cipher handle that is required for any subsequent 618 * API invocation for that message digest. 619 * 620 * Return: allocated cipher handle in case of success; IS_ERR() is true in case 621 * of an error, PTR_ERR() returns the error code. 622 */ 623 struct crypto_shash *crypto_alloc_shash(const char *alg_name, u32 type, 624 u32 mask); 625 626 static inline struct crypto_tfm *crypto_shash_tfm(struct crypto_shash *tfm) 627 { 628 return &tfm->base; 629 } 630 631 /** 632 * crypto_free_shash() - zeroize and free the message digest handle 633 * @tfm: cipher handle to be freed 634 */ 635 static inline void crypto_free_shash(struct crypto_shash *tfm) 636 { 637 crypto_destroy_tfm(tfm, crypto_shash_tfm(tfm)); 638 } 639 640 static inline unsigned int crypto_shash_alignmask( 641 struct crypto_shash *tfm) 642 { 643 return crypto_tfm_alg_alignmask(crypto_shash_tfm(tfm)); 644 } 645 646 /** 647 * crypto_shash_blocksize() - obtain block size for cipher 648 * @tfm: cipher handle 649 * 650 * The block size for the message digest cipher referenced with the cipher 651 * handle is returned. 652 * 653 * Return: block size of cipher 654 */ 655 static inline unsigned int crypto_shash_blocksize(struct crypto_shash *tfm) 656 { 657 return crypto_tfm_alg_blocksize(crypto_shash_tfm(tfm)); 658 } 659 660 static inline struct shash_alg *__crypto_shash_alg(struct crypto_alg *alg) 661 { 662 return container_of(alg, struct shash_alg, base); 663 } 664 665 static inline struct shash_alg *crypto_shash_alg(struct crypto_shash *tfm) 666 { 667 return __crypto_shash_alg(crypto_shash_tfm(tfm)->__crt_alg); 668 } 669 670 /** 671 * crypto_shash_digestsize() - obtain message digest size 672 * @tfm: cipher handle 673 * 674 * The size for the message digest created by the message digest cipher 675 * referenced with the cipher handle is returned. 676 * 677 * Return: digest size of cipher 678 */ 679 static inline unsigned int crypto_shash_digestsize(struct crypto_shash *tfm) 680 { 681 return crypto_shash_alg(tfm)->digestsize; 682 } 683 684 static inline unsigned int crypto_shash_statesize(struct crypto_shash *tfm) 685 { 686 return crypto_shash_alg(tfm)->statesize; 687 } 688 689 static inline u32 crypto_shash_get_flags(struct crypto_shash *tfm) 690 { 691 return crypto_tfm_get_flags(crypto_shash_tfm(tfm)); 692 } 693 694 static inline void crypto_shash_set_flags(struct crypto_shash *tfm, u32 flags) 695 { 696 crypto_tfm_set_flags(crypto_shash_tfm(tfm), flags); 697 } 698 699 static inline void crypto_shash_clear_flags(struct crypto_shash *tfm, u32 flags) 700 { 701 crypto_tfm_clear_flags(crypto_shash_tfm(tfm), flags); 702 } 703 704 /** 705 * crypto_shash_descsize() - obtain the operational state size 706 * @tfm: cipher handle 707 * 708 * The size of the operational state the cipher needs during operation is 709 * returned for the hash referenced with the cipher handle. This size is 710 * required to calculate the memory requirements to allow the caller allocating 711 * sufficient memory for operational state. 712 * 713 * The operational state is defined with struct shash_desc where the size of 714 * that data structure is to be calculated as 715 * sizeof(struct shash_desc) + crypto_shash_descsize(alg) 716 * 717 * Return: size of the operational state 718 */ 719 static inline unsigned int crypto_shash_descsize(struct crypto_shash *tfm) 720 { 721 return tfm->descsize; 722 } 723 724 static inline void *shash_desc_ctx(struct shash_desc *desc) 725 { 726 return desc->__ctx; 727 } 728 729 /** 730 * crypto_shash_setkey() - set key for message digest 731 * @tfm: cipher handle 732 * @key: buffer holding the key 733 * @keylen: length of the key in bytes 734 * 735 * The caller provided key is set for the keyed message digest cipher. The 736 * cipher handle must point to a keyed message digest cipher in order for this 737 * function to succeed. 738 * 739 * Return: 0 if the setting of the key was successful; < 0 if an error occurred 740 */ 741 int crypto_shash_setkey(struct crypto_shash *tfm, const u8 *key, 742 unsigned int keylen); 743 744 /** 745 * crypto_shash_digest() - calculate message digest for buffer 746 * @desc: see crypto_shash_final() 747 * @data: see crypto_shash_update() 748 * @len: see crypto_shash_update() 749 * @out: see crypto_shash_final() 750 * 751 * This function is a "short-hand" for the function calls of crypto_shash_init, 752 * crypto_shash_update and crypto_shash_final. The parameters have the same 753 * meaning as discussed for those separate three functions. 754 * 755 * Return: 0 if the message digest creation was successful; < 0 if an error 756 * occurred 757 */ 758 int crypto_shash_digest(struct shash_desc *desc, const u8 *data, 759 unsigned int len, u8 *out); 760 761 /** 762 * crypto_shash_export() - extract operational state for message digest 763 * @desc: reference to the operational state handle whose state is exported 764 * @out: output buffer of sufficient size that can hold the hash state 765 * 766 * This function exports the hash state of the operational state handle into the 767 * caller-allocated output buffer out which must have sufficient size (e.g. by 768 * calling crypto_shash_descsize). 769 * 770 * Return: 0 if the export creation was successful; < 0 if an error occurred 771 */ 772 static inline int crypto_shash_export(struct shash_desc *desc, void *out) 773 { 774 return crypto_shash_alg(desc->tfm)->export(desc, out); 775 } 776 777 /** 778 * crypto_shash_import() - import operational state 779 * @desc: reference to the operational state handle the state imported into 780 * @in: buffer holding the state 781 * 782 * This function imports the hash state into the operational state handle from 783 * the input buffer. That buffer should have been generated with the 784 * crypto_ahash_export function. 785 * 786 * Return: 0 if the import was successful; < 0 if an error occurred 787 */ 788 static inline int crypto_shash_import(struct shash_desc *desc, const void *in) 789 { 790 return crypto_shash_alg(desc->tfm)->import(desc, in); 791 } 792 793 /** 794 * crypto_shash_init() - (re)initialize message digest 795 * @desc: operational state handle that is already filled 796 * 797 * The call (re-)initializes the message digest referenced by the 798 * operational state handle. Any potentially existing state created by 799 * previous operations is discarded. 800 * 801 * Return: 0 if the message digest initialization was successful; < 0 if an 802 * error occurred 803 */ 804 static inline int crypto_shash_init(struct shash_desc *desc) 805 { 806 return crypto_shash_alg(desc->tfm)->init(desc); 807 } 808 809 /** 810 * crypto_shash_update() - add data to message digest for processing 811 * @desc: operational state handle that is already initialized 812 * @data: input data to be added to the message digest 813 * @len: length of the input data 814 * 815 * Updates the message digest state of the operational state handle. 816 * 817 * Return: 0 if the message digest update was successful; < 0 if an error 818 * occurred 819 */ 820 int crypto_shash_update(struct shash_desc *desc, const u8 *data, 821 unsigned int len); 822 823 /** 824 * crypto_shash_final() - calculate message digest 825 * @desc: operational state handle that is already filled with data 826 * @out: output buffer filled with the message digest 827 * 828 * Finalize the message digest operation and create the message digest 829 * based on all data added to the cipher handle. The message digest is placed 830 * into the output buffer. The caller must ensure that the output buffer is 831 * large enough by using crypto_shash_digestsize. 832 * 833 * Return: 0 if the message digest creation was successful; < 0 if an error 834 * occurred 835 */ 836 int crypto_shash_final(struct shash_desc *desc, u8 *out); 837 838 /** 839 * crypto_shash_finup() - calculate message digest of buffer 840 * @desc: see crypto_shash_final() 841 * @data: see crypto_shash_update() 842 * @len: see crypto_shash_update() 843 * @out: see crypto_shash_final() 844 * 845 * This function is a "short-hand" for the function calls of 846 * crypto_shash_update and crypto_shash_final. The parameters have the same 847 * meaning as discussed for those separate functions. 848 * 849 * Return: 0 if the message digest creation was successful; < 0 if an error 850 * occurred 851 */ 852 int crypto_shash_finup(struct shash_desc *desc, const u8 *data, 853 unsigned int len, u8 *out); 854 855 #endif /* _CRYPTO_HASH_H */ 856