1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> 4 5<book id="KernelCryptoAPI"> 6 <bookinfo> 7 <title>Linux Kernel Crypto API</title> 8 9 <authorgroup> 10 <author> 11 <firstname>Stephan</firstname> 12 <surname>Mueller</surname> 13 <affiliation> 14 <address> 15 <email>smueller@chronox.de</email> 16 </address> 17 </affiliation> 18 </author> 19 <author> 20 <firstname>Marek</firstname> 21 <surname>Vasut</surname> 22 <affiliation> 23 <address> 24 <email>marek@denx.de</email> 25 </address> 26 </affiliation> 27 </author> 28 </authorgroup> 29 30 <copyright> 31 <year>2014</year> 32 <holder>Stephan Mueller</holder> 33 </copyright> 34 35 36 <legalnotice> 37 <para> 38 This documentation is free software; you can redistribute 39 it and/or modify it under the terms of the GNU General Public 40 License as published by the Free Software Foundation; either 41 version 2 of the License, or (at your option) any later 42 version. 43 </para> 44 45 <para> 46 This program is distributed in the hope that it will be 47 useful, but WITHOUT ANY WARRANTY; without even the implied 48 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 49 See the GNU General Public License for more details. 50 </para> 51 52 <para> 53 You should have received a copy of the GNU General Public 54 License along with this program; if not, write to the Free 55 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 56 MA 02111-1307 USA 57 </para> 58 59 <para> 60 For more details see the file COPYING in the source 61 distribution of Linux. 62 </para> 63 </legalnotice> 64 </bookinfo> 65 66 <toc></toc> 67 68 <chapter id="Intro"> 69 <title>Kernel Crypto API Interface Specification</title> 70 71 <sect1><title>Introduction</title> 72 73 <para> 74 The kernel crypto API offers a rich set of cryptographic ciphers as 75 well as other data transformation mechanisms and methods to invoke 76 these. This document contains a description of the API and provides 77 example code. 78 </para> 79 80 <para> 81 To understand and properly use the kernel crypto API a brief 82 explanation of its structure is given. Based on the architecture, 83 the API can be separated into different components. Following the 84 architecture specification, hints to developers of ciphers are 85 provided. Pointers to the API function call documentation are 86 given at the end. 87 </para> 88 89 <para> 90 The kernel crypto API refers to all algorithms as "transformations". 91 Therefore, a cipher handle variable usually has the name "tfm". 92 Besides cryptographic operations, the kernel crypto API also knows 93 compression transformations and handles them the same way as ciphers. 94 </para> 95 96 <para> 97 The kernel crypto API serves the following entity types: 98 99 <itemizedlist> 100 <listitem> 101 <para>consumers requesting cryptographic services</para> 102 </listitem> 103 <listitem> 104 <para>data transformation implementations (typically ciphers) 105 that can be called by consumers using the kernel crypto 106 API</para> 107 </listitem> 108 </itemizedlist> 109 </para> 110 111 <para> 112 This specification is intended for consumers of the kernel crypto 113 API as well as for developers implementing ciphers. This API 114 specification, however, does not discuss all API calls available 115 to data transformation implementations (i.e. implementations of 116 ciphers and other transformations (such as CRC or even compression 117 algorithms) that can register with the kernel crypto API). 118 </para> 119 120 <para> 121 Note: The terms "transformation" and cipher algorithm are used 122 interchangably. 123 </para> 124 </sect1> 125 126 <sect1><title>Terminology</title> 127 <para> 128 The transformation implementation is an actual code or interface 129 to hardware which implements a certain transformation with precisely 130 defined behavior. 131 </para> 132 133 <para> 134 The transformation object (TFM) is an instance of a transformation 135 implementation. There can be multiple transformation objects 136 associated with a single transformation implementation. Each of 137 those transformation objects is held by a crypto API consumer or 138 another transformation. Transformation object is allocated when a 139 crypto API consumer requests a transformation implementation. 140 The consumer is then provided with a structure, which contains 141 a transformation object (TFM). 142 </para> 143 144 <para> 145 The structure that contains transformation objects may also be 146 referred to as a "cipher handle". Such a cipher handle is always 147 subject to the following phases that are reflected in the API calls 148 applicable to such a cipher handle: 149 </para> 150 151 <orderedlist> 152 <listitem> 153 <para>Initialization of a cipher handle.</para> 154 </listitem> 155 <listitem> 156 <para>Execution of all intended cipher operations applicable 157 for the handle where the cipher handle must be furnished to 158 every API call.</para> 159 </listitem> 160 <listitem> 161 <para>Destruction of a cipher handle.</para> 162 </listitem> 163 </orderedlist> 164 165 <para> 166 When using the initialization API calls, a cipher handle is 167 created and returned to the consumer. Therefore, please refer 168 to all initialization API calls that refer to the data 169 structure type a consumer is expected to receive and subsequently 170 to use. The initialization API calls have all the same naming 171 conventions of crypto_alloc_*. 172 </para> 173 174 <para> 175 The transformation context is private data associated with 176 the transformation object. 177 </para> 178 </sect1> 179 </chapter> 180 181 <chapter id="Architecture"><title>Kernel Crypto API Architecture</title> 182 <sect1><title>Cipher algorithm types</title> 183 <para> 184 The kernel crypto API provides different API calls for the 185 following cipher types: 186 187 <itemizedlist> 188 <listitem><para>Symmetric ciphers</para></listitem> 189 <listitem><para>AEAD ciphers</para></listitem> 190 <listitem><para>Message digest, including keyed message digest</para></listitem> 191 <listitem><para>Random number generation</para></listitem> 192 <listitem><para>User space interface</para></listitem> 193 </itemizedlist> 194 </para> 195 </sect1> 196 197 <sect1><title>Ciphers And Templates</title> 198 <para> 199 The kernel crypto API provides implementations of single block 200 ciphers and message digests. In addition, the kernel crypto API 201 provides numerous "templates" that can be used in conjunction 202 with the single block ciphers and message digests. Templates 203 include all types of block chaining mode, the HMAC mechanism, etc. 204 </para> 205 206 <para> 207 Single block ciphers and message digests can either be directly 208 used by a caller or invoked together with a template to form 209 multi-block ciphers or keyed message digests. 210 </para> 211 212 <para> 213 A single block cipher may even be called with multiple templates. 214 However, templates cannot be used without a single cipher. 215 </para> 216 217 <para> 218 See /proc/crypto and search for "name". For example: 219 220 <itemizedlist> 221 <listitem><para>aes</para></listitem> 222 <listitem><para>ecb(aes)</para></listitem> 223 <listitem><para>cmac(aes)</para></listitem> 224 <listitem><para>ccm(aes)</para></listitem> 225 <listitem><para>rfc4106(gcm(aes))</para></listitem> 226 <listitem><para>sha1</para></listitem> 227 <listitem><para>hmac(sha1)</para></listitem> 228 <listitem><para>authenc(hmac(sha1),cbc(aes))</para></listitem> 229 </itemizedlist> 230 </para> 231 232 <para> 233 In these examples, "aes" and "sha1" are the ciphers and all 234 others are the templates. 235 </para> 236 </sect1> 237 238 <sect1><title>Synchronous And Asynchronous Operation</title> 239 <para> 240 The kernel crypto API provides synchronous and asynchronous 241 API operations. 242 </para> 243 244 <para> 245 When using the synchronous API operation, the caller invokes 246 a cipher operation which is performed synchronously by the 247 kernel crypto API. That means, the caller waits until the 248 cipher operation completes. Therefore, the kernel crypto API 249 calls work like regular function calls. For synchronous 250 operation, the set of API calls is small and conceptually 251 similar to any other crypto library. 252 </para> 253 254 <para> 255 Asynchronous operation is provided by the kernel crypto API 256 which implies that the invocation of a cipher operation will 257 complete almost instantly. That invocation triggers the 258 cipher operation but it does not signal its completion. Before 259 invoking a cipher operation, the caller must provide a callback 260 function the kernel crypto API can invoke to signal the 261 completion of the cipher operation. Furthermore, the caller 262 must ensure it can handle such asynchronous events by applying 263 appropriate locking around its data. The kernel crypto API 264 does not perform any special serialization operation to protect 265 the caller's data integrity. 266 </para> 267 </sect1> 268 269 <sect1><title>Crypto API Cipher References And Priority</title> 270 <para> 271 A cipher is referenced by the caller with a string. That string 272 has the following semantics: 273 274 <programlisting> 275 template(single block cipher) 276 </programlisting> 277 278 where "template" and "single block cipher" is the aforementioned 279 template and single block cipher, respectively. If applicable, 280 additional templates may enclose other templates, such as 281 282 <programlisting> 283 template1(template2(single block cipher))) 284 </programlisting> 285 </para> 286 287 <para> 288 The kernel crypto API may provide multiple implementations of a 289 template or a single block cipher. For example, AES on newer 290 Intel hardware has the following implementations: AES-NI, 291 assembler implementation, or straight C. Now, when using the 292 string "aes" with the kernel crypto API, which cipher 293 implementation is used? The answer to that question is the 294 priority number assigned to each cipher implementation by the 295 kernel crypto API. When a caller uses the string to refer to a 296 cipher during initialization of a cipher handle, the kernel 297 crypto API looks up all implementations providing an 298 implementation with that name and selects the implementation 299 with the highest priority. 300 </para> 301 302 <para> 303 Now, a caller may have the need to refer to a specific cipher 304 implementation and thus does not want to rely on the 305 priority-based selection. To accommodate this scenario, the 306 kernel crypto API allows the cipher implementation to register 307 a unique name in addition to common names. When using that 308 unique name, a caller is therefore always sure to refer to 309 the intended cipher implementation. 310 </para> 311 312 <para> 313 The list of available ciphers is given in /proc/crypto. However, 314 that list does not specify all possible permutations of 315 templates and ciphers. Each block listed in /proc/crypto may 316 contain the following information -- if one of the components 317 listed as follows are not applicable to a cipher, it is not 318 displayed: 319 </para> 320 321 <itemizedlist> 322 <listitem> 323 <para>name: the generic name of the cipher that is subject 324 to the priority-based selection -- this name can be used by 325 the cipher allocation API calls (all names listed above are 326 examples for such generic names)</para> 327 </listitem> 328 <listitem> 329 <para>driver: the unique name of the cipher -- this name can 330 be used by the cipher allocation API calls</para> 331 </listitem> 332 <listitem> 333 <para>module: the kernel module providing the cipher 334 implementation (or "kernel" for statically linked ciphers)</para> 335 </listitem> 336 <listitem> 337 <para>priority: the priority value of the cipher implementation</para> 338 </listitem> 339 <listitem> 340 <para>refcnt: the reference count of the respective cipher 341 (i.e. the number of current consumers of this cipher)</para> 342 </listitem> 343 <listitem> 344 <para>selftest: specification whether the self test for the 345 cipher passed</para> 346 </listitem> 347 <listitem> 348 <para>type: 349 <itemizedlist> 350 <listitem> 351 <para>blkcipher for synchronous block ciphers</para> 352 </listitem> 353 <listitem> 354 <para>ablkcipher for asynchronous block ciphers</para> 355 </listitem> 356 <listitem> 357 <para>cipher for single block ciphers that may be used with 358 an additional template</para> 359 </listitem> 360 <listitem> 361 <para>shash for synchronous message digest</para> 362 </listitem> 363 <listitem> 364 <para>ahash for asynchronous message digest</para> 365 </listitem> 366 <listitem> 367 <para>aead for AEAD cipher type</para> 368 </listitem> 369 <listitem> 370 <para>compression for compression type transformations</para> 371 </listitem> 372 <listitem> 373 <para>rng for random number generator</para> 374 </listitem> 375 <listitem> 376 <para>givcipher for cipher with associated IV generator 377 (see the geniv entry below for the specification of the 378 IV generator type used by the cipher implementation)</para> 379 </listitem> 380 </itemizedlist> 381 </para> 382 </listitem> 383 <listitem> 384 <para>blocksize: blocksize of cipher in bytes</para> 385 </listitem> 386 <listitem> 387 <para>keysize: key size in bytes</para> 388 </listitem> 389 <listitem> 390 <para>ivsize: IV size in bytes</para> 391 </listitem> 392 <listitem> 393 <para>seedsize: required size of seed data for random number 394 generator</para> 395 </listitem> 396 <listitem> 397 <para>digestsize: output size of the message digest</para> 398 </listitem> 399 <listitem> 400 <para>geniv: IV generation type: 401 <itemizedlist> 402 <listitem> 403 <para>eseqiv for encrypted sequence number based IV 404 generation</para> 405 </listitem> 406 <listitem> 407 <para>seqiv for sequence number based IV generation</para> 408 </listitem> 409 <listitem> 410 <para>chainiv for chain iv generation</para> 411 </listitem> 412 <listitem> 413 <para><builtin> is a marker that the cipher implements 414 IV generation and handling as it is specific to the given 415 cipher</para> 416 </listitem> 417 </itemizedlist> 418 </para> 419 </listitem> 420 </itemizedlist> 421 </sect1> 422 423 <sect1><title>Key Sizes</title> 424 <para> 425 When allocating a cipher handle, the caller only specifies the 426 cipher type. Symmetric ciphers, however, typically support 427 multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256). 428 These key sizes are determined with the length of the provided 429 key. Thus, the kernel crypto API does not provide a separate 430 way to select the particular symmetric cipher key size. 431 </para> 432 </sect1> 433 434 <sect1><title>Cipher Allocation Type And Masks</title> 435 <para> 436 The different cipher handle allocation functions allow the 437 specification of a type and mask flag. Both parameters have 438 the following meaning (and are therefore not covered in the 439 subsequent sections). 440 </para> 441 442 <para> 443 The type flag specifies the type of the cipher algorithm. 444 The caller usually provides a 0 when the caller wants the 445 default handling. Otherwise, the caller may provide the 446 following selections which match the the aforementioned 447 cipher types: 448 </para> 449 450 <itemizedlist> 451 <listitem> 452 <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para> 453 </listitem> 454 <listitem> 455 <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para> 456 </listitem> 457 <listitem> 458 <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with 459 Associated Data (MAC)</para> 460 </listitem> 461 <listitem> 462 <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para> 463 </listitem> 464 <listitem> 465 <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para> 466 </listitem> 467 <listitem> 468 <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block 469 cipher packed together with an IV generator (see geniv field 470 in the /proc/crypto listing for the known IV generators)</para> 471 </listitem> 472 <listitem> 473 <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para> 474 </listitem> 475 <listitem> 476 <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para> 477 </listitem> 478 <listitem> 479 <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para> 480 </listitem> 481 <listitem> 482 <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para> 483 </listitem> 484 <listitem> 485 <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para> 486 </listitem> 487 <listitem> 488 <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of 489 CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / 490 decompression instead of performing the operation on one 491 segment only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace 492 CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.</para> 493 </listitem> 494 </itemizedlist> 495 496 <para> 497 The mask flag restricts the type of cipher. The only allowed 498 flag is CRYPTO_ALG_ASYNC to restrict the cipher lookup function 499 to asynchronous ciphers. Usually, a caller provides a 0 for the 500 mask flag. 501 </para> 502 503 <para> 504 When the caller provides a mask and type specification, the 505 caller limits the search the kernel crypto API can perform for 506 a suitable cipher implementation for the given cipher name. 507 That means, even when a caller uses a cipher name that exists 508 during its initialization call, the kernel crypto API may not 509 select it due to the used type and mask field. 510 </para> 511 </sect1> 512 513 <sect1><title>Internal Structure of Kernel Crypto API</title> 514 515 <para> 516 The kernel crypto API has an internal structure where a cipher 517 implementation may use many layers and indirections. This section 518 shall help to clarify how the kernel crypto API uses 519 various components to implement the complete cipher. 520 </para> 521 522 <para> 523 The following subsections explain the internal structure based 524 on existing cipher implementations. The first section addresses 525 the most complex scenario where all other scenarios form a logical 526 subset. 527 </para> 528 529 <sect2><title>Generic AEAD Cipher Structure</title> 530 531 <para> 532 The following ASCII art decomposes the kernel crypto API layers 533 when using the AEAD cipher with the automated IV generation. The 534 shown example is used by the IPSEC layer. 535 </para> 536 537 <para> 538 For other use cases of AEAD ciphers, the ASCII art applies as 539 well, but the caller may not use the GIVCIPHER interface. In 540 this case, the caller must generate the IV. 541 </para> 542 543 <para> 544 The depicted example decomposes the AEAD cipher of GCM(AES) based 545 on the generic C implementations (gcm.c, aes-generic.c, ctr.c, 546 ghash-generic.c, seqiv.c). The generic implementation serves as an 547 example showing the complete logic of the kernel crypto API. 548 </para> 549 550 <para> 551 It is possible that some streamlined cipher implementations (like 552 AES-NI) provide implementations merging aspects which in the view 553 of the kernel crypto API cannot be decomposed into layers any more. 554 In case of the AES-NI implementation, the CTR mode, the GHASH 555 implementation and the AES cipher are all merged into one cipher 556 implementation registered with the kernel crypto API. In this case, 557 the concept described by the following ASCII art applies too. However, 558 the decomposition of GCM into the individual sub-components 559 by the kernel crypto API is not done any more. 560 </para> 561 562 <para> 563 Each block in the following ASCII art is an independent cipher 564 instance obtained from the kernel crypto API. Each block 565 is accessed by the caller or by other blocks using the API functions 566 defined by the kernel crypto API for the cipher implementation type. 567 </para> 568 569 <para> 570 The blocks below indicate the cipher type as well as the specific 571 logic implemented in the cipher. 572 </para> 573 574 <para> 575 The ASCII art picture also indicates the call structure, i.e. who 576 calls which component. The arrows point to the invoked block 577 where the caller uses the API applicable to the cipher type 578 specified for the block. 579 </para> 580 581 <programlisting> 582<![CDATA[ 583kernel crypto API | IPSEC Layer 584 | 585+-----------+ | 586| | (1) 587| givcipher | <----------------------------------- esp_output 588| (seqiv) | ---+ 589+-----------+ | 590 | (2) 591+-----------+ | 592| | <--+ (2) 593| aead | <----------------------------------- esp_input 594| (gcm) | ------------+ 595+-----------+ | 596 | (3) | (5) 597 v v 598+-----------+ +-----------+ 599| | | | 600| ablkcipher| | ahash | 601| (ctr) | ---+ | (ghash) | 602+-----------+ | +-----------+ 603 | 604+-----------+ | (4) 605| | <--+ 606| cipher | 607| (aes) | 608+-----------+ 609]]> 610 </programlisting> 611 612 <para> 613 The following call sequence is applicable when the IPSEC layer 614 triggers an encryption operation with the esp_output function. During 615 configuration, the administrator set up the use of rfc4106(gcm(aes)) as 616 the cipher for ESP. The following call sequence is now depicted in the 617 ASCII art above: 618 </para> 619 620 <orderedlist> 621 <listitem> 622 <para> 623 esp_output() invokes crypto_aead_givencrypt() to trigger an encryption 624 operation of the GIVCIPHER implementation. 625 </para> 626 627 <para> 628 In case of GCM, the SEQIV implementation is registered as GIVCIPHER 629 in crypto_rfc4106_alloc(). 630 </para> 631 632 <para> 633 The SEQIV performs its operation to generate an IV where the core 634 function is seqiv_geniv(). 635 </para> 636 </listitem> 637 638 <listitem> 639 <para> 640 Now, SEQIV uses the AEAD API function calls to invoke the associated 641 AEAD cipher. In our case, during the instantiation of SEQIV, the 642 cipher handle for GCM is provided to SEQIV. This means that SEQIV 643 invokes AEAD cipher operations with the GCM cipher handle. 644 </para> 645 646 <para> 647 During instantiation of the GCM handle, the CTR(AES) and GHASH 648 ciphers are instantiated. The cipher handles for CTR(AES) and GHASH 649 are retained for later use. 650 </para> 651 652 <para> 653 The GCM implementation is responsible to invoke the CTR mode AES and 654 the GHASH cipher in the right manner to implement the GCM 655 specification. 656 </para> 657 </listitem> 658 659 <listitem> 660 <para> 661 The GCM AEAD cipher type implementation now invokes the ABLKCIPHER API 662 with the instantiated CTR(AES) cipher handle. 663 </para> 664 665 <para> 666 During instantiation of the CTR(AES) cipher, the CIPHER type 667 implementation of AES is instantiated. The cipher handle for AES is 668 retained. 669 </para> 670 671 <para> 672 That means that the ABLKCIPHER implementation of CTR(AES) only 673 implements the CTR block chaining mode. After performing the block 674 chaining operation, the CIPHER implementation of AES is invoked. 675 </para> 676 </listitem> 677 678 <listitem> 679 <para> 680 The ABLKCIPHER of CTR(AES) now invokes the CIPHER API with the AES 681 cipher handle to encrypt one block. 682 </para> 683 </listitem> 684 685 <listitem> 686 <para> 687 The GCM AEAD implementation also invokes the GHASH cipher 688 implementation via the AHASH API. 689 </para> 690 </listitem> 691 </orderedlist> 692 693 <para> 694 When the IPSEC layer triggers the esp_input() function, the same call 695 sequence is followed with the only difference that the operation starts 696 with step (2). 697 </para> 698 </sect2> 699 700 <sect2><title>Generic Block Cipher Structure</title> 701 <para> 702 Generic block ciphers follow the same concept as depicted with the ASCII 703 art picture above. 704 </para> 705 706 <para> 707 For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The 708 ASCII art picture above applies as well with the difference that only 709 step (4) is used and the ABLKCIPHER block chaining mode is CBC. 710 </para> 711 </sect2> 712 713 <sect2><title>Generic Keyed Message Digest Structure</title> 714 <para> 715 Keyed message digest implementations again follow the same concept as 716 depicted in the ASCII art picture above. 717 </para> 718 719 <para> 720 For example, HMAC(SHA256) is implemented with hmac.c and 721 sha256_generic.c. The following ASCII art illustrates the 722 implementation: 723 </para> 724 725 <programlisting> 726<![CDATA[ 727kernel crypto API | Caller 728 | 729+-----------+ (1) | 730| | <------------------ some_function 731| ahash | 732| (hmac) | ---+ 733+-----------+ | 734 | (2) 735+-----------+ | 736| | <--+ 737| shash | 738| (sha256) | 739+-----------+ 740]]> 741 </programlisting> 742 743 <para> 744 The following call sequence is applicable when a caller triggers 745 an HMAC operation: 746 </para> 747 748 <orderedlist> 749 <listitem> 750 <para> 751 The AHASH API functions are invoked by the caller. The HMAC 752 implementation performs its operation as needed. 753 </para> 754 755 <para> 756 During initialization of the HMAC cipher, the SHASH cipher type of 757 SHA256 is instantiated. The cipher handle for the SHA256 instance is 758 retained. 759 </para> 760 761 <para> 762 At one time, the HMAC implementation requires a SHA256 operation 763 where the SHA256 cipher handle is used. 764 </para> 765 </listitem> 766 767 <listitem> 768 <para> 769 The HMAC instance now invokes the SHASH API with the SHA256 770 cipher handle to calculate the message digest. 771 </para> 772 </listitem> 773 </orderedlist> 774 </sect2> 775 </sect1> 776 </chapter> 777 778 <chapter id="Development"><title>Developing Cipher Algorithms</title> 779 <sect1><title>Registering And Unregistering Transformation</title> 780 <para> 781 There are three distinct types of registration functions in 782 the Crypto API. One is used to register a generic cryptographic 783 transformation, while the other two are specific to HASH 784 transformations and COMPRESSion. We will discuss the latter 785 two in a separate chapter, here we will only look at the 786 generic ones. 787 </para> 788 789 <para> 790 Before discussing the register functions, the data structure 791 to be filled with each, struct crypto_alg, must be considered 792 -- see below for a description of this data structure. 793 </para> 794 795 <para> 796 The generic registration functions can be found in 797 include/linux/crypto.h and their definition can be seen below. 798 The former function registers a single transformation, while 799 the latter works on an array of transformation descriptions. 800 The latter is useful when registering transformations in bulk. 801 </para> 802 803 <programlisting> 804 int crypto_register_alg(struct crypto_alg *alg); 805 int crypto_register_algs(struct crypto_alg *algs, int count); 806 </programlisting> 807 808 <para> 809 The counterparts to those functions are listed below. 810 </para> 811 812 <programlisting> 813 int crypto_unregister_alg(struct crypto_alg *alg); 814 int crypto_unregister_algs(struct crypto_alg *algs, int count); 815 </programlisting> 816 817 <para> 818 Notice that both registration and unregistration functions 819 do return a value, so make sure to handle errors. A return 820 code of zero implies success. Any return code < 0 implies 821 an error. 822 </para> 823 824 <para> 825 The bulk registration / unregistration functions require 826 that struct crypto_alg is an array of count size. These 827 functions simply loop over that array and register / 828 unregister each individual algorithm. If an error occurs, 829 the loop is terminated at the offending algorithm definition. 830 That means, the algorithms prior to the offending algorithm 831 are successfully registered. Note, the caller has no way of 832 knowing which cipher implementations have successfully 833 registered. If this is important to know, the caller should 834 loop through the different implementations using the single 835 instance *_alg functions for each individual implementation. 836 </para> 837 </sect1> 838 839 <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title> 840 <para> 841 Example of transformations: aes, arc4, ... 842 </para> 843 844 <para> 845 This section describes the simplest of all transformation 846 implementations, that being the CIPHER type used for symmetric 847 ciphers. The CIPHER type is used for transformations which 848 operate on exactly one block at a time and there are no 849 dependencies between blocks at all. 850 </para> 851 852 <sect2><title>Registration specifics</title> 853 <para> 854 The registration of [CIPHER] algorithm is specific in that 855 struct crypto_alg field .cra_type is empty. The .cra_u.cipher 856 has to be filled in with proper callbacks to implement this 857 transformation. 858 </para> 859 860 <para> 861 See struct cipher_alg below. 862 </para> 863 </sect2> 864 865 <sect2><title>Cipher Definition With struct cipher_alg</title> 866 <para> 867 Struct cipher_alg defines a single block cipher. 868 </para> 869 870 <para> 871 Here are schematics of how these functions are called when 872 operated from other part of the kernel. Note that the 873 .cia_setkey() call might happen before or after any of these 874 schematics happen, but must not happen during any of these 875 are in-flight. 876 </para> 877 878 <para> 879 <programlisting> 880 KEY ---. PLAINTEXT ---. 881 v v 882 .cia_setkey() -> .cia_encrypt() 883 | 884 '-----> CIPHERTEXT 885 </programlisting> 886 </para> 887 888 <para> 889 Please note that a pattern where .cia_setkey() is called 890 multiple times is also valid: 891 </para> 892 893 <para> 894 <programlisting> 895 896 KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --. 897 v v v v 898 .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt() 899 | | 900 '---> CIPHERTEXT1 '---> CIPHERTEXT2 901 </programlisting> 902 </para> 903 904 </sect2> 905 </sect1> 906 907 <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title> 908 <para> 909 Example of transformations: cbc(aes), ecb(arc4), ... 910 </para> 911 912 <para> 913 This section describes the multi-block cipher transformation 914 implementations for both synchronous [BLKCIPHER] and 915 asynchronous [ABLKCIPHER] case. The multi-block ciphers are 916 used for transformations which operate on scatterlists of 917 data supplied to the transformation functions. They output 918 the result into a scatterlist of data as well. 919 </para> 920 921 <sect2><title>Registration Specifics</title> 922 923 <para> 924 The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms 925 is one of the most standard procedures throughout the crypto API. 926 </para> 927 928 <para> 929 Note, if a cipher implementation requires a proper alignment 930 of data, the caller should use the functions of 931 crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask() 932 respectively to identify a memory alignment mask. The kernel 933 crypto API is able to process requests that are unaligned. 934 This implies, however, additional overhead as the kernel 935 crypto API needs to perform the realignment of the data which 936 may imply moving of data. 937 </para> 938 </sect2> 939 940 <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title> 941 <para> 942 Struct blkcipher_alg defines a synchronous block cipher whereas 943 struct ablkcipher_alg defines an asynchronous block cipher. 944 </para> 945 946 <para> 947 Please refer to the single block cipher description for schematics 948 of the block cipher usage. The usage patterns are exactly the same 949 for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER]. 950 </para> 951 </sect2> 952 953 <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title> 954 <para> 955 There are a couple of specifics to the [ABLKCIPHER] interface. 956 </para> 957 958 <para> 959 First of all, some of the drivers will want to use the 960 Generic ScatterWalk in case the hardware needs to be fed 961 separate chunks of the scatterlist which contains the 962 plaintext and will contain the ciphertext. Please refer 963 to the ScatterWalk interface offered by the Linux kernel 964 scatter / gather list implementation. 965 </para> 966 </sect2> 967 </sect1> 968 969 <sect1><title>Hashing [HASH]</title> 970 971 <para> 972 Example of transformations: crc32, md5, sha1, sha256,... 973 </para> 974 975 <sect2><title>Registering And Unregistering The Transformation</title> 976 977 <para> 978 There are multiple ways to register a HASH transformation, 979 depending on whether the transformation is synchronous [SHASH] 980 or asynchronous [AHASH] and the amount of HASH transformations 981 we are registering. You can find the prototypes defined in 982 include/crypto/internal/hash.h: 983 </para> 984 985 <programlisting> 986 int crypto_register_ahash(struct ahash_alg *alg); 987 988 int crypto_register_shash(struct shash_alg *alg); 989 int crypto_register_shashes(struct shash_alg *algs, int count); 990 </programlisting> 991 992 <para> 993 The respective counterparts for unregistering the HASH 994 transformation are as follows: 995 </para> 996 997 <programlisting> 998 int crypto_unregister_ahash(struct ahash_alg *alg); 999 1000 int crypto_unregister_shash(struct shash_alg *alg); 1001 int crypto_unregister_shashes(struct shash_alg *algs, int count); 1002 </programlisting> 1003 </sect2> 1004 1005 <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title> 1006 <para> 1007 Here are schematics of how these functions are called when 1008 operated from other part of the kernel. Note that the .setkey() 1009 call might happen before or after any of these schematics happen, 1010 but must not happen during any of these are in-flight. Please note 1011 that calling .init() followed immediately by .finish() is also a 1012 perfectly valid transformation. 1013 </para> 1014 1015 <programlisting> 1016 I) DATA -----------. 1017 v 1018 .init() -> .update() -> .final() ! .update() might not be called 1019 ^ | | at all in this scenario. 1020 '----' '---> HASH 1021 1022 II) DATA -----------.-----------. 1023 v v 1024 .init() -> .update() -> .finup() ! .update() may not be called 1025 ^ | | at all in this scenario. 1026 '----' '---> HASH 1027 1028 III) DATA -----------. 1029 v 1030 .digest() ! The entire process is handled 1031 | by the .digest() call. 1032 '---------------> HASH 1033 </programlisting> 1034 1035 <para> 1036 Here is a schematic of how the .export()/.import() functions are 1037 called when used from another part of the kernel. 1038 </para> 1039 1040 <programlisting> 1041 KEY--. DATA--. 1042 v v ! .update() may not be called 1043 .setkey() -> .init() -> .update() -> .export() at all in this scenario. 1044 ^ | | 1045 '-----' '--> PARTIAL_HASH 1046 1047 ----------- other transformations happen here ----------- 1048 1049 PARTIAL_HASH--. DATA1--. 1050 v v 1051 .import -> .update() -> .final() ! .update() may not be called 1052 ^ | | at all in this scenario. 1053 '----' '--> HASH1 1054 1055 PARTIAL_HASH--. DATA2-. 1056 v v 1057 .import -> .finup() 1058 | 1059 '---------------> HASH2 1060 </programlisting> 1061 </sect2> 1062 1063 <sect2><title>Specifics Of Asynchronous HASH Transformation</title> 1064 <para> 1065 Some of the drivers will want to use the Generic ScatterWalk 1066 in case the implementation needs to be fed separate chunks of the 1067 scatterlist which contains the input data. The buffer containing 1068 the resulting hash will always be properly aligned to 1069 .cra_alignmask so there is no need to worry about this. 1070 </para> 1071 </sect2> 1072 </sect1> 1073 </chapter> 1074 1075 <chapter id="User"><title>User Space Interface</title> 1076 <sect1><title>Introduction</title> 1077 <para> 1078 The concepts of the kernel crypto API visible to kernel space is fully 1079 applicable to the user space interface as well. Therefore, the kernel 1080 crypto API high level discussion for the in-kernel use cases applies 1081 here as well. 1082 </para> 1083 1084 <para> 1085 The major difference, however, is that user space can only act as a 1086 consumer and never as a provider of a transformation or cipher algorithm. 1087 </para> 1088 1089 <para> 1090 The following covers the user space interface exported by the kernel 1091 crypto API. A working example of this description is libkcapi that 1092 can be obtained from [1]. That library can be used by user space 1093 applications that require cryptographic services from the kernel. 1094 </para> 1095 1096 <para> 1097 Some details of the in-kernel kernel crypto API aspects do not 1098 apply to user space, however. This includes the difference between 1099 synchronous and asynchronous invocations. The user space API call 1100 is fully synchronous. 1101 </para> 1102 1103 <para> 1104 [1] http://www.chronox.de/libkcapi.html 1105 </para> 1106 1107 </sect1> 1108 1109 <sect1><title>User Space API General Remarks</title> 1110 <para> 1111 The kernel crypto API is accessible from user space. Currently, 1112 the following ciphers are accessible: 1113 </para> 1114 1115 <itemizedlist> 1116 <listitem> 1117 <para>Message digest including keyed message digest (HMAC, CMAC)</para> 1118 </listitem> 1119 1120 <listitem> 1121 <para>Symmetric ciphers</para> 1122 </listitem> 1123 1124 <listitem> 1125 <para>AEAD ciphers</para> 1126 </listitem> 1127 1128 <listitem> 1129 <para>Random Number Generators</para> 1130 </listitem> 1131 </itemizedlist> 1132 1133 <para> 1134 The interface is provided via socket type using the type AF_ALG. 1135 In addition, the setsockopt option type is SOL_ALG. In case the 1136 user space header files do not export these flags yet, use the 1137 following macros: 1138 </para> 1139 1140 <programlisting> 1141#ifndef AF_ALG 1142#define AF_ALG 38 1143#endif 1144#ifndef SOL_ALG 1145#define SOL_ALG 279 1146#endif 1147 </programlisting> 1148 1149 <para> 1150 A cipher is accessed with the same name as done for the in-kernel 1151 API calls. This includes the generic vs. unique naming schema for 1152 ciphers as well as the enforcement of priorities for generic names. 1153 </para> 1154 1155 <para> 1156 To interact with the kernel crypto API, a socket must be 1157 created by the user space application. User space invokes the cipher 1158 operation with the send()/write() system call family. The result of the 1159 cipher operation is obtained with the read()/recv() system call family. 1160 </para> 1161 1162 <para> 1163 The following API calls assume that the socket descriptor 1164 is already opened by the user space application and discusses only 1165 the kernel crypto API specific invocations. 1166 </para> 1167 1168 <para> 1169 To initialize the socket interface, the following sequence has to 1170 be performed by the consumer: 1171 </para> 1172 1173 <orderedlist> 1174 <listitem> 1175 <para> 1176 Create a socket of type AF_ALG with the struct sockaddr_alg 1177 parameter specified below for the different cipher types. 1178 </para> 1179 </listitem> 1180 1181 <listitem> 1182 <para> 1183 Invoke bind with the socket descriptor 1184 </para> 1185 </listitem> 1186 1187 <listitem> 1188 <para> 1189 Invoke accept with the socket descriptor. The accept system call 1190 returns a new file descriptor that is to be used to interact with 1191 the particular cipher instance. When invoking send/write or recv/read 1192 system calls to send data to the kernel or obtain data from the 1193 kernel, the file descriptor returned by accept must be used. 1194 </para> 1195 </listitem> 1196 </orderedlist> 1197 </sect1> 1198 1199 <sect1><title>In-place Cipher operation</title> 1200 <para> 1201 Just like the in-kernel operation of the kernel crypto API, the user 1202 space interface allows the cipher operation in-place. That means that 1203 the input buffer used for the send/write system call and the output 1204 buffer used by the read/recv system call may be one and the same. 1205 This is of particular interest for symmetric cipher operations where a 1206 copying of the output data to its final destination can be avoided. 1207 </para> 1208 1209 <para> 1210 If a consumer on the other hand wants to maintain the plaintext and 1211 the ciphertext in different memory locations, all a consumer needs 1212 to do is to provide different memory pointers for the encryption and 1213 decryption operation. 1214 </para> 1215 </sect1> 1216 1217 <sect1><title>Message Digest API</title> 1218 <para> 1219 The message digest type to be used for the cipher operation is 1220 selected when invoking the bind syscall. bind requires the caller 1221 to provide a filled struct sockaddr data structure. This data 1222 structure must be filled as follows: 1223 </para> 1224 1225 <programlisting> 1226struct sockaddr_alg sa = { 1227 .salg_family = AF_ALG, 1228 .salg_type = "hash", /* this selects the hash logic in the kernel */ 1229 .salg_name = "sha1" /* this is the cipher name */ 1230}; 1231 </programlisting> 1232 1233 <para> 1234 The salg_type value "hash" applies to message digests and keyed 1235 message digests. Though, a keyed message digest is referenced by 1236 the appropriate salg_name. Please see below for the setsockopt 1237 interface that explains how the key can be set for a keyed message 1238 digest. 1239 </para> 1240 1241 <para> 1242 Using the send() system call, the application provides the data that 1243 should be processed with the message digest. The send system call 1244 allows the following flags to be specified: 1245 </para> 1246 1247 <itemizedlist> 1248 <listitem> 1249 <para> 1250 MSG_MORE: If this flag is set, the send system call acts like a 1251 message digest update function where the final hash is not 1252 yet calculated. If the flag is not set, the send system call 1253 calculates the final message digest immediately. 1254 </para> 1255 </listitem> 1256 </itemizedlist> 1257 1258 <para> 1259 With the recv() system call, the application can read the message 1260 digest from the kernel crypto API. If the buffer is too small for the 1261 message digest, the flag MSG_TRUNC is set by the kernel. 1262 </para> 1263 1264 <para> 1265 In order to set a message digest key, the calling application must use 1266 the setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC 1267 operation is performed without the initial HMAC state change caused by 1268 the key. 1269 </para> 1270 </sect1> 1271 1272 <sect1><title>Symmetric Cipher API</title> 1273 <para> 1274 The operation is very similar to the message digest discussion. 1275 During initialization, the struct sockaddr data structure must be 1276 filled as follows: 1277 </para> 1278 1279 <programlisting> 1280struct sockaddr_alg sa = { 1281 .salg_family = AF_ALG, 1282 .salg_type = "skcipher", /* this selects the symmetric cipher */ 1283 .salg_name = "cbc(aes)" /* this is the cipher name */ 1284}; 1285 </programlisting> 1286 1287 <para> 1288 Before data can be sent to the kernel using the write/send system 1289 call family, the consumer must set the key. The key setting is 1290 described with the setsockopt invocation below. 1291 </para> 1292 1293 <para> 1294 Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is 1295 specified with the data structure provided by the sendmsg() system call. 1296 </para> 1297 1298 <para> 1299 The sendmsg system call parameter of struct msghdr is embedded into the 1300 struct cmsghdr data structure. See recv(2) and cmsg(3) for more 1301 information on how the cmsghdr data structure is used together with the 1302 send/recv system call family. That cmsghdr data structure holds the 1303 following information specified with a separate header instances: 1304 </para> 1305 1306 <itemizedlist> 1307 <listitem> 1308 <para> 1309 specification of the cipher operation type with one of these flags: 1310 </para> 1311 <itemizedlist> 1312 <listitem> 1313 <para>ALG_OP_ENCRYPT - encryption of data</para> 1314 </listitem> 1315 <listitem> 1316 <para>ALG_OP_DECRYPT - decryption of data</para> 1317 </listitem> 1318 </itemizedlist> 1319 </listitem> 1320 1321 <listitem> 1322 <para> 1323 specification of the IV information marked with the flag ALG_SET_IV 1324 </para> 1325 </listitem> 1326 </itemizedlist> 1327 1328 <para> 1329 The send system call family allows the following flag to be specified: 1330 </para> 1331 1332 <itemizedlist> 1333 <listitem> 1334 <para> 1335 MSG_MORE: If this flag is set, the send system call acts like a 1336 cipher update function where more input data is expected 1337 with a subsequent invocation of the send system call. 1338 </para> 1339 </listitem> 1340 </itemizedlist> 1341 1342 <para> 1343 Note: The kernel reports -EINVAL for any unexpected data. The caller 1344 must make sure that all data matches the constraints given in 1345 /proc/crypto for the selected cipher. 1346 </para> 1347 1348 <para> 1349 With the recv() system call, the application can read the result of 1350 the cipher operation from the kernel crypto API. The output buffer 1351 must be at least as large as to hold all blocks of the encrypted or 1352 decrypted data. If the output data size is smaller, only as many 1353 blocks are returned that fit into that output buffer size. 1354 </para> 1355 </sect1> 1356 1357 <sect1><title>AEAD Cipher API</title> 1358 <para> 1359 The operation is very similar to the symmetric cipher discussion. 1360 During initialization, the struct sockaddr data structure must be 1361 filled as follows: 1362 </para> 1363 1364 <programlisting> 1365struct sockaddr_alg sa = { 1366 .salg_family = AF_ALG, 1367 .salg_type = "aead", /* this selects the symmetric cipher */ 1368 .salg_name = "gcm(aes)" /* this is the cipher name */ 1369}; 1370 </programlisting> 1371 1372 <para> 1373 Before data can be sent to the kernel using the write/send system 1374 call family, the consumer must set the key. The key setting is 1375 described with the setsockopt invocation below. 1376 </para> 1377 1378 <para> 1379 In addition, before data can be sent to the kernel using the 1380 write/send system call family, the consumer must set the authentication 1381 tag size. To set the authentication tag size, the caller must use the 1382 setsockopt invocation described below. 1383 </para> 1384 1385 <para> 1386 Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is 1387 specified with the data structure provided by the sendmsg() system call. 1388 </para> 1389 1390 <para> 1391 The sendmsg system call parameter of struct msghdr is embedded into the 1392 struct cmsghdr data structure. See recv(2) and cmsg(3) for more 1393 information on how the cmsghdr data structure is used together with the 1394 send/recv system call family. That cmsghdr data structure holds the 1395 following information specified with a separate header instances: 1396 </para> 1397 1398 <itemizedlist> 1399 <listitem> 1400 <para> 1401 specification of the cipher operation type with one of these flags: 1402 </para> 1403 <itemizedlist> 1404 <listitem> 1405 <para>ALG_OP_ENCRYPT - encryption of data</para> 1406 </listitem> 1407 <listitem> 1408 <para>ALG_OP_DECRYPT - decryption of data</para> 1409 </listitem> 1410 </itemizedlist> 1411 </listitem> 1412 1413 <listitem> 1414 <para> 1415 specification of the IV information marked with the flag ALG_SET_IV 1416 </para> 1417 </listitem> 1418 1419 <listitem> 1420 <para> 1421 specification of the associated authentication data (AAD) with the 1422 flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together 1423 with the plaintext / ciphertext. See below for the memory structure. 1424 </para> 1425 </listitem> 1426 </itemizedlist> 1427 1428 <para> 1429 The send system call family allows the following flag to be specified: 1430 </para> 1431 1432 <itemizedlist> 1433 <listitem> 1434 <para> 1435 MSG_MORE: If this flag is set, the send system call acts like a 1436 cipher update function where more input data is expected 1437 with a subsequent invocation of the send system call. 1438 </para> 1439 </listitem> 1440 </itemizedlist> 1441 1442 <para> 1443 Note: The kernel reports -EINVAL for any unexpected data. The caller 1444 must make sure that all data matches the constraints given in 1445 /proc/crypto for the selected cipher. 1446 </para> 1447 1448 <para> 1449 With the recv() system call, the application can read the result of 1450 the cipher operation from the kernel crypto API. The output buffer 1451 must be at least as large as defined with the memory structure below. 1452 If the output data size is smaller, the cipher operation is not performed. 1453 </para> 1454 1455 <para> 1456 The authenticated decryption operation may indicate an integrity error. 1457 Such breach in integrity is marked with the -EBADMSG error code. 1458 </para> 1459 1460 <sect2><title>AEAD Memory Structure</title> 1461 <para> 1462 The AEAD cipher operates with the following information that 1463 is communicated between user and kernel space as one data stream: 1464 </para> 1465 1466 <itemizedlist> 1467 <listitem> 1468 <para>plaintext or ciphertext</para> 1469 </listitem> 1470 1471 <listitem> 1472 <para>associated authentication data (AAD)</para> 1473 </listitem> 1474 1475 <listitem> 1476 <para>authentication tag</para> 1477 </listitem> 1478 </itemizedlist> 1479 1480 <para> 1481 The sizes of the AAD and the authentication tag are provided with 1482 the sendmsg and setsockopt calls (see there). As the kernel knows 1483 the size of the entire data stream, the kernel is now able to 1484 calculate the right offsets of the data components in the data 1485 stream. 1486 </para> 1487 1488 <para> 1489 The user space caller must arrange the aforementioned information 1490 in the following order: 1491 </para> 1492 1493 <itemizedlist> 1494 <listitem> 1495 <para> 1496 AEAD encryption input: AAD || plaintext 1497 </para> 1498 </listitem> 1499 1500 <listitem> 1501 <para> 1502 AEAD decryption input: AAD || ciphertext || authentication tag 1503 </para> 1504 </listitem> 1505 </itemizedlist> 1506 1507 <para> 1508 The output buffer the user space caller provides must be at least as 1509 large to hold the following data: 1510 </para> 1511 1512 <itemizedlist> 1513 <listitem> 1514 <para> 1515 AEAD encryption output: ciphertext || authentication tag 1516 </para> 1517 </listitem> 1518 1519 <listitem> 1520 <para> 1521 AEAD decryption output: plaintext 1522 </para> 1523 </listitem> 1524 </itemizedlist> 1525 </sect2> 1526 </sect1> 1527 1528 <sect1><title>Random Number Generator API</title> 1529 <para> 1530 Again, the operation is very similar to the other APIs. 1531 During initialization, the struct sockaddr data structure must be 1532 filled as follows: 1533 </para> 1534 1535 <programlisting> 1536struct sockaddr_alg sa = { 1537 .salg_family = AF_ALG, 1538 .salg_type = "rng", /* this selects the symmetric cipher */ 1539 .salg_name = "drbg_nopr_sha256" /* this is the cipher name */ 1540}; 1541 </programlisting> 1542 1543 <para> 1544 Depending on the RNG type, the RNG must be seeded. The seed is provided 1545 using the setsockopt interface to set the key. For example, the 1546 ansi_cprng requires a seed. The DRBGs do not require a seed, but 1547 may be seeded. 1548 </para> 1549 1550 <para> 1551 Using the read()/recvmsg() system calls, random numbers can be obtained. 1552 The kernel generates at most 128 bytes in one call. If user space 1553 requires more data, multiple calls to read()/recvmsg() must be made. 1554 </para> 1555 1556 <para> 1557 WARNING: The user space caller may invoke the initially mentioned 1558 accept system call multiple times. In this case, the returned file 1559 descriptors have the same state. 1560 </para> 1561 1562 </sect1> 1563 1564 <sect1><title>Zero-Copy Interface</title> 1565 <para> 1566 In addition to the send/write/read/recv system call familty, the AF_ALG 1567 interface can be accessed with the zero-copy interface of splice/vmsplice. 1568 As the name indicates, the kernel tries to avoid a copy operation into 1569 kernel space. 1570 </para> 1571 1572 <para> 1573 The zero-copy operation requires data to be aligned at the page boundary. 1574 Non-aligned data can be used as well, but may require more operations of 1575 the kernel which would defeat the speed gains obtained from the zero-copy 1576 interface. 1577 </para> 1578 1579 <para> 1580 The system-interent limit for the size of one zero-copy operation is 1581 16 pages. If more data is to be sent to AF_ALG, user space must slice 1582 the input into segments with a maximum size of 16 pages. 1583 </para> 1584 1585 <para> 1586 Zero-copy can be used with the following code example (a complete working 1587 example is provided with libkcapi): 1588 </para> 1589 1590 <programlisting> 1591int pipes[2]; 1592 1593pipe(pipes); 1594/* input data in iov */ 1595vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT); 1596/* opfd is the file descriptor returned from accept() system call */ 1597splice(pipes[0], NULL, opfd, NULL, ret, 0); 1598read(opfd, out, outlen); 1599 </programlisting> 1600 1601 </sect1> 1602 1603 <sect1><title>Setsockopt Interface</title> 1604 <para> 1605 In addition to the read/recv and send/write system call handling 1606 to send and retrieve data subject to the cipher operation, a consumer 1607 also needs to set the additional information for the cipher operation. 1608 This additional information is set using the setsockopt system call 1609 that must be invoked with the file descriptor of the open cipher 1610 (i.e. the file descriptor returned by the accept system call). 1611 </para> 1612 1613 <para> 1614 Each setsockopt invocation must use the level SOL_ALG. 1615 </para> 1616 1617 <para> 1618 The setsockopt interface allows setting the following data using 1619 the mentioned optname: 1620 </para> 1621 1622 <itemizedlist> 1623 <listitem> 1624 <para> 1625 ALG_SET_KEY -- Setting the key. Key setting is applicable to: 1626 </para> 1627 <itemizedlist> 1628 <listitem> 1629 <para>the skcipher cipher type (symmetric ciphers)</para> 1630 </listitem> 1631 <listitem> 1632 <para>the hash cipher type (keyed message digests)</para> 1633 </listitem> 1634 <listitem> 1635 <para>the AEAD cipher type</para> 1636 </listitem> 1637 <listitem> 1638 <para>the RNG cipher type to provide the seed</para> 1639 </listitem> 1640 </itemizedlist> 1641 </listitem> 1642 1643 <listitem> 1644 <para> 1645 ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size 1646 for AEAD ciphers. For a encryption operation, the authentication 1647 tag of the given size will be generated. For a decryption operation, 1648 the provided ciphertext is assumed to contain an authentication tag 1649 of the given size (see section about AEAD memory layout below). 1650 </para> 1651 </listitem> 1652 </itemizedlist> 1653 1654 </sect1> 1655 1656 <sect1><title>User space API example</title> 1657 <para> 1658 Please see [1] for libkcapi which provides an easy-to-use wrapper 1659 around the aforementioned Netlink kernel interface. [1] also contains 1660 a test application that invokes all libkcapi API calls. 1661 </para> 1662 1663 <para> 1664 [1] http://www.chronox.de/libkcapi.html 1665 </para> 1666 1667 </sect1> 1668 1669 </chapter> 1670 1671 <chapter id="API"><title>Programming Interface</title> 1672 <sect1><title>Block Cipher Context Data Structures</title> 1673<para> 1674 </para><para> 1675 These data structures define the operating context for each block cipher 1676 type. 1677</para> 1678 1679<refentry id="API-struct-aead-request"> 1680<refentryinfo> 1681 <title>LINUX</title> 1682 <productname>Kernel Hackers Manual</productname> 1683 <date>July 2017</date> 1684</refentryinfo> 1685<refmeta> 1686 <refentrytitle><phrase>struct aead_request</phrase></refentrytitle> 1687 <manvolnum>9</manvolnum> 1688 <refmiscinfo class="version">4.1.27</refmiscinfo> 1689</refmeta> 1690<refnamediv> 1691 <refname>struct aead_request</refname> 1692 <refpurpose> 1693 AEAD request 1694 </refpurpose> 1695</refnamediv> 1696<refsynopsisdiv> 1697 <title>Synopsis</title> 1698 <programlisting> 1699struct aead_request { 1700 struct crypto_async_request base; 1701 unsigned int assoclen; 1702 unsigned int cryptlen; 1703 u8 * iv; 1704 struct scatterlist * assoc; 1705 struct scatterlist * src; 1706 struct scatterlist * dst; 1707 void * __ctx[] CRYPTO_MINALIGN_ATTR; 1708}; </programlisting> 1709</refsynopsisdiv> 1710 <refsect1> 1711 <title>Members</title> 1712 <variablelist> 1713 <varlistentry> <term>base</term> 1714 <listitem><para> 1715Common attributes for async crypto requests 1716 </para></listitem> 1717 </varlistentry> 1718 <varlistentry> <term>assoclen</term> 1719 <listitem><para> 1720Length in bytes of associated data for authentication 1721 </para></listitem> 1722 </varlistentry> 1723 <varlistentry> <term>cryptlen</term> 1724 <listitem><para> 1725Length of data to be encrypted or decrypted 1726 </para></listitem> 1727 </varlistentry> 1728 <varlistentry> <term>iv</term> 1729 <listitem><para> 1730Initialisation vector 1731 </para></listitem> 1732 </varlistentry> 1733 <varlistentry> <term>assoc</term> 1734 <listitem><para> 1735Associated data 1736 </para></listitem> 1737 </varlistentry> 1738 <varlistentry> <term>src</term> 1739 <listitem><para> 1740Source data 1741 </para></listitem> 1742 </varlistentry> 1743 <varlistentry> <term>dst</term> 1744 <listitem><para> 1745Destination data 1746 </para></listitem> 1747 </varlistentry> 1748 <varlistentry> <term>__ctx[] CRYPTO_MINALIGN_ATTR</term> 1749 <listitem><para> 1750Start of private context data 1751 </para></listitem> 1752 </varlistentry> 1753 </variablelist> 1754 </refsect1> 1755</refentry> 1756 1757 </sect1> 1758 <sect1><title>Block Cipher Algorithm Definitions</title> 1759<para> 1760 </para><para> 1761 These data structures define modular crypto algorithm implementations, 1762 managed via <function>crypto_register_alg</function> and <function>crypto_unregister_alg</function>. 1763</para> 1764 1765<refentry id="API-struct-crypto-alg"> 1766<refentryinfo> 1767 <title>LINUX</title> 1768 <productname>Kernel Hackers Manual</productname> 1769 <date>July 2017</date> 1770</refentryinfo> 1771<refmeta> 1772 <refentrytitle><phrase>struct crypto_alg</phrase></refentrytitle> 1773 <manvolnum>9</manvolnum> 1774 <refmiscinfo class="version">4.1.27</refmiscinfo> 1775</refmeta> 1776<refnamediv> 1777 <refname>struct crypto_alg</refname> 1778 <refpurpose> 1779 definition of a cryptograpic cipher algorithm 1780 </refpurpose> 1781</refnamediv> 1782<refsynopsisdiv> 1783 <title>Synopsis</title> 1784 <programlisting> 1785struct crypto_alg { 1786 struct list_head cra_list; 1787 struct list_head cra_users; 1788 u32 cra_flags; 1789 unsigned int cra_blocksize; 1790 unsigned int cra_ctxsize; 1791 unsigned int cra_alignmask; 1792 int cra_priority; 1793 atomic_t cra_refcnt; 1794 char cra_name[CRYPTO_MAX_ALG_NAME]; 1795 char cra_driver_name[CRYPTO_MAX_ALG_NAME]; 1796 const struct crypto_type * cra_type; 1797 union cra_u; 1798 int (* cra_init) (struct crypto_tfm *tfm); 1799 void (* cra_exit) (struct crypto_tfm *tfm); 1800 void (* cra_destroy) (struct crypto_alg *alg); 1801 struct module * cra_module; 1802}; </programlisting> 1803</refsynopsisdiv> 1804 <refsect1> 1805 <title>Members</title> 1806 <variablelist> 1807 <varlistentry> <term>cra_list</term> 1808 <listitem><para> 1809internally used 1810 </para></listitem> 1811 </varlistentry> 1812 <varlistentry> <term>cra_users</term> 1813 <listitem><para> 1814internally used 1815 </para></listitem> 1816 </varlistentry> 1817 <varlistentry> <term>cra_flags</term> 1818 <listitem><para> 1819Flags describing this transformation. See include/linux/crypto.h 1820CRYPTO_ALG_* flags for the flags which go in here. Those are 1821used for fine-tuning the description of the transformation 1822algorithm. 1823 </para></listitem> 1824 </varlistentry> 1825 <varlistentry> <term>cra_blocksize</term> 1826 <listitem><para> 1827Minimum block size of this transformation. The size in bytes 1828of the smallest possible unit which can be transformed with 1829this algorithm. The users must respect this value. 1830In case of HASH transformation, it is possible for a smaller 1831block than <parameter>cra_blocksize</parameter> to be passed to the crypto API for 1832transformation, in case of any other transformation type, an 1833error will be returned upon any attempt to transform smaller 1834than <parameter>cra_blocksize</parameter> chunks. 1835 </para></listitem> 1836 </varlistentry> 1837 <varlistentry> <term>cra_ctxsize</term> 1838 <listitem><para> 1839Size of the operational context of the transformation. This 1840value informs the kernel crypto API about the memory size 1841needed to be allocated for the transformation context. 1842 </para></listitem> 1843 </varlistentry> 1844 <varlistentry> <term>cra_alignmask</term> 1845 <listitem><para> 1846Alignment mask for the input and output data buffer. The data 1847buffer containing the input data for the algorithm must be 1848aligned to this alignment mask. The data buffer for the 1849output data must be aligned to this alignment mask. Note that 1850the Crypto API will do the re-alignment in software, but 1851only under special conditions and there is a performance hit. 1852The re-alignment happens at these occasions for different 1853 </para></listitem> 1854 </varlistentry> 1855 <varlistentry> <term>cra_priority</term> 1856 <listitem><para> 1857Priority of this transformation implementation. In case 1858multiple transformations with same <parameter>cra_name</parameter> are available to 1859the Crypto API, the kernel will use the one with highest 1860<parameter>cra_priority</parameter>. 1861 </para></listitem> 1862 </varlistentry> 1863 <varlistentry> <term>cra_refcnt</term> 1864 <listitem><para> 1865internally used 1866 </para></listitem> 1867 </varlistentry> 1868 <varlistentry> <term>cra_name[CRYPTO_MAX_ALG_NAME]</term> 1869 <listitem><para> 1870Generic name (usable by multiple implementations) of the 1871transformation algorithm. This is the name of the transformation 1872itself. This field is used by the kernel when looking up the 1873providers of particular transformation. 1874 </para></listitem> 1875 </varlistentry> 1876 <varlistentry> <term>cra_driver_name[CRYPTO_MAX_ALG_NAME]</term> 1877 <listitem><para> 1878Unique name of the transformation provider. This is the 1879name of the provider of the transformation. This can be any 1880arbitrary value, but in the usual case, this contains the 1881name of the chip or provider and the name of the 1882transformation algorithm. 1883 </para></listitem> 1884 </varlistentry> 1885 <varlistentry> <term>cra_type</term> 1886 <listitem><para> 1887Type of the cryptographic transformation. This is a pointer to 1888struct crypto_type, which implements callbacks common for all 1889trasnformation types. There are multiple options: 1890<structname>crypto_blkcipher_type</structname>, <structname>crypto_ablkcipher_type</structname>, 1891<structname>crypto_ahash_type</structname>, <structname>crypto_aead_type</structname>, <structname>crypto_rng_type</structname>. 1892This field might be empty. In that case, there are no common 1893callbacks. This is the case for: cipher, compress, shash. 1894 </para></listitem> 1895 </varlistentry> 1896 <varlistentry> <term>cra_u</term> 1897 <listitem><para> 1898Callbacks implementing the transformation. This is a union of 1899multiple structures. Depending on the type of transformation selected 1900by <parameter>cra_type</parameter> and <parameter>cra_flags</parameter> above, the associated structure must be 1901filled with callbacks. This field might be empty. This is the case 1902for ahash, shash. 1903 </para></listitem> 1904 </varlistentry> 1905 <varlistentry> <term>cra_init</term> 1906 <listitem><para> 1907Initialize the cryptographic transformation object. This function 1908is used to initialize the cryptographic transformation object. 1909This function is called only once at the instantiation time, right 1910after the transformation context was allocated. In case the 1911cryptographic hardware has some special requirements which need to 1912be handled by software, this function shall check for the precise 1913requirement of the transformation and put any software fallbacks 1914in place. 1915 </para></listitem> 1916 </varlistentry> 1917 <varlistentry> <term>cra_exit</term> 1918 <listitem><para> 1919Deinitialize the cryptographic transformation object. This is a 1920counterpart to <parameter>cra_init</parameter>, used to remove various changes set in 1921<parameter>cra_init</parameter>. 1922 </para></listitem> 1923 </varlistentry> 1924 <varlistentry> <term>cra_destroy</term> 1925 <listitem><para> 1926internally used 1927 </para></listitem> 1928 </varlistentry> 1929 <varlistentry> <term>cra_module</term> 1930 <listitem><para> 1931Owner of this transformation implementation. Set to THIS_MODULE 1932 </para></listitem> 1933 </varlistentry> 1934 </variablelist> 1935 </refsect1> 1936<refsect1> 1937<title>Description</title> 1938<para> 1939 The struct crypto_alg describes a generic Crypto API algorithm and is common 1940 for all of the transformations. Any variable not documented here shall not 1941 be used by a cipher implementation as it is internal to the Crypto API. 1942</para> 1943</refsect1> 1944</refentry> 1945 1946<refentry id="API-struct-ablkcipher-alg"> 1947<refentryinfo> 1948 <title>LINUX</title> 1949 <productname>Kernel Hackers Manual</productname> 1950 <date>July 2017</date> 1951</refentryinfo> 1952<refmeta> 1953 <refentrytitle><phrase>struct ablkcipher_alg</phrase></refentrytitle> 1954 <manvolnum>9</manvolnum> 1955 <refmiscinfo class="version">4.1.27</refmiscinfo> 1956</refmeta> 1957<refnamediv> 1958 <refname>struct ablkcipher_alg</refname> 1959 <refpurpose> 1960 asynchronous block cipher definition 1961 </refpurpose> 1962</refnamediv> 1963<refsynopsisdiv> 1964 <title>Synopsis</title> 1965 <programlisting> 1966struct ablkcipher_alg { 1967 int (* setkey) (struct crypto_ablkcipher *tfm, const u8 *key,unsigned int keylen); 1968 int (* encrypt) (struct ablkcipher_request *req); 1969 int (* decrypt) (struct ablkcipher_request *req); 1970 int (* givencrypt) (struct skcipher_givcrypt_request *req); 1971 int (* givdecrypt) (struct skcipher_givcrypt_request *req); 1972 const char * geniv; 1973 unsigned int min_keysize; 1974 unsigned int max_keysize; 1975 unsigned int ivsize; 1976}; </programlisting> 1977</refsynopsisdiv> 1978 <refsect1> 1979 <title>Members</title> 1980 <variablelist> 1981 <varlistentry> <term>setkey</term> 1982 <listitem><para> 1983Set key for the transformation. This function is used to either 1984program a supplied key into the hardware or store the key in the 1985transformation context for programming it later. Note that this 1986function does modify the transformation context. This function can 1987be called multiple times during the existence of the transformation 1988object, so one must make sure the key is properly reprogrammed into 1989the hardware. This function is also responsible for checking the key 1990length for validity. In case a software fallback was put in place in 1991the <parameter>cra_init</parameter> call, this function might need to use the fallback if 1992the algorithm doesn't support all of the key sizes. 1993 </para></listitem> 1994 </varlistentry> 1995 <varlistentry> <term>encrypt</term> 1996 <listitem><para> 1997Encrypt a scatterlist of blocks. This function is used to encrypt 1998the supplied scatterlist containing the blocks of data. The crypto 1999API consumer is responsible for aligning the entries of the 2000scatterlist properly and making sure the chunks are correctly 2001sized. In case a software fallback was put in place in the 2002<parameter>cra_init</parameter> call, this function might need to use the fallback if 2003the algorithm doesn't support all of the key sizes. In case the 2004key was stored in transformation context, the key might need to be 2005re-programmed into the hardware in this function. This function 2006shall not modify the transformation context, as this function may 2007be called in parallel with the same transformation object. 2008 </para></listitem> 2009 </varlistentry> 2010 <varlistentry> <term>decrypt</term> 2011 <listitem><para> 2012Decrypt a single block. This is a reverse counterpart to <parameter>encrypt</parameter> 2013and the conditions are exactly the same. 2014 </para></listitem> 2015 </varlistentry> 2016 <varlistentry> <term>givencrypt</term> 2017 <listitem><para> 2018Update the IV for encryption. With this function, a cipher 2019implementation may provide the function on how to update the IV 2020for encryption. 2021 </para></listitem> 2022 </varlistentry> 2023 <varlistentry> <term>givdecrypt</term> 2024 <listitem><para> 2025Update the IV for decryption. This is the reverse of 2026<parameter>givencrypt</parameter> . 2027 </para></listitem> 2028 </varlistentry> 2029 <varlistentry> <term>geniv</term> 2030 <listitem><para> 2031The transformation implementation may use an <quote>IV generator</quote> provided 2032by the kernel crypto API. Several use cases have a predefined 2033approach how IVs are to be updated. For such use cases, the kernel 2034crypto API provides ready-to-use implementations that can be 2035referenced with this variable. 2036 </para></listitem> 2037 </varlistentry> 2038 <varlistentry> <term>min_keysize</term> 2039 <listitem><para> 2040Minimum key size supported by the transformation. This is the 2041smallest key length supported by this transformation algorithm. 2042This must be set to one of the pre-defined values as this is 2043not hardware specific. Possible values for this field can be 2044found via git grep <quote>_MIN_KEY_SIZE</quote> include/crypto/ 2045 </para></listitem> 2046 </varlistentry> 2047 <varlistentry> <term>max_keysize</term> 2048 <listitem><para> 2049Maximum key size supported by the transformation. This is the 2050largest key length supported by this transformation algorithm. 2051This must be set to one of the pre-defined values as this is 2052not hardware specific. Possible values for this field can be 2053found via git grep <quote>_MAX_KEY_SIZE</quote> include/crypto/ 2054 </para></listitem> 2055 </varlistentry> 2056 <varlistentry> <term>ivsize</term> 2057 <listitem><para> 2058IV size applicable for transformation. The consumer must provide an 2059IV of exactly that size to perform the encrypt or decrypt operation. 2060 </para></listitem> 2061 </varlistentry> 2062 </variablelist> 2063 </refsect1> 2064<refsect1> 2065<title>Description</title> 2066<para> 2067 All fields except <parameter>givencrypt</parameter> , <parameter>givdecrypt</parameter> , <parameter>geniv</parameter> and <parameter>ivsize</parameter> are 2068 mandatory and must be filled. 2069</para> 2070</refsect1> 2071</refentry> 2072 2073<refentry id="API-struct-aead-alg"> 2074<refentryinfo> 2075 <title>LINUX</title> 2076 <productname>Kernel Hackers Manual</productname> 2077 <date>July 2017</date> 2078</refentryinfo> 2079<refmeta> 2080 <refentrytitle><phrase>struct aead_alg</phrase></refentrytitle> 2081 <manvolnum>9</manvolnum> 2082 <refmiscinfo class="version">4.1.27</refmiscinfo> 2083</refmeta> 2084<refnamediv> 2085 <refname>struct aead_alg</refname> 2086 <refpurpose> 2087 AEAD cipher definition 2088 </refpurpose> 2089</refnamediv> 2090<refsynopsisdiv> 2091 <title>Synopsis</title> 2092 <programlisting> 2093struct aead_alg { 2094 int (* setkey) (struct crypto_aead *tfm, const u8 *key,unsigned int keylen); 2095 int (* setauthsize) (struct crypto_aead *tfm, unsigned int authsize); 2096 int (* encrypt) (struct aead_request *req); 2097 int (* decrypt) (struct aead_request *req); 2098 int (* givencrypt) (struct aead_givcrypt_request *req); 2099 int (* givdecrypt) (struct aead_givcrypt_request *req); 2100 const char * geniv; 2101 unsigned int ivsize; 2102 unsigned int maxauthsize; 2103}; </programlisting> 2104</refsynopsisdiv> 2105 <refsect1> 2106 <title>Members</title> 2107 <variablelist> 2108 <varlistentry> <term>setkey</term> 2109 <listitem><para> 2110see struct ablkcipher_alg 2111 </para></listitem> 2112 </varlistentry> 2113 <varlistentry> <term>setauthsize</term> 2114 <listitem><para> 2115Set authentication size for the AEAD transformation. This 2116function is used to specify the consumer requested size of the 2117authentication tag to be either generated by the transformation 2118during encryption or the size of the authentication tag to be 2119supplied during the decryption operation. This function is also 2120responsible for checking the authentication tag size for 2121validity. 2122 </para></listitem> 2123 </varlistentry> 2124 <varlistentry> <term>encrypt</term> 2125 <listitem><para> 2126see struct ablkcipher_alg 2127 </para></listitem> 2128 </varlistentry> 2129 <varlistentry> <term>decrypt</term> 2130 <listitem><para> 2131see struct ablkcipher_alg 2132 </para></listitem> 2133 </varlistentry> 2134 <varlistentry> <term>givencrypt</term> 2135 <listitem><para> 2136see struct ablkcipher_alg 2137 </para></listitem> 2138 </varlistentry> 2139 <varlistentry> <term>givdecrypt</term> 2140 <listitem><para> 2141see struct ablkcipher_alg 2142 </para></listitem> 2143 </varlistentry> 2144 <varlistentry> <term>geniv</term> 2145 <listitem><para> 2146see struct ablkcipher_alg 2147 </para></listitem> 2148 </varlistentry> 2149 <varlistentry> <term>ivsize</term> 2150 <listitem><para> 2151see struct ablkcipher_alg 2152 </para></listitem> 2153 </varlistentry> 2154 <varlistentry> <term>maxauthsize</term> 2155 <listitem><para> 2156Set the maximum authentication tag size supported by the 2157transformation. A transformation may support smaller tag sizes. 2158As the authentication tag is a message digest to ensure the 2159integrity of the encrypted data, a consumer typically wants the 2160largest authentication tag possible as defined by this 2161variable. 2162 </para></listitem> 2163 </varlistentry> 2164 </variablelist> 2165 </refsect1> 2166<refsect1> 2167<title>Description</title> 2168<para> 2169 All fields except <parameter>givencrypt</parameter> , <parameter>givdecrypt</parameter> , <parameter>geniv</parameter> and <parameter>ivsize</parameter> are 2170 mandatory and must be filled. 2171</para> 2172</refsect1> 2173</refentry> 2174 2175<refentry id="API-struct-blkcipher-alg"> 2176<refentryinfo> 2177 <title>LINUX</title> 2178 <productname>Kernel Hackers Manual</productname> 2179 <date>July 2017</date> 2180</refentryinfo> 2181<refmeta> 2182 <refentrytitle><phrase>struct blkcipher_alg</phrase></refentrytitle> 2183 <manvolnum>9</manvolnum> 2184 <refmiscinfo class="version">4.1.27</refmiscinfo> 2185</refmeta> 2186<refnamediv> 2187 <refname>struct blkcipher_alg</refname> 2188 <refpurpose> 2189 synchronous block cipher definition 2190 </refpurpose> 2191</refnamediv> 2192<refsynopsisdiv> 2193 <title>Synopsis</title> 2194 <programlisting> 2195struct blkcipher_alg { 2196 int (* setkey) (struct crypto_tfm *tfm, const u8 *key,unsigned int keylen); 2197 int (* encrypt) (struct blkcipher_desc *desc,struct scatterlist *dst, struct scatterlist *src,unsigned int nbytes); 2198 int (* decrypt) (struct blkcipher_desc *desc,struct scatterlist *dst, struct scatterlist *src,unsigned int nbytes); 2199 const char * geniv; 2200 unsigned int min_keysize; 2201 unsigned int max_keysize; 2202 unsigned int ivsize; 2203}; </programlisting> 2204</refsynopsisdiv> 2205 <refsect1> 2206 <title>Members</title> 2207 <variablelist> 2208 <varlistentry> <term>setkey</term> 2209 <listitem><para> 2210see struct ablkcipher_alg 2211 </para></listitem> 2212 </varlistentry> 2213 <varlistentry> <term>encrypt</term> 2214 <listitem><para> 2215see struct ablkcipher_alg 2216 </para></listitem> 2217 </varlistentry> 2218 <varlistentry> <term>decrypt</term> 2219 <listitem><para> 2220see struct ablkcipher_alg 2221 </para></listitem> 2222 </varlistentry> 2223 <varlistentry> <term>geniv</term> 2224 <listitem><para> 2225see struct ablkcipher_alg 2226 </para></listitem> 2227 </varlistentry> 2228 <varlistentry> <term>min_keysize</term> 2229 <listitem><para> 2230see struct ablkcipher_alg 2231 </para></listitem> 2232 </varlistentry> 2233 <varlistentry> <term>max_keysize</term> 2234 <listitem><para> 2235see struct ablkcipher_alg 2236 </para></listitem> 2237 </varlistentry> 2238 <varlistentry> <term>ivsize</term> 2239 <listitem><para> 2240see struct ablkcipher_alg 2241 </para></listitem> 2242 </varlistentry> 2243 </variablelist> 2244 </refsect1> 2245<refsect1> 2246<title>Description</title> 2247<para> 2248 All fields except <parameter>geniv</parameter> and <parameter>ivsize</parameter> are mandatory and must be filled. 2249</para> 2250</refsect1> 2251</refentry> 2252 2253<refentry id="API-struct-cipher-alg"> 2254<refentryinfo> 2255 <title>LINUX</title> 2256 <productname>Kernel Hackers Manual</productname> 2257 <date>July 2017</date> 2258</refentryinfo> 2259<refmeta> 2260 <refentrytitle><phrase>struct cipher_alg</phrase></refentrytitle> 2261 <manvolnum>9</manvolnum> 2262 <refmiscinfo class="version">4.1.27</refmiscinfo> 2263</refmeta> 2264<refnamediv> 2265 <refname>struct cipher_alg</refname> 2266 <refpurpose> 2267 single-block symmetric ciphers definition 2268 </refpurpose> 2269</refnamediv> 2270<refsynopsisdiv> 2271 <title>Synopsis</title> 2272 <programlisting> 2273struct cipher_alg { 2274 unsigned int cia_min_keysize; 2275 unsigned int cia_max_keysize; 2276 int (* cia_setkey) (struct crypto_tfm *tfm, const u8 *key,unsigned int keylen); 2277 void (* cia_encrypt) (struct crypto_tfm *tfm, u8 *dst, const u8 *src); 2278 void (* cia_decrypt) (struct crypto_tfm *tfm, u8 *dst, const u8 *src); 2279}; </programlisting> 2280</refsynopsisdiv> 2281 <refsect1> 2282 <title>Members</title> 2283 <variablelist> 2284 <varlistentry> <term>cia_min_keysize</term> 2285 <listitem><para> 2286Minimum key size supported by the transformation. This is 2287the smallest key length supported by this transformation 2288algorithm. This must be set to one of the pre-defined 2289values as this is not hardware specific. Possible values 2290for this field can be found via git grep <quote>_MIN_KEY_SIZE</quote> 2291include/crypto/ 2292 </para></listitem> 2293 </varlistentry> 2294 <varlistentry> <term>cia_max_keysize</term> 2295 <listitem><para> 2296Maximum key size supported by the transformation. This is 2297the largest key length supported by this transformation 2298algorithm. This must be set to one of the pre-defined values 2299as this is not hardware specific. Possible values for this 2300field can be found via git grep <quote>_MAX_KEY_SIZE</quote> 2301include/crypto/ 2302 </para></listitem> 2303 </varlistentry> 2304 <varlistentry> <term>cia_setkey</term> 2305 <listitem><para> 2306Set key for the transformation. This function is used to either 2307program a supplied key into the hardware or store the key in the 2308transformation context for programming it later. Note that this 2309function does modify the transformation context. This function 2310can be called multiple times during the existence of the 2311transformation object, so one must make sure the key is properly 2312reprogrammed into the hardware. This function is also 2313responsible for checking the key length for validity. 2314 </para></listitem> 2315 </varlistentry> 2316 <varlistentry> <term>cia_encrypt</term> 2317 <listitem><para> 2318Encrypt a single block. This function is used to encrypt a 2319single block of data, which must be <parameter>cra_blocksize</parameter> big. This 2320always operates on a full <parameter>cra_blocksize</parameter> and it is not possible 2321to encrypt a block of smaller size. The supplied buffers must 2322therefore also be at least of <parameter>cra_blocksize</parameter> size. Both the 2323input and output buffers are always aligned to <parameter>cra_alignmask</parameter>. 2324In case either of the input or output buffer supplied by user 2325of the crypto API is not aligned to <parameter>cra_alignmask</parameter>, the crypto 2326API will re-align the buffers. The re-alignment means that a 2327new buffer will be allocated, the data will be copied into the 2328new buffer, then the processing will happen on the new buffer, 2329then the data will be copied back into the original buffer and 2330finally the new buffer will be freed. In case a software 2331fallback was put in place in the <parameter>cra_init</parameter> call, this function 2332might need to use the fallback if the algorithm doesn't support 2333all of the key sizes. In case the key was stored in 2334transformation context, the key might need to be re-programmed 2335into the hardware in this function. This function shall not 2336modify the transformation context, as this function may be 2337called in parallel with the same transformation object. 2338 </para></listitem> 2339 </varlistentry> 2340 <varlistentry> <term>cia_decrypt</term> 2341 <listitem><para> 2342Decrypt a single block. This is a reverse counterpart to 2343<parameter>cia_encrypt</parameter>, and the conditions are exactly the same. 2344 </para></listitem> 2345 </varlistentry> 2346 </variablelist> 2347 </refsect1> 2348<refsect1> 2349<title>Description</title> 2350<para> 2351 All fields are mandatory and must be filled. 2352</para> 2353</refsect1> 2354</refentry> 2355 2356<refentry id="API-struct-rng-alg"> 2357<refentryinfo> 2358 <title>LINUX</title> 2359 <productname>Kernel Hackers Manual</productname> 2360 <date>July 2017</date> 2361</refentryinfo> 2362<refmeta> 2363 <refentrytitle><phrase>struct rng_alg</phrase></refentrytitle> 2364 <manvolnum>9</manvolnum> 2365 <refmiscinfo class="version">4.1.27</refmiscinfo> 2366</refmeta> 2367<refnamediv> 2368 <refname>struct rng_alg</refname> 2369 <refpurpose> 2370 random number generator definition 2371 </refpurpose> 2372</refnamediv> 2373<refsynopsisdiv> 2374 <title>Synopsis</title> 2375 <programlisting> 2376struct rng_alg { 2377 int (* rng_make_random) (struct crypto_rng *tfm, u8 *rdata,unsigned int dlen); 2378 int (* rng_reset) (struct crypto_rng *tfm, u8 *seed, unsigned int slen); 2379 unsigned int seedsize; 2380}; </programlisting> 2381</refsynopsisdiv> 2382 <refsect1> 2383 <title>Members</title> 2384 <variablelist> 2385 <varlistentry> <term>rng_make_random</term> 2386 <listitem><para> 2387The function defined by this variable obtains a random 2388number. The random number generator transform must generate 2389the random number out of the context provided with this 2390call. 2391 </para></listitem> 2392 </varlistentry> 2393 <varlistentry> <term>rng_reset</term> 2394 <listitem><para> 2395Reset of the random number generator by clearing the entire state. 2396With the invocation of this function call, the random number 2397generator shall completely reinitialize its state. If the random 2398number generator requires a seed for setting up a new state, 2399the seed must be provided by the consumer while invoking this 2400function. The required size of the seed is defined with 2401<parameter>seedsize</parameter> . 2402 </para></listitem> 2403 </varlistentry> 2404 <varlistentry> <term>seedsize</term> 2405 <listitem><para> 2406The seed size required for a random number generator 2407initialization defined with this variable. Some random number 2408generators like the SP800-90A DRBG does not require a seed as the 2409seeding is implemented internally without the need of support by 2410the consumer. In this case, the seed size is set to zero. 2411 </para></listitem> 2412 </varlistentry> 2413 </variablelist> 2414 </refsect1> 2415</refentry> 2416 2417 </sect1> 2418 <sect1><title>Asynchronous Block Cipher API</title> 2419<para> 2420 </para><para> 2421 Asynchronous block cipher API is used with the ciphers of type 2422 CRYPTO_ALG_TYPE_ABLKCIPHER (listed as type <quote>ablkcipher</quote> in /proc/crypto). 2423 </para><para> 2424 Asynchronous cipher operations imply that the function invocation for a 2425 cipher request returns immediately before the completion of the operation. 2426 The cipher request is scheduled as a separate kernel thread and therefore 2427 load-balanced on the different CPUs via the process scheduler. To allow 2428 the kernel crypto API to inform the caller about the completion of a cipher 2429 request, the caller must provide a callback function. That function is 2430 invoked with the cipher handle when the request completes. 2431 </para><para> 2432 To support the asynchronous operation, additional information than just the 2433 cipher handle must be supplied to the kernel crypto API. That additional 2434 information is given by filling in the ablkcipher_request data structure. 2435 </para><para> 2436 For the asynchronous block cipher API, the state is maintained with the tfm 2437 cipher handle. A single tfm can be used across multiple calls and in 2438 parallel. For asynchronous block cipher calls, context data supplied and 2439 only used by the caller can be referenced the request data structure in 2440 addition to the IV used for the cipher request. The maintenance of such 2441 state information would be important for a crypto driver implementer to 2442 have, because when calling the callback function upon completion of the 2443 cipher operation, that callback function may need some information about 2444 which operation just finished if it invoked multiple in parallel. This 2445 state information is unused by the kernel crypto API. 2446</para> 2447 2448<refentry id="API-crypto-alloc-ablkcipher"> 2449<refentryinfo> 2450 <title>LINUX</title> 2451 <productname>Kernel Hackers Manual</productname> 2452 <date>July 2017</date> 2453</refentryinfo> 2454<refmeta> 2455 <refentrytitle><phrase>crypto_alloc_ablkcipher</phrase></refentrytitle> 2456 <manvolnum>9</manvolnum> 2457 <refmiscinfo class="version">4.1.27</refmiscinfo> 2458</refmeta> 2459<refnamediv> 2460 <refname>crypto_alloc_ablkcipher</refname> 2461 <refpurpose> 2462 allocate asynchronous block cipher handle 2463 </refpurpose> 2464</refnamediv> 2465<refsynopsisdiv> 2466 <title>Synopsis</title> 2467 <funcsynopsis><funcprototype> 2468 <funcdef>struct crypto_ablkcipher * <function>crypto_alloc_ablkcipher </function></funcdef> 2469 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 2470 <paramdef>u32 <parameter>type</parameter></paramdef> 2471 <paramdef>u32 <parameter>mask</parameter></paramdef> 2472 </funcprototype></funcsynopsis> 2473</refsynopsisdiv> 2474<refsect1> 2475 <title>Arguments</title> 2476 <variablelist> 2477 <varlistentry> 2478 <term><parameter>alg_name</parameter></term> 2479 <listitem> 2480 <para> 2481 is the cra_name / name or cra_driver_name / driver name of the 2482 ablkcipher cipher 2483 </para> 2484 </listitem> 2485 </varlistentry> 2486 <varlistentry> 2487 <term><parameter>type</parameter></term> 2488 <listitem> 2489 <para> 2490 specifies the type of the cipher 2491 </para> 2492 </listitem> 2493 </varlistentry> 2494 <varlistentry> 2495 <term><parameter>mask</parameter></term> 2496 <listitem> 2497 <para> 2498 specifies the mask for the cipher 2499 </para> 2500 </listitem> 2501 </varlistentry> 2502 </variablelist> 2503</refsect1> 2504<refsect1> 2505<title>Description</title> 2506<para> 2507 Allocate a cipher handle for an ablkcipher. The returned struct 2508 crypto_ablkcipher is the cipher handle that is required for any subsequent 2509 API invocation for that ablkcipher. 2510</para> 2511</refsect1> 2512<refsect1> 2513<title>Return</title> 2514<para> 2515 allocated cipher handle in case of success; <function>IS_ERR</function> is true in case 2516 of an error, <function>PTR_ERR</function> returns the error code. 2517</para> 2518</refsect1> 2519</refentry> 2520 2521<refentry id="API-crypto-free-ablkcipher"> 2522<refentryinfo> 2523 <title>LINUX</title> 2524 <productname>Kernel Hackers Manual</productname> 2525 <date>July 2017</date> 2526</refentryinfo> 2527<refmeta> 2528 <refentrytitle><phrase>crypto_free_ablkcipher</phrase></refentrytitle> 2529 <manvolnum>9</manvolnum> 2530 <refmiscinfo class="version">4.1.27</refmiscinfo> 2531</refmeta> 2532<refnamediv> 2533 <refname>crypto_free_ablkcipher</refname> 2534 <refpurpose> 2535 zeroize and free cipher handle 2536 </refpurpose> 2537</refnamediv> 2538<refsynopsisdiv> 2539 <title>Synopsis</title> 2540 <funcsynopsis><funcprototype> 2541 <funcdef>void <function>crypto_free_ablkcipher </function></funcdef> 2542 <paramdef>struct crypto_ablkcipher * <parameter>tfm</parameter></paramdef> 2543 </funcprototype></funcsynopsis> 2544</refsynopsisdiv> 2545<refsect1> 2546 <title>Arguments</title> 2547 <variablelist> 2548 <varlistentry> 2549 <term><parameter>tfm</parameter></term> 2550 <listitem> 2551 <para> 2552 cipher handle to be freed 2553 </para> 2554 </listitem> 2555 </varlistentry> 2556 </variablelist> 2557</refsect1> 2558</refentry> 2559 2560<refentry id="API-crypto-has-ablkcipher"> 2561<refentryinfo> 2562 <title>LINUX</title> 2563 <productname>Kernel Hackers Manual</productname> 2564 <date>July 2017</date> 2565</refentryinfo> 2566<refmeta> 2567 <refentrytitle><phrase>crypto_has_ablkcipher</phrase></refentrytitle> 2568 <manvolnum>9</manvolnum> 2569 <refmiscinfo class="version">4.1.27</refmiscinfo> 2570</refmeta> 2571<refnamediv> 2572 <refname>crypto_has_ablkcipher</refname> 2573 <refpurpose> 2574 Search for the availability of an ablkcipher. 2575 </refpurpose> 2576</refnamediv> 2577<refsynopsisdiv> 2578 <title>Synopsis</title> 2579 <funcsynopsis><funcprototype> 2580 <funcdef>int <function>crypto_has_ablkcipher </function></funcdef> 2581 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 2582 <paramdef>u32 <parameter>type</parameter></paramdef> 2583 <paramdef>u32 <parameter>mask</parameter></paramdef> 2584 </funcprototype></funcsynopsis> 2585</refsynopsisdiv> 2586<refsect1> 2587 <title>Arguments</title> 2588 <variablelist> 2589 <varlistentry> 2590 <term><parameter>alg_name</parameter></term> 2591 <listitem> 2592 <para> 2593 is the cra_name / name or cra_driver_name / driver name of the 2594 ablkcipher 2595 </para> 2596 </listitem> 2597 </varlistentry> 2598 <varlistentry> 2599 <term><parameter>type</parameter></term> 2600 <listitem> 2601 <para> 2602 specifies the type of the cipher 2603 </para> 2604 </listitem> 2605 </varlistentry> 2606 <varlistentry> 2607 <term><parameter>mask</parameter></term> 2608 <listitem> 2609 <para> 2610 specifies the mask for the cipher 2611 </para> 2612 </listitem> 2613 </varlistentry> 2614 </variablelist> 2615</refsect1> 2616<refsect1> 2617<title>Return</title> 2618<para> 2619 true when the ablkcipher is known to the kernel crypto API; false 2620 otherwise 2621</para> 2622</refsect1> 2623</refentry> 2624 2625<refentry id="API-crypto-ablkcipher-ivsize"> 2626<refentryinfo> 2627 <title>LINUX</title> 2628 <productname>Kernel Hackers Manual</productname> 2629 <date>July 2017</date> 2630</refentryinfo> 2631<refmeta> 2632 <refentrytitle><phrase>crypto_ablkcipher_ivsize</phrase></refentrytitle> 2633 <manvolnum>9</manvolnum> 2634 <refmiscinfo class="version">4.1.27</refmiscinfo> 2635</refmeta> 2636<refnamediv> 2637 <refname>crypto_ablkcipher_ivsize</refname> 2638 <refpurpose> 2639 obtain IV size 2640 </refpurpose> 2641</refnamediv> 2642<refsynopsisdiv> 2643 <title>Synopsis</title> 2644 <funcsynopsis><funcprototype> 2645 <funcdef>unsigned int <function>crypto_ablkcipher_ivsize </function></funcdef> 2646 <paramdef>struct crypto_ablkcipher * <parameter>tfm</parameter></paramdef> 2647 </funcprototype></funcsynopsis> 2648</refsynopsisdiv> 2649<refsect1> 2650 <title>Arguments</title> 2651 <variablelist> 2652 <varlistentry> 2653 <term><parameter>tfm</parameter></term> 2654 <listitem> 2655 <para> 2656 cipher handle 2657 </para> 2658 </listitem> 2659 </varlistentry> 2660 </variablelist> 2661</refsect1> 2662<refsect1> 2663<title>Description</title> 2664<para> 2665 The size of the IV for the ablkcipher referenced by the cipher handle is 2666 returned. This IV size may be zero if the cipher does not need an IV. 2667</para> 2668</refsect1> 2669<refsect1> 2670<title>Return</title> 2671<para> 2672 IV size in bytes 2673</para> 2674</refsect1> 2675</refentry> 2676 2677<refentry id="API-crypto-ablkcipher-blocksize"> 2678<refentryinfo> 2679 <title>LINUX</title> 2680 <productname>Kernel Hackers Manual</productname> 2681 <date>July 2017</date> 2682</refentryinfo> 2683<refmeta> 2684 <refentrytitle><phrase>crypto_ablkcipher_blocksize</phrase></refentrytitle> 2685 <manvolnum>9</manvolnum> 2686 <refmiscinfo class="version">4.1.27</refmiscinfo> 2687</refmeta> 2688<refnamediv> 2689 <refname>crypto_ablkcipher_blocksize</refname> 2690 <refpurpose> 2691 obtain block size of cipher 2692 </refpurpose> 2693</refnamediv> 2694<refsynopsisdiv> 2695 <title>Synopsis</title> 2696 <funcsynopsis><funcprototype> 2697 <funcdef>unsigned int <function>crypto_ablkcipher_blocksize </function></funcdef> 2698 <paramdef>struct crypto_ablkcipher * <parameter>tfm</parameter></paramdef> 2699 </funcprototype></funcsynopsis> 2700</refsynopsisdiv> 2701<refsect1> 2702 <title>Arguments</title> 2703 <variablelist> 2704 <varlistentry> 2705 <term><parameter>tfm</parameter></term> 2706 <listitem> 2707 <para> 2708 cipher handle 2709 </para> 2710 </listitem> 2711 </varlistentry> 2712 </variablelist> 2713</refsect1> 2714<refsect1> 2715<title>Description</title> 2716<para> 2717 The block size for the ablkcipher referenced with the cipher handle is 2718 returned. The caller may use that information to allocate appropriate 2719 memory for the data returned by the encryption or decryption operation 2720</para> 2721</refsect1> 2722<refsect1> 2723<title>Return</title> 2724<para> 2725 block size of cipher 2726</para> 2727</refsect1> 2728</refentry> 2729 2730<refentry id="API-crypto-ablkcipher-setkey"> 2731<refentryinfo> 2732 <title>LINUX</title> 2733 <productname>Kernel Hackers Manual</productname> 2734 <date>July 2017</date> 2735</refentryinfo> 2736<refmeta> 2737 <refentrytitle><phrase>crypto_ablkcipher_setkey</phrase></refentrytitle> 2738 <manvolnum>9</manvolnum> 2739 <refmiscinfo class="version">4.1.27</refmiscinfo> 2740</refmeta> 2741<refnamediv> 2742 <refname>crypto_ablkcipher_setkey</refname> 2743 <refpurpose> 2744 set key for cipher 2745 </refpurpose> 2746</refnamediv> 2747<refsynopsisdiv> 2748 <title>Synopsis</title> 2749 <funcsynopsis><funcprototype> 2750 <funcdef>int <function>crypto_ablkcipher_setkey </function></funcdef> 2751 <paramdef>struct crypto_ablkcipher * <parameter>tfm</parameter></paramdef> 2752 <paramdef>const u8 * <parameter>key</parameter></paramdef> 2753 <paramdef>unsigned int <parameter>keylen</parameter></paramdef> 2754 </funcprototype></funcsynopsis> 2755</refsynopsisdiv> 2756<refsect1> 2757 <title>Arguments</title> 2758 <variablelist> 2759 <varlistentry> 2760 <term><parameter>tfm</parameter></term> 2761 <listitem> 2762 <para> 2763 cipher handle 2764 </para> 2765 </listitem> 2766 </varlistentry> 2767 <varlistentry> 2768 <term><parameter>key</parameter></term> 2769 <listitem> 2770 <para> 2771 buffer holding the key 2772 </para> 2773 </listitem> 2774 </varlistentry> 2775 <varlistentry> 2776 <term><parameter>keylen</parameter></term> 2777 <listitem> 2778 <para> 2779 length of the key in bytes 2780 </para> 2781 </listitem> 2782 </varlistentry> 2783 </variablelist> 2784</refsect1> 2785<refsect1> 2786<title>Description</title> 2787<para> 2788 The caller provided key is set for the ablkcipher referenced by the cipher 2789 handle. 2790 </para><para> 2791 2792 Note, the key length determines the cipher type. Many block ciphers implement 2793 different cipher modes depending on the key size, such as AES-128 vs AES-192 2794 vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128 2795 is performed. 2796</para> 2797</refsect1> 2798<refsect1> 2799<title>Return</title> 2800<para> 2801 0 if the setting of the key was successful; < 0 if an error occurred 2802</para> 2803</refsect1> 2804</refentry> 2805 2806<refentry id="API-crypto-ablkcipher-reqtfm"> 2807<refentryinfo> 2808 <title>LINUX</title> 2809 <productname>Kernel Hackers Manual</productname> 2810 <date>July 2017</date> 2811</refentryinfo> 2812<refmeta> 2813 <refentrytitle><phrase>crypto_ablkcipher_reqtfm</phrase></refentrytitle> 2814 <manvolnum>9</manvolnum> 2815 <refmiscinfo class="version">4.1.27</refmiscinfo> 2816</refmeta> 2817<refnamediv> 2818 <refname>crypto_ablkcipher_reqtfm</refname> 2819 <refpurpose> 2820 obtain cipher handle from request 2821 </refpurpose> 2822</refnamediv> 2823<refsynopsisdiv> 2824 <title>Synopsis</title> 2825 <funcsynopsis><funcprototype> 2826 <funcdef>struct crypto_ablkcipher * <function>crypto_ablkcipher_reqtfm </function></funcdef> 2827 <paramdef>struct ablkcipher_request * <parameter>req</parameter></paramdef> 2828 </funcprototype></funcsynopsis> 2829</refsynopsisdiv> 2830<refsect1> 2831 <title>Arguments</title> 2832 <variablelist> 2833 <varlistentry> 2834 <term><parameter>req</parameter></term> 2835 <listitem> 2836 <para> 2837 ablkcipher_request out of which the cipher handle is to be obtained 2838 </para> 2839 </listitem> 2840 </varlistentry> 2841 </variablelist> 2842</refsect1> 2843<refsect1> 2844<title>Description</title> 2845<para> 2846 Return the crypto_ablkcipher handle when furnishing an ablkcipher_request 2847 data structure. 2848</para> 2849</refsect1> 2850<refsect1> 2851<title>Return</title> 2852<para> 2853 crypto_ablkcipher handle 2854</para> 2855</refsect1> 2856</refentry> 2857 2858<refentry id="API-crypto-ablkcipher-encrypt"> 2859<refentryinfo> 2860 <title>LINUX</title> 2861 <productname>Kernel Hackers Manual</productname> 2862 <date>July 2017</date> 2863</refentryinfo> 2864<refmeta> 2865 <refentrytitle><phrase>crypto_ablkcipher_encrypt</phrase></refentrytitle> 2866 <manvolnum>9</manvolnum> 2867 <refmiscinfo class="version">4.1.27</refmiscinfo> 2868</refmeta> 2869<refnamediv> 2870 <refname>crypto_ablkcipher_encrypt</refname> 2871 <refpurpose> 2872 encrypt plaintext 2873 </refpurpose> 2874</refnamediv> 2875<refsynopsisdiv> 2876 <title>Synopsis</title> 2877 <funcsynopsis><funcprototype> 2878 <funcdef>int <function>crypto_ablkcipher_encrypt </function></funcdef> 2879 <paramdef>struct ablkcipher_request * <parameter>req</parameter></paramdef> 2880 </funcprototype></funcsynopsis> 2881</refsynopsisdiv> 2882<refsect1> 2883 <title>Arguments</title> 2884 <variablelist> 2885 <varlistentry> 2886 <term><parameter>req</parameter></term> 2887 <listitem> 2888 <para> 2889 reference to the ablkcipher_request handle that holds all information 2890 needed to perform the cipher operation 2891 </para> 2892 </listitem> 2893 </varlistentry> 2894 </variablelist> 2895</refsect1> 2896<refsect1> 2897<title>Description</title> 2898<para> 2899 Encrypt plaintext data using the ablkcipher_request handle. That data 2900 structure and how it is filled with data is discussed with the 2901 ablkcipher_request_* functions. 2902</para> 2903</refsect1> 2904<refsect1> 2905<title>Return</title> 2906<para> 2907 0 if the cipher operation was successful; < 0 if an error occurred 2908</para> 2909</refsect1> 2910</refentry> 2911 2912<refentry id="API-crypto-ablkcipher-decrypt"> 2913<refentryinfo> 2914 <title>LINUX</title> 2915 <productname>Kernel Hackers Manual</productname> 2916 <date>July 2017</date> 2917</refentryinfo> 2918<refmeta> 2919 <refentrytitle><phrase>crypto_ablkcipher_decrypt</phrase></refentrytitle> 2920 <manvolnum>9</manvolnum> 2921 <refmiscinfo class="version">4.1.27</refmiscinfo> 2922</refmeta> 2923<refnamediv> 2924 <refname>crypto_ablkcipher_decrypt</refname> 2925 <refpurpose> 2926 decrypt ciphertext 2927 </refpurpose> 2928</refnamediv> 2929<refsynopsisdiv> 2930 <title>Synopsis</title> 2931 <funcsynopsis><funcprototype> 2932 <funcdef>int <function>crypto_ablkcipher_decrypt </function></funcdef> 2933 <paramdef>struct ablkcipher_request * <parameter>req</parameter></paramdef> 2934 </funcprototype></funcsynopsis> 2935</refsynopsisdiv> 2936<refsect1> 2937 <title>Arguments</title> 2938 <variablelist> 2939 <varlistentry> 2940 <term><parameter>req</parameter></term> 2941 <listitem> 2942 <para> 2943 reference to the ablkcipher_request handle that holds all information 2944 needed to perform the cipher operation 2945 </para> 2946 </listitem> 2947 </varlistentry> 2948 </variablelist> 2949</refsect1> 2950<refsect1> 2951<title>Description</title> 2952<para> 2953 Decrypt ciphertext data using the ablkcipher_request handle. That data 2954 structure and how it is filled with data is discussed with the 2955 ablkcipher_request_* functions. 2956</para> 2957</refsect1> 2958<refsect1> 2959<title>Return</title> 2960<para> 2961 0 if the cipher operation was successful; < 0 if an error occurred 2962</para> 2963</refsect1> 2964</refentry> 2965 2966 </sect1> 2967 <sect1><title>Asynchronous Cipher Request Handle</title> 2968<para> 2969 </para><para> 2970 The ablkcipher_request data structure contains all pointers to data 2971 required for the asynchronous cipher operation. This includes the cipher 2972 handle (which can be used by multiple ablkcipher_request instances), pointer 2973 to plaintext and ciphertext, asynchronous callback function, etc. It acts 2974 as a handle to the ablkcipher_request_* API calls in a similar way as 2975 ablkcipher handle to the crypto_ablkcipher_* API calls. 2976</para> 2977 2978<refentry id="API-crypto-ablkcipher-reqsize"> 2979<refentryinfo> 2980 <title>LINUX</title> 2981 <productname>Kernel Hackers Manual</productname> 2982 <date>July 2017</date> 2983</refentryinfo> 2984<refmeta> 2985 <refentrytitle><phrase>crypto_ablkcipher_reqsize</phrase></refentrytitle> 2986 <manvolnum>9</manvolnum> 2987 <refmiscinfo class="version">4.1.27</refmiscinfo> 2988</refmeta> 2989<refnamediv> 2990 <refname>crypto_ablkcipher_reqsize</refname> 2991 <refpurpose> 2992 obtain size of the request data structure 2993 </refpurpose> 2994</refnamediv> 2995<refsynopsisdiv> 2996 <title>Synopsis</title> 2997 <funcsynopsis><funcprototype> 2998 <funcdef>unsigned int <function>crypto_ablkcipher_reqsize </function></funcdef> 2999 <paramdef>struct crypto_ablkcipher * <parameter>tfm</parameter></paramdef> 3000 </funcprototype></funcsynopsis> 3001</refsynopsisdiv> 3002<refsect1> 3003 <title>Arguments</title> 3004 <variablelist> 3005 <varlistentry> 3006 <term><parameter>tfm</parameter></term> 3007 <listitem> 3008 <para> 3009 cipher handle 3010 </para> 3011 </listitem> 3012 </varlistentry> 3013 </variablelist> 3014</refsect1> 3015<refsect1> 3016<title>Return</title> 3017<para> 3018 number of bytes 3019</para> 3020</refsect1> 3021</refentry> 3022 3023<refentry id="API-ablkcipher-request-set-tfm"> 3024<refentryinfo> 3025 <title>LINUX</title> 3026 <productname>Kernel Hackers Manual</productname> 3027 <date>July 2017</date> 3028</refentryinfo> 3029<refmeta> 3030 <refentrytitle><phrase>ablkcipher_request_set_tfm</phrase></refentrytitle> 3031 <manvolnum>9</manvolnum> 3032 <refmiscinfo class="version">4.1.27</refmiscinfo> 3033</refmeta> 3034<refnamediv> 3035 <refname>ablkcipher_request_set_tfm</refname> 3036 <refpurpose> 3037 update cipher handle reference in request 3038 </refpurpose> 3039</refnamediv> 3040<refsynopsisdiv> 3041 <title>Synopsis</title> 3042 <funcsynopsis><funcprototype> 3043 <funcdef>void <function>ablkcipher_request_set_tfm </function></funcdef> 3044 <paramdef>struct ablkcipher_request * <parameter>req</parameter></paramdef> 3045 <paramdef>struct crypto_ablkcipher * <parameter>tfm</parameter></paramdef> 3046 </funcprototype></funcsynopsis> 3047</refsynopsisdiv> 3048<refsect1> 3049 <title>Arguments</title> 3050 <variablelist> 3051 <varlistentry> 3052 <term><parameter>req</parameter></term> 3053 <listitem> 3054 <para> 3055 request handle to be modified 3056 </para> 3057 </listitem> 3058 </varlistentry> 3059 <varlistentry> 3060 <term><parameter>tfm</parameter></term> 3061 <listitem> 3062 <para> 3063 cipher handle that shall be added to the request handle 3064 </para> 3065 </listitem> 3066 </varlistentry> 3067 </variablelist> 3068</refsect1> 3069<refsect1> 3070<title>Description</title> 3071<para> 3072 Allow the caller to replace the existing ablkcipher handle in the request 3073 data structure with a different one. 3074</para> 3075</refsect1> 3076</refentry> 3077 3078<refentry id="API-ablkcipher-request-alloc"> 3079<refentryinfo> 3080 <title>LINUX</title> 3081 <productname>Kernel Hackers Manual</productname> 3082 <date>July 2017</date> 3083</refentryinfo> 3084<refmeta> 3085 <refentrytitle><phrase>ablkcipher_request_alloc</phrase></refentrytitle> 3086 <manvolnum>9</manvolnum> 3087 <refmiscinfo class="version">4.1.27</refmiscinfo> 3088</refmeta> 3089<refnamediv> 3090 <refname>ablkcipher_request_alloc</refname> 3091 <refpurpose> 3092 allocate request data structure 3093 </refpurpose> 3094</refnamediv> 3095<refsynopsisdiv> 3096 <title>Synopsis</title> 3097 <funcsynopsis><funcprototype> 3098 <funcdef>struct ablkcipher_request * <function>ablkcipher_request_alloc </function></funcdef> 3099 <paramdef>struct crypto_ablkcipher * <parameter>tfm</parameter></paramdef> 3100 <paramdef>gfp_t <parameter>gfp</parameter></paramdef> 3101 </funcprototype></funcsynopsis> 3102</refsynopsisdiv> 3103<refsect1> 3104 <title>Arguments</title> 3105 <variablelist> 3106 <varlistentry> 3107 <term><parameter>tfm</parameter></term> 3108 <listitem> 3109 <para> 3110 cipher handle to be registered with the request 3111 </para> 3112 </listitem> 3113 </varlistentry> 3114 <varlistentry> 3115 <term><parameter>gfp</parameter></term> 3116 <listitem> 3117 <para> 3118 memory allocation flag that is handed to kmalloc by the API call. 3119 </para> 3120 </listitem> 3121 </varlistentry> 3122 </variablelist> 3123</refsect1> 3124<refsect1> 3125<title>Description</title> 3126<para> 3127 Allocate the request data structure that must be used with the ablkcipher 3128 encrypt and decrypt API calls. During the allocation, the provided ablkcipher 3129 handle is registered in the request data structure. 3130</para> 3131</refsect1> 3132<refsect1> 3133<title>Return</title> 3134<para> 3135 allocated request handle in case of success; <function>IS_ERR</function> is true in case 3136 of an error, <function>PTR_ERR</function> returns the error code. 3137</para> 3138</refsect1> 3139</refentry> 3140 3141<refentry id="API-ablkcipher-request-free"> 3142<refentryinfo> 3143 <title>LINUX</title> 3144 <productname>Kernel Hackers Manual</productname> 3145 <date>July 2017</date> 3146</refentryinfo> 3147<refmeta> 3148 <refentrytitle><phrase>ablkcipher_request_free</phrase></refentrytitle> 3149 <manvolnum>9</manvolnum> 3150 <refmiscinfo class="version">4.1.27</refmiscinfo> 3151</refmeta> 3152<refnamediv> 3153 <refname>ablkcipher_request_free</refname> 3154 <refpurpose> 3155 zeroize and free request data structure 3156 </refpurpose> 3157</refnamediv> 3158<refsynopsisdiv> 3159 <title>Synopsis</title> 3160 <funcsynopsis><funcprototype> 3161 <funcdef>void <function>ablkcipher_request_free </function></funcdef> 3162 <paramdef>struct ablkcipher_request * <parameter>req</parameter></paramdef> 3163 </funcprototype></funcsynopsis> 3164</refsynopsisdiv> 3165<refsect1> 3166 <title>Arguments</title> 3167 <variablelist> 3168 <varlistentry> 3169 <term><parameter>req</parameter></term> 3170 <listitem> 3171 <para> 3172 request data structure cipher handle to be freed 3173 </para> 3174 </listitem> 3175 </varlistentry> 3176 </variablelist> 3177</refsect1> 3178</refentry> 3179 3180<refentry id="API-ablkcipher-request-set-callback"> 3181<refentryinfo> 3182 <title>LINUX</title> 3183 <productname>Kernel Hackers Manual</productname> 3184 <date>July 2017</date> 3185</refentryinfo> 3186<refmeta> 3187 <refentrytitle><phrase>ablkcipher_request_set_callback</phrase></refentrytitle> 3188 <manvolnum>9</manvolnum> 3189 <refmiscinfo class="version">4.1.27</refmiscinfo> 3190</refmeta> 3191<refnamediv> 3192 <refname>ablkcipher_request_set_callback</refname> 3193 <refpurpose> 3194 set asynchronous callback function 3195 </refpurpose> 3196</refnamediv> 3197<refsynopsisdiv> 3198 <title>Synopsis</title> 3199 <funcsynopsis><funcprototype> 3200 <funcdef>void <function>ablkcipher_request_set_callback </function></funcdef> 3201 <paramdef>struct ablkcipher_request * <parameter>req</parameter></paramdef> 3202 <paramdef>u32 <parameter>flags</parameter></paramdef> 3203 <paramdef>crypto_completion_t <parameter>compl</parameter></paramdef> 3204 <paramdef>void * <parameter>data</parameter></paramdef> 3205 </funcprototype></funcsynopsis> 3206</refsynopsisdiv> 3207<refsect1> 3208 <title>Arguments</title> 3209 <variablelist> 3210 <varlistentry> 3211 <term><parameter>req</parameter></term> 3212 <listitem> 3213 <para> 3214 request handle 3215 </para> 3216 </listitem> 3217 </varlistentry> 3218 <varlistentry> 3219 <term><parameter>flags</parameter></term> 3220 <listitem> 3221 <para> 3222 specify zero or an ORing of the flags 3223 CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and 3224 increase the wait queue beyond the initial maximum size; 3225 CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep 3226 </para> 3227 </listitem> 3228 </varlistentry> 3229 <varlistentry> 3230 <term><parameter>compl</parameter></term> 3231 <listitem> 3232 <para> 3233 callback function pointer to be registered with the request handle 3234 </para> 3235 </listitem> 3236 </varlistentry> 3237 <varlistentry> 3238 <term><parameter>data</parameter></term> 3239 <listitem> 3240 <para> 3241 The data pointer refers to memory that is not used by the kernel 3242 crypto API, but provided to the callback function for it to use. Here, 3243 the caller can provide a reference to memory the callback function can 3244 operate on. As the callback function is invoked asynchronously to the 3245 related functionality, it may need to access data structures of the 3246 related functionality which can be referenced using this pointer. The 3247 callback function can access the memory via the <quote>data</quote> field in the 3248 crypto_async_request data structure provided to the callback function. 3249 </para> 3250 </listitem> 3251 </varlistentry> 3252 </variablelist> 3253</refsect1> 3254<refsect1> 3255<title>Description</title> 3256<para> 3257 This function allows setting the callback function that is triggered once the 3258 cipher operation completes. 3259 </para><para> 3260 3261 The callback function is registered with the ablkcipher_request handle and 3262 must comply with the following template 3263 </para><para> 3264 3265 void callback_function(struct crypto_async_request *req, int error) 3266</para> 3267</refsect1> 3268</refentry> 3269 3270<refentry id="API-ablkcipher-request-set-crypt"> 3271<refentryinfo> 3272 <title>LINUX</title> 3273 <productname>Kernel Hackers Manual</productname> 3274 <date>July 2017</date> 3275</refentryinfo> 3276<refmeta> 3277 <refentrytitle><phrase>ablkcipher_request_set_crypt</phrase></refentrytitle> 3278 <manvolnum>9</manvolnum> 3279 <refmiscinfo class="version">4.1.27</refmiscinfo> 3280</refmeta> 3281<refnamediv> 3282 <refname>ablkcipher_request_set_crypt</refname> 3283 <refpurpose> 3284 set data buffers 3285 </refpurpose> 3286</refnamediv> 3287<refsynopsisdiv> 3288 <title>Synopsis</title> 3289 <funcsynopsis><funcprototype> 3290 <funcdef>void <function>ablkcipher_request_set_crypt </function></funcdef> 3291 <paramdef>struct ablkcipher_request * <parameter>req</parameter></paramdef> 3292 <paramdef>struct scatterlist * <parameter>src</parameter></paramdef> 3293 <paramdef>struct scatterlist * <parameter>dst</parameter></paramdef> 3294 <paramdef>unsigned int <parameter>nbytes</parameter></paramdef> 3295 <paramdef>void * <parameter>iv</parameter></paramdef> 3296 </funcprototype></funcsynopsis> 3297</refsynopsisdiv> 3298<refsect1> 3299 <title>Arguments</title> 3300 <variablelist> 3301 <varlistentry> 3302 <term><parameter>req</parameter></term> 3303 <listitem> 3304 <para> 3305 request handle 3306 </para> 3307 </listitem> 3308 </varlistentry> 3309 <varlistentry> 3310 <term><parameter>src</parameter></term> 3311 <listitem> 3312 <para> 3313 source scatter / gather list 3314 </para> 3315 </listitem> 3316 </varlistentry> 3317 <varlistentry> 3318 <term><parameter>dst</parameter></term> 3319 <listitem> 3320 <para> 3321 destination scatter / gather list 3322 </para> 3323 </listitem> 3324 </varlistentry> 3325 <varlistentry> 3326 <term><parameter>nbytes</parameter></term> 3327 <listitem> 3328 <para> 3329 number of bytes to process from <parameter>src</parameter> 3330 </para> 3331 </listitem> 3332 </varlistentry> 3333 <varlistentry> 3334 <term><parameter>iv</parameter></term> 3335 <listitem> 3336 <para> 3337 IV for the cipher operation which must comply with the IV size defined 3338 by crypto_ablkcipher_ivsize 3339 </para> 3340 </listitem> 3341 </varlistentry> 3342 </variablelist> 3343</refsect1> 3344<refsect1> 3345<title>Description</title> 3346<para> 3347 This function allows setting of the source data and destination data 3348 scatter / gather lists. 3349 </para><para> 3350 3351 For encryption, the source is treated as the plaintext and the 3352 destination is the ciphertext. For a decryption operation, the use is 3353 reversed - the source is the ciphertext and the destination is the plaintext. 3354</para> 3355</refsect1> 3356</refentry> 3357 3358 </sect1> 3359 <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title> 3360<para> 3361 </para><para> 3362 The AEAD cipher API is used with the ciphers of type CRYPTO_ALG_TYPE_AEAD 3363 (listed as type <quote>aead</quote> in /proc/crypto) 3364 </para><para> 3365 The most prominent examples for this type of encryption is GCM and CCM. 3366 However, the kernel supports other types of AEAD ciphers which are defined 3367 with the following cipher string: 3368 </para><para> 3369 authenc(keyed message digest, block cipher) 3370 </para><para> 3371 For example: authenc(hmac(sha256), cbc(aes)) 3372 </para><para> 3373 The example code provided for the asynchronous block cipher operation 3374 applies here as well. Naturally all *ablkcipher* symbols must be exchanged 3375 the *aead* pendants discussed in the following. In addtion, for the AEAD 3376 operation, the aead_request_set_assoc function must be used to set the 3377 pointer to the associated data memory location before performing the 3378 encryption or decryption operation. In case of an encryption, the associated 3379 data memory is filled during the encryption operation. For decryption, the 3380 associated data memory must contain data that is used to verify the integrity 3381 of the decrypted data. Another deviation from the asynchronous block cipher 3382 operation is that the caller should explicitly check for -EBADMSG of the 3383 crypto_aead_decrypt. That error indicates an authentication error, i.e. 3384 a breach in the integrity of the message. In essence, that -EBADMSG error 3385 code is the key bonus an AEAD cipher has over <quote>standard</quote> block chaining 3386 modes. 3387</para> 3388 3389<refentry id="API-crypto-alloc-aead"> 3390<refentryinfo> 3391 <title>LINUX</title> 3392 <productname>Kernel Hackers Manual</productname> 3393 <date>July 2017</date> 3394</refentryinfo> 3395<refmeta> 3396 <refentrytitle><phrase>crypto_alloc_aead</phrase></refentrytitle> 3397 <manvolnum>9</manvolnum> 3398 <refmiscinfo class="version">4.1.27</refmiscinfo> 3399</refmeta> 3400<refnamediv> 3401 <refname>crypto_alloc_aead</refname> 3402 <refpurpose> 3403 allocate AEAD cipher handle 3404 </refpurpose> 3405</refnamediv> 3406<refsynopsisdiv> 3407 <title>Synopsis</title> 3408 <funcsynopsis><funcprototype> 3409 <funcdef>struct crypto_aead * <function>crypto_alloc_aead </function></funcdef> 3410 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 3411 <paramdef>u32 <parameter>type</parameter></paramdef> 3412 <paramdef>u32 <parameter>mask</parameter></paramdef> 3413 </funcprototype></funcsynopsis> 3414</refsynopsisdiv> 3415<refsect1> 3416 <title>Arguments</title> 3417 <variablelist> 3418 <varlistentry> 3419 <term><parameter>alg_name</parameter></term> 3420 <listitem> 3421 <para> 3422 is the cra_name / name or cra_driver_name / driver name of the 3423 AEAD cipher 3424 </para> 3425 </listitem> 3426 </varlistentry> 3427 <varlistentry> 3428 <term><parameter>type</parameter></term> 3429 <listitem> 3430 <para> 3431 specifies the type of the cipher 3432 </para> 3433 </listitem> 3434 </varlistentry> 3435 <varlistentry> 3436 <term><parameter>mask</parameter></term> 3437 <listitem> 3438 <para> 3439 specifies the mask for the cipher 3440 </para> 3441 </listitem> 3442 </varlistentry> 3443 </variablelist> 3444</refsect1> 3445<refsect1> 3446<title>Description</title> 3447<para> 3448 Allocate a cipher handle for an AEAD. The returned struct 3449 crypto_aead is the cipher handle that is required for any subsequent 3450 API invocation for that AEAD. 3451</para> 3452</refsect1> 3453<refsect1> 3454<title>Return</title> 3455<para> 3456 allocated cipher handle in case of success; <function>IS_ERR</function> is true in case 3457 of an error, <function>PTR_ERR</function> returns the error code. 3458</para> 3459</refsect1> 3460</refentry> 3461 3462<refentry id="API-crypto-free-aead"> 3463<refentryinfo> 3464 <title>LINUX</title> 3465 <productname>Kernel Hackers Manual</productname> 3466 <date>July 2017</date> 3467</refentryinfo> 3468<refmeta> 3469 <refentrytitle><phrase>crypto_free_aead</phrase></refentrytitle> 3470 <manvolnum>9</manvolnum> 3471 <refmiscinfo class="version">4.1.27</refmiscinfo> 3472</refmeta> 3473<refnamediv> 3474 <refname>crypto_free_aead</refname> 3475 <refpurpose> 3476 zeroize and free aead handle 3477 </refpurpose> 3478</refnamediv> 3479<refsynopsisdiv> 3480 <title>Synopsis</title> 3481 <funcsynopsis><funcprototype> 3482 <funcdef>void <function>crypto_free_aead </function></funcdef> 3483 <paramdef>struct crypto_aead * <parameter>tfm</parameter></paramdef> 3484 </funcprototype></funcsynopsis> 3485</refsynopsisdiv> 3486<refsect1> 3487 <title>Arguments</title> 3488 <variablelist> 3489 <varlistentry> 3490 <term><parameter>tfm</parameter></term> 3491 <listitem> 3492 <para> 3493 cipher handle to be freed 3494 </para> 3495 </listitem> 3496 </varlistentry> 3497 </variablelist> 3498</refsect1> 3499</refentry> 3500 3501<refentry id="API-crypto-aead-ivsize"> 3502<refentryinfo> 3503 <title>LINUX</title> 3504 <productname>Kernel Hackers Manual</productname> 3505 <date>July 2017</date> 3506</refentryinfo> 3507<refmeta> 3508 <refentrytitle><phrase>crypto_aead_ivsize</phrase></refentrytitle> 3509 <manvolnum>9</manvolnum> 3510 <refmiscinfo class="version">4.1.27</refmiscinfo> 3511</refmeta> 3512<refnamediv> 3513 <refname>crypto_aead_ivsize</refname> 3514 <refpurpose> 3515 obtain IV size 3516 </refpurpose> 3517</refnamediv> 3518<refsynopsisdiv> 3519 <title>Synopsis</title> 3520 <funcsynopsis><funcprototype> 3521 <funcdef>unsigned int <function>crypto_aead_ivsize </function></funcdef> 3522 <paramdef>struct crypto_aead * <parameter>tfm</parameter></paramdef> 3523 </funcprototype></funcsynopsis> 3524</refsynopsisdiv> 3525<refsect1> 3526 <title>Arguments</title> 3527 <variablelist> 3528 <varlistentry> 3529 <term><parameter>tfm</parameter></term> 3530 <listitem> 3531 <para> 3532 cipher handle 3533 </para> 3534 </listitem> 3535 </varlistentry> 3536 </variablelist> 3537</refsect1> 3538<refsect1> 3539<title>Description</title> 3540<para> 3541 The size of the IV for the aead referenced by the cipher handle is 3542 returned. This IV size may be zero if the cipher does not need an IV. 3543</para> 3544</refsect1> 3545<refsect1> 3546<title>Return</title> 3547<para> 3548 IV size in bytes 3549</para> 3550</refsect1> 3551</refentry> 3552 3553<refentry id="API-crypto-aead-authsize"> 3554<refentryinfo> 3555 <title>LINUX</title> 3556 <productname>Kernel Hackers Manual</productname> 3557 <date>July 2017</date> 3558</refentryinfo> 3559<refmeta> 3560 <refentrytitle><phrase>crypto_aead_authsize</phrase></refentrytitle> 3561 <manvolnum>9</manvolnum> 3562 <refmiscinfo class="version">4.1.27</refmiscinfo> 3563</refmeta> 3564<refnamediv> 3565 <refname>crypto_aead_authsize</refname> 3566 <refpurpose> 3567 obtain maximum authentication data size 3568 </refpurpose> 3569</refnamediv> 3570<refsynopsisdiv> 3571 <title>Synopsis</title> 3572 <funcsynopsis><funcprototype> 3573 <funcdef>unsigned int <function>crypto_aead_authsize </function></funcdef> 3574 <paramdef>struct crypto_aead * <parameter>tfm</parameter></paramdef> 3575 </funcprototype></funcsynopsis> 3576</refsynopsisdiv> 3577<refsect1> 3578 <title>Arguments</title> 3579 <variablelist> 3580 <varlistentry> 3581 <term><parameter>tfm</parameter></term> 3582 <listitem> 3583 <para> 3584 cipher handle 3585 </para> 3586 </listitem> 3587 </varlistentry> 3588 </variablelist> 3589</refsect1> 3590<refsect1> 3591<title>Description</title> 3592<para> 3593 The maximum size of the authentication data for the AEAD cipher referenced 3594 by the AEAD cipher handle is returned. The authentication data size may be 3595 zero if the cipher implements a hard-coded maximum. 3596 </para><para> 3597 3598 The authentication data may also be known as <quote>tag value</quote>. 3599</para> 3600</refsect1> 3601<refsect1> 3602<title>Return</title> 3603<para> 3604 authentication data size / tag size in bytes 3605</para> 3606</refsect1> 3607</refentry> 3608 3609<refentry id="API-crypto-aead-blocksize"> 3610<refentryinfo> 3611 <title>LINUX</title> 3612 <productname>Kernel Hackers Manual</productname> 3613 <date>July 2017</date> 3614</refentryinfo> 3615<refmeta> 3616 <refentrytitle><phrase>crypto_aead_blocksize</phrase></refentrytitle> 3617 <manvolnum>9</manvolnum> 3618 <refmiscinfo class="version">4.1.27</refmiscinfo> 3619</refmeta> 3620<refnamediv> 3621 <refname>crypto_aead_blocksize</refname> 3622 <refpurpose> 3623 obtain block size of cipher 3624 </refpurpose> 3625</refnamediv> 3626<refsynopsisdiv> 3627 <title>Synopsis</title> 3628 <funcsynopsis><funcprototype> 3629 <funcdef>unsigned int <function>crypto_aead_blocksize </function></funcdef> 3630 <paramdef>struct crypto_aead * <parameter>tfm</parameter></paramdef> 3631 </funcprototype></funcsynopsis> 3632</refsynopsisdiv> 3633<refsect1> 3634 <title>Arguments</title> 3635 <variablelist> 3636 <varlistentry> 3637 <term><parameter>tfm</parameter></term> 3638 <listitem> 3639 <para> 3640 cipher handle 3641 </para> 3642 </listitem> 3643 </varlistentry> 3644 </variablelist> 3645</refsect1> 3646<refsect1> 3647<title>Description</title> 3648<para> 3649 The block size for the AEAD referenced with the cipher handle is returned. 3650 The caller may use that information to allocate appropriate memory for the 3651 data returned by the encryption or decryption operation 3652</para> 3653</refsect1> 3654<refsect1> 3655<title>Return</title> 3656<para> 3657 block size of cipher 3658</para> 3659</refsect1> 3660</refentry> 3661 3662<refentry id="API-crypto-aead-setkey"> 3663<refentryinfo> 3664 <title>LINUX</title> 3665 <productname>Kernel Hackers Manual</productname> 3666 <date>July 2017</date> 3667</refentryinfo> 3668<refmeta> 3669 <refentrytitle><phrase>crypto_aead_setkey</phrase></refentrytitle> 3670 <manvolnum>9</manvolnum> 3671 <refmiscinfo class="version">4.1.27</refmiscinfo> 3672</refmeta> 3673<refnamediv> 3674 <refname>crypto_aead_setkey</refname> 3675 <refpurpose> 3676 set key for cipher 3677 </refpurpose> 3678</refnamediv> 3679<refsynopsisdiv> 3680 <title>Synopsis</title> 3681 <funcsynopsis><funcprototype> 3682 <funcdef>int <function>crypto_aead_setkey </function></funcdef> 3683 <paramdef>struct crypto_aead * <parameter>tfm</parameter></paramdef> 3684 <paramdef>const u8 * <parameter>key</parameter></paramdef> 3685 <paramdef>unsigned int <parameter>keylen</parameter></paramdef> 3686 </funcprototype></funcsynopsis> 3687</refsynopsisdiv> 3688<refsect1> 3689 <title>Arguments</title> 3690 <variablelist> 3691 <varlistentry> 3692 <term><parameter>tfm</parameter></term> 3693 <listitem> 3694 <para> 3695 cipher handle 3696 </para> 3697 </listitem> 3698 </varlistentry> 3699 <varlistentry> 3700 <term><parameter>key</parameter></term> 3701 <listitem> 3702 <para> 3703 buffer holding the key 3704 </para> 3705 </listitem> 3706 </varlistentry> 3707 <varlistentry> 3708 <term><parameter>keylen</parameter></term> 3709 <listitem> 3710 <para> 3711 length of the key in bytes 3712 </para> 3713 </listitem> 3714 </varlistentry> 3715 </variablelist> 3716</refsect1> 3717<refsect1> 3718<title>Description</title> 3719<para> 3720 The caller provided key is set for the AEAD referenced by the cipher 3721 handle. 3722 </para><para> 3723 3724 Note, the key length determines the cipher type. Many block ciphers implement 3725 different cipher modes depending on the key size, such as AES-128 vs AES-192 3726 vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128 3727 is performed. 3728</para> 3729</refsect1> 3730<refsect1> 3731<title>Return</title> 3732<para> 3733 0 if the setting of the key was successful; < 0 if an error occurred 3734</para> 3735</refsect1> 3736</refentry> 3737 3738<refentry id="API-crypto-aead-setauthsize"> 3739<refentryinfo> 3740 <title>LINUX</title> 3741 <productname>Kernel Hackers Manual</productname> 3742 <date>July 2017</date> 3743</refentryinfo> 3744<refmeta> 3745 <refentrytitle><phrase>crypto_aead_setauthsize</phrase></refentrytitle> 3746 <manvolnum>9</manvolnum> 3747 <refmiscinfo class="version">4.1.27</refmiscinfo> 3748</refmeta> 3749<refnamediv> 3750 <refname>crypto_aead_setauthsize</refname> 3751 <refpurpose> 3752 set authentication data size 3753 </refpurpose> 3754</refnamediv> 3755<refsynopsisdiv> 3756 <title>Synopsis</title> 3757 <funcsynopsis><funcprototype> 3758 <funcdef>int <function>crypto_aead_setauthsize </function></funcdef> 3759 <paramdef>struct crypto_aead * <parameter>tfm</parameter></paramdef> 3760 <paramdef>unsigned int <parameter>authsize</parameter></paramdef> 3761 </funcprototype></funcsynopsis> 3762</refsynopsisdiv> 3763<refsect1> 3764 <title>Arguments</title> 3765 <variablelist> 3766 <varlistentry> 3767 <term><parameter>tfm</parameter></term> 3768 <listitem> 3769 <para> 3770 cipher handle 3771 </para> 3772 </listitem> 3773 </varlistentry> 3774 <varlistentry> 3775 <term><parameter>authsize</parameter></term> 3776 <listitem> 3777 <para> 3778 size of the authentication data / tag in bytes 3779 </para> 3780 </listitem> 3781 </varlistentry> 3782 </variablelist> 3783</refsect1> 3784<refsect1> 3785<title>Description</title> 3786<para> 3787 Set the authentication data size / tag size. AEAD requires an authentication 3788 tag (or MAC) in addition to the associated data. 3789</para> 3790</refsect1> 3791<refsect1> 3792<title>Return</title> 3793<para> 3794 0 if the setting of the key was successful; < 0 if an error occurred 3795</para> 3796</refsect1> 3797</refentry> 3798 3799<refentry id="API-crypto-aead-encrypt"> 3800<refentryinfo> 3801 <title>LINUX</title> 3802 <productname>Kernel Hackers Manual</productname> 3803 <date>July 2017</date> 3804</refentryinfo> 3805<refmeta> 3806 <refentrytitle><phrase>crypto_aead_encrypt</phrase></refentrytitle> 3807 <manvolnum>9</manvolnum> 3808 <refmiscinfo class="version">4.1.27</refmiscinfo> 3809</refmeta> 3810<refnamediv> 3811 <refname>crypto_aead_encrypt</refname> 3812 <refpurpose> 3813 encrypt plaintext 3814 </refpurpose> 3815</refnamediv> 3816<refsynopsisdiv> 3817 <title>Synopsis</title> 3818 <funcsynopsis><funcprototype> 3819 <funcdef>int <function>crypto_aead_encrypt </function></funcdef> 3820 <paramdef>struct aead_request * <parameter>req</parameter></paramdef> 3821 </funcprototype></funcsynopsis> 3822</refsynopsisdiv> 3823<refsect1> 3824 <title>Arguments</title> 3825 <variablelist> 3826 <varlistentry> 3827 <term><parameter>req</parameter></term> 3828 <listitem> 3829 <para> 3830 reference to the aead_request handle that holds all information 3831 needed to perform the cipher operation 3832 </para> 3833 </listitem> 3834 </varlistentry> 3835 </variablelist> 3836</refsect1> 3837<refsect1> 3838<title>Description</title> 3839<para> 3840 Encrypt plaintext data using the aead_request handle. That data structure 3841 and how it is filled with data is discussed with the aead_request_* 3842 functions. 3843 </para><para> 3844 3845 IMPORTANT NOTE The encryption operation creates the authentication data / 3846 tag. That data is concatenated with the created ciphertext. 3847 The ciphertext memory size is therefore the given number of 3848 block cipher blocks + the size defined by the 3849 crypto_aead_setauthsize invocation. The caller must ensure 3850 that sufficient memory is available for the ciphertext and 3851 the authentication tag. 3852</para> 3853</refsect1> 3854<refsect1> 3855<title>Return</title> 3856<para> 3857 0 if the cipher operation was successful; < 0 if an error occurred 3858</para> 3859</refsect1> 3860</refentry> 3861 3862<refentry id="API-crypto-aead-decrypt"> 3863<refentryinfo> 3864 <title>LINUX</title> 3865 <productname>Kernel Hackers Manual</productname> 3866 <date>July 2017</date> 3867</refentryinfo> 3868<refmeta> 3869 <refentrytitle><phrase>crypto_aead_decrypt</phrase></refentrytitle> 3870 <manvolnum>9</manvolnum> 3871 <refmiscinfo class="version">4.1.27</refmiscinfo> 3872</refmeta> 3873<refnamediv> 3874 <refname>crypto_aead_decrypt</refname> 3875 <refpurpose> 3876 decrypt ciphertext 3877 </refpurpose> 3878</refnamediv> 3879<refsynopsisdiv> 3880 <title>Synopsis</title> 3881 <funcsynopsis><funcprototype> 3882 <funcdef>int <function>crypto_aead_decrypt </function></funcdef> 3883 <paramdef>struct aead_request * <parameter>req</parameter></paramdef> 3884 </funcprototype></funcsynopsis> 3885</refsynopsisdiv> 3886<refsect1> 3887 <title>Arguments</title> 3888 <variablelist> 3889 <varlistentry> 3890 <term><parameter>req</parameter></term> 3891 <listitem> 3892 <para> 3893 reference to the ablkcipher_request handle that holds all information 3894 needed to perform the cipher operation 3895 </para> 3896 </listitem> 3897 </varlistentry> 3898 </variablelist> 3899</refsect1> 3900<refsect1> 3901<title>Description</title> 3902<para> 3903 Decrypt ciphertext data using the aead_request handle. That data structure 3904 and how it is filled with data is discussed with the aead_request_* 3905 functions. 3906 </para><para> 3907 3908 IMPORTANT NOTE The caller must concatenate the ciphertext followed by the 3909 authentication data / tag. That authentication data / tag 3910 must have the size defined by the crypto_aead_setauthsize 3911 invocation. 3912</para> 3913</refsect1> 3914<refsect1> 3915<title>Return</title> 3916<para> 3917 0 if the cipher operation was successful; -EBADMSG: The AEAD 3918 cipher operation performs the authentication of the data during the 3919 decryption operation. Therefore, the function returns this error if 3920 the authentication of the ciphertext was unsuccessful (i.e. the 3921 integrity of the ciphertext or the associated data was violated); 3922 < 0 if an error occurred. 3923</para> 3924</refsect1> 3925</refentry> 3926 3927 </sect1> 3928 <sect1><title>Asynchronous AEAD Request Handle</title> 3929<para> 3930 </para><para> 3931 The aead_request data structure contains all pointers to data required for 3932 the AEAD cipher operation. This includes the cipher handle (which can be 3933 used by multiple aead_request instances), pointer to plaintext and 3934 ciphertext, asynchronous callback function, etc. It acts as a handle to the 3935 aead_request_* API calls in a similar way as AEAD handle to the 3936 crypto_aead_* API calls. 3937</para> 3938 3939<refentry id="API-crypto-aead-reqsize"> 3940<refentryinfo> 3941 <title>LINUX</title> 3942 <productname>Kernel Hackers Manual</productname> 3943 <date>July 2017</date> 3944</refentryinfo> 3945<refmeta> 3946 <refentrytitle><phrase>crypto_aead_reqsize</phrase></refentrytitle> 3947 <manvolnum>9</manvolnum> 3948 <refmiscinfo class="version">4.1.27</refmiscinfo> 3949</refmeta> 3950<refnamediv> 3951 <refname>crypto_aead_reqsize</refname> 3952 <refpurpose> 3953 obtain size of the request data structure 3954 </refpurpose> 3955</refnamediv> 3956<refsynopsisdiv> 3957 <title>Synopsis</title> 3958 <funcsynopsis><funcprototype> 3959 <funcdef>unsigned int <function>crypto_aead_reqsize </function></funcdef> 3960 <paramdef>struct crypto_aead * <parameter>tfm</parameter></paramdef> 3961 </funcprototype></funcsynopsis> 3962</refsynopsisdiv> 3963<refsect1> 3964 <title>Arguments</title> 3965 <variablelist> 3966 <varlistentry> 3967 <term><parameter>tfm</parameter></term> 3968 <listitem> 3969 <para> 3970 cipher handle 3971 </para> 3972 </listitem> 3973 </varlistentry> 3974 </variablelist> 3975</refsect1> 3976<refsect1> 3977<title>Return</title> 3978<para> 3979 number of bytes 3980</para> 3981</refsect1> 3982</refentry> 3983 3984<refentry id="API-aead-request-set-tfm"> 3985<refentryinfo> 3986 <title>LINUX</title> 3987 <productname>Kernel Hackers Manual</productname> 3988 <date>July 2017</date> 3989</refentryinfo> 3990<refmeta> 3991 <refentrytitle><phrase>aead_request_set_tfm</phrase></refentrytitle> 3992 <manvolnum>9</manvolnum> 3993 <refmiscinfo class="version">4.1.27</refmiscinfo> 3994</refmeta> 3995<refnamediv> 3996 <refname>aead_request_set_tfm</refname> 3997 <refpurpose> 3998 update cipher handle reference in request 3999 </refpurpose> 4000</refnamediv> 4001<refsynopsisdiv> 4002 <title>Synopsis</title> 4003 <funcsynopsis><funcprototype> 4004 <funcdef>void <function>aead_request_set_tfm </function></funcdef> 4005 <paramdef>struct aead_request * <parameter>req</parameter></paramdef> 4006 <paramdef>struct crypto_aead * <parameter>tfm</parameter></paramdef> 4007 </funcprototype></funcsynopsis> 4008</refsynopsisdiv> 4009<refsect1> 4010 <title>Arguments</title> 4011 <variablelist> 4012 <varlistentry> 4013 <term><parameter>req</parameter></term> 4014 <listitem> 4015 <para> 4016 request handle to be modified 4017 </para> 4018 </listitem> 4019 </varlistentry> 4020 <varlistentry> 4021 <term><parameter>tfm</parameter></term> 4022 <listitem> 4023 <para> 4024 cipher handle that shall be added to the request handle 4025 </para> 4026 </listitem> 4027 </varlistentry> 4028 </variablelist> 4029</refsect1> 4030<refsect1> 4031<title>Description</title> 4032<para> 4033 Allow the caller to replace the existing aead handle in the request 4034 data structure with a different one. 4035</para> 4036</refsect1> 4037</refentry> 4038 4039<refentry id="API-aead-request-alloc"> 4040<refentryinfo> 4041 <title>LINUX</title> 4042 <productname>Kernel Hackers Manual</productname> 4043 <date>July 2017</date> 4044</refentryinfo> 4045<refmeta> 4046 <refentrytitle><phrase>aead_request_alloc</phrase></refentrytitle> 4047 <manvolnum>9</manvolnum> 4048 <refmiscinfo class="version">4.1.27</refmiscinfo> 4049</refmeta> 4050<refnamediv> 4051 <refname>aead_request_alloc</refname> 4052 <refpurpose> 4053 allocate request data structure 4054 </refpurpose> 4055</refnamediv> 4056<refsynopsisdiv> 4057 <title>Synopsis</title> 4058 <funcsynopsis><funcprototype> 4059 <funcdef>struct aead_request * <function>aead_request_alloc </function></funcdef> 4060 <paramdef>struct crypto_aead * <parameter>tfm</parameter></paramdef> 4061 <paramdef>gfp_t <parameter>gfp</parameter></paramdef> 4062 </funcprototype></funcsynopsis> 4063</refsynopsisdiv> 4064<refsect1> 4065 <title>Arguments</title> 4066 <variablelist> 4067 <varlistentry> 4068 <term><parameter>tfm</parameter></term> 4069 <listitem> 4070 <para> 4071 cipher handle to be registered with the request 4072 </para> 4073 </listitem> 4074 </varlistentry> 4075 <varlistentry> 4076 <term><parameter>gfp</parameter></term> 4077 <listitem> 4078 <para> 4079 memory allocation flag that is handed to kmalloc by the API call. 4080 </para> 4081 </listitem> 4082 </varlistentry> 4083 </variablelist> 4084</refsect1> 4085<refsect1> 4086<title>Description</title> 4087<para> 4088 Allocate the request data structure that must be used with the AEAD 4089 encrypt and decrypt API calls. During the allocation, the provided aead 4090 handle is registered in the request data structure. 4091</para> 4092</refsect1> 4093<refsect1> 4094<title>Return</title> 4095<para> 4096 allocated request handle in case of success; <function>IS_ERR</function> is true in case 4097 of an error, <function>PTR_ERR</function> returns the error code. 4098</para> 4099</refsect1> 4100</refentry> 4101 4102<refentry id="API-aead-request-free"> 4103<refentryinfo> 4104 <title>LINUX</title> 4105 <productname>Kernel Hackers Manual</productname> 4106 <date>July 2017</date> 4107</refentryinfo> 4108<refmeta> 4109 <refentrytitle><phrase>aead_request_free</phrase></refentrytitle> 4110 <manvolnum>9</manvolnum> 4111 <refmiscinfo class="version">4.1.27</refmiscinfo> 4112</refmeta> 4113<refnamediv> 4114 <refname>aead_request_free</refname> 4115 <refpurpose> 4116 zeroize and free request data structure 4117 </refpurpose> 4118</refnamediv> 4119<refsynopsisdiv> 4120 <title>Synopsis</title> 4121 <funcsynopsis><funcprototype> 4122 <funcdef>void <function>aead_request_free </function></funcdef> 4123 <paramdef>struct aead_request * <parameter>req</parameter></paramdef> 4124 </funcprototype></funcsynopsis> 4125</refsynopsisdiv> 4126<refsect1> 4127 <title>Arguments</title> 4128 <variablelist> 4129 <varlistentry> 4130 <term><parameter>req</parameter></term> 4131 <listitem> 4132 <para> 4133 request data structure cipher handle to be freed 4134 </para> 4135 </listitem> 4136 </varlistentry> 4137 </variablelist> 4138</refsect1> 4139</refentry> 4140 4141<refentry id="API-aead-request-set-callback"> 4142<refentryinfo> 4143 <title>LINUX</title> 4144 <productname>Kernel Hackers Manual</productname> 4145 <date>July 2017</date> 4146</refentryinfo> 4147<refmeta> 4148 <refentrytitle><phrase>aead_request_set_callback</phrase></refentrytitle> 4149 <manvolnum>9</manvolnum> 4150 <refmiscinfo class="version">4.1.27</refmiscinfo> 4151</refmeta> 4152<refnamediv> 4153 <refname>aead_request_set_callback</refname> 4154 <refpurpose> 4155 set asynchronous callback function 4156 </refpurpose> 4157</refnamediv> 4158<refsynopsisdiv> 4159 <title>Synopsis</title> 4160 <funcsynopsis><funcprototype> 4161 <funcdef>void <function>aead_request_set_callback </function></funcdef> 4162 <paramdef>struct aead_request * <parameter>req</parameter></paramdef> 4163 <paramdef>u32 <parameter>flags</parameter></paramdef> 4164 <paramdef>crypto_completion_t <parameter>compl</parameter></paramdef> 4165 <paramdef>void * <parameter>data</parameter></paramdef> 4166 </funcprototype></funcsynopsis> 4167</refsynopsisdiv> 4168<refsect1> 4169 <title>Arguments</title> 4170 <variablelist> 4171 <varlistentry> 4172 <term><parameter>req</parameter></term> 4173 <listitem> 4174 <para> 4175 request handle 4176 </para> 4177 </listitem> 4178 </varlistentry> 4179 <varlistentry> 4180 <term><parameter>flags</parameter></term> 4181 <listitem> 4182 <para> 4183 specify zero or an ORing of the flags 4184 CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and 4185 increase the wait queue beyond the initial maximum size; 4186 CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep 4187 </para> 4188 </listitem> 4189 </varlistentry> 4190 <varlistentry> 4191 <term><parameter>compl</parameter></term> 4192 <listitem> 4193 <para> 4194 callback function pointer to be registered with the request handle 4195 </para> 4196 </listitem> 4197 </varlistentry> 4198 <varlistentry> 4199 <term><parameter>data</parameter></term> 4200 <listitem> 4201 <para> 4202 The data pointer refers to memory that is not used by the kernel 4203 crypto API, but provided to the callback function for it to use. Here, 4204 the caller can provide a reference to memory the callback function can 4205 operate on. As the callback function is invoked asynchronously to the 4206 related functionality, it may need to access data structures of the 4207 related functionality which can be referenced using this pointer. The 4208 callback function can access the memory via the <quote>data</quote> field in the 4209 crypto_async_request data structure provided to the callback function. 4210 </para> 4211 </listitem> 4212 </varlistentry> 4213 </variablelist> 4214</refsect1> 4215<refsect1> 4216<title>Description</title> 4217<para> 4218 Setting the callback function that is triggered once the cipher operation 4219 completes 4220 </para><para> 4221 4222 The callback function is registered with the aead_request handle and 4223 must comply with the following template 4224 </para><para> 4225 4226 void callback_function(struct crypto_async_request *req, int error) 4227</para> 4228</refsect1> 4229</refentry> 4230 4231<refentry id="API-aead-request-set-crypt"> 4232<refentryinfo> 4233 <title>LINUX</title> 4234 <productname>Kernel Hackers Manual</productname> 4235 <date>July 2017</date> 4236</refentryinfo> 4237<refmeta> 4238 <refentrytitle><phrase>aead_request_set_crypt</phrase></refentrytitle> 4239 <manvolnum>9</manvolnum> 4240 <refmiscinfo class="version">4.1.27</refmiscinfo> 4241</refmeta> 4242<refnamediv> 4243 <refname>aead_request_set_crypt</refname> 4244 <refpurpose> 4245 set data buffers 4246 </refpurpose> 4247</refnamediv> 4248<refsynopsisdiv> 4249 <title>Synopsis</title> 4250 <funcsynopsis><funcprototype> 4251 <funcdef>void <function>aead_request_set_crypt </function></funcdef> 4252 <paramdef>struct aead_request * <parameter>req</parameter></paramdef> 4253 <paramdef>struct scatterlist * <parameter>src</parameter></paramdef> 4254 <paramdef>struct scatterlist * <parameter>dst</parameter></paramdef> 4255 <paramdef>unsigned int <parameter>cryptlen</parameter></paramdef> 4256 <paramdef>u8 * <parameter>iv</parameter></paramdef> 4257 </funcprototype></funcsynopsis> 4258</refsynopsisdiv> 4259<refsect1> 4260 <title>Arguments</title> 4261 <variablelist> 4262 <varlistentry> 4263 <term><parameter>req</parameter></term> 4264 <listitem> 4265 <para> 4266 request handle 4267 </para> 4268 </listitem> 4269 </varlistentry> 4270 <varlistentry> 4271 <term><parameter>src</parameter></term> 4272 <listitem> 4273 <para> 4274 source scatter / gather list 4275 </para> 4276 </listitem> 4277 </varlistentry> 4278 <varlistentry> 4279 <term><parameter>dst</parameter></term> 4280 <listitem> 4281 <para> 4282 destination scatter / gather list 4283 </para> 4284 </listitem> 4285 </varlistentry> 4286 <varlistentry> 4287 <term><parameter>cryptlen</parameter></term> 4288 <listitem> 4289 <para> 4290 number of bytes to process from <parameter>src</parameter> 4291 </para> 4292 </listitem> 4293 </varlistentry> 4294 <varlistentry> 4295 <term><parameter>iv</parameter></term> 4296 <listitem> 4297 <para> 4298 IV for the cipher operation which must comply with the IV size defined 4299 by <function>crypto_aead_ivsize</function> 4300 </para> 4301 </listitem> 4302 </varlistentry> 4303 </variablelist> 4304</refsect1> 4305<refsect1> 4306<title>Description</title> 4307<para> 4308 Setting the source data and destination data scatter / gather lists. 4309 </para><para> 4310 4311 For encryption, the source is treated as the plaintext and the 4312 destination is the ciphertext. For a decryption operation, the use is 4313 reversed - the source is the ciphertext and the destination is the plaintext. 4314 </para><para> 4315 4316 IMPORTANT NOTE AEAD requires an authentication tag (MAC). For decryption, 4317 the caller must concatenate the ciphertext followed by the 4318 authentication tag and provide the entire data stream to the 4319 decryption operation (i.e. the data length used for the 4320 initialization of the scatterlist and the data length for the 4321 decryption operation is identical). For encryption, however, 4322 the authentication tag is created while encrypting the data. 4323 The destination buffer must hold sufficient space for the 4324 ciphertext and the authentication tag while the encryption 4325 invocation must only point to the plaintext data size. The 4326 following code snippet illustrates the memory usage 4327 buffer = kmalloc(ptbuflen + (enc ? authsize : 0)); 4328 sg_init_one(<structname>sg</structname>, buffer, ptbuflen + (enc ? authsize : 0)); 4329 aead_request_set_crypt(req, <structname>sg</structname>, <structname>sg</structname>, ptbuflen, iv); 4330</para> 4331</refsect1> 4332</refentry> 4333 4334<refentry id="API-aead-request-set-assoc"> 4335<refentryinfo> 4336 <title>LINUX</title> 4337 <productname>Kernel Hackers Manual</productname> 4338 <date>July 2017</date> 4339</refentryinfo> 4340<refmeta> 4341 <refentrytitle><phrase>aead_request_set_assoc</phrase></refentrytitle> 4342 <manvolnum>9</manvolnum> 4343 <refmiscinfo class="version">4.1.27</refmiscinfo> 4344</refmeta> 4345<refnamediv> 4346 <refname>aead_request_set_assoc</refname> 4347 <refpurpose> 4348 set the associated data scatter / gather list 4349 </refpurpose> 4350</refnamediv> 4351<refsynopsisdiv> 4352 <title>Synopsis</title> 4353 <funcsynopsis><funcprototype> 4354 <funcdef>void <function>aead_request_set_assoc </function></funcdef> 4355 <paramdef>struct aead_request * <parameter>req</parameter></paramdef> 4356 <paramdef>struct scatterlist * <parameter>assoc</parameter></paramdef> 4357 <paramdef>unsigned int <parameter>assoclen</parameter></paramdef> 4358 </funcprototype></funcsynopsis> 4359</refsynopsisdiv> 4360<refsect1> 4361 <title>Arguments</title> 4362 <variablelist> 4363 <varlistentry> 4364 <term><parameter>req</parameter></term> 4365 <listitem> 4366 <para> 4367 request handle 4368 </para> 4369 </listitem> 4370 </varlistentry> 4371 <varlistentry> 4372 <term><parameter>assoc</parameter></term> 4373 <listitem> 4374 <para> 4375 associated data scatter / gather list 4376 </para> 4377 </listitem> 4378 </varlistentry> 4379 <varlistentry> 4380 <term><parameter>assoclen</parameter></term> 4381 <listitem> 4382 <para> 4383 number of bytes to process from <parameter>assoc</parameter> 4384 </para> 4385 </listitem> 4386 </varlistentry> 4387 </variablelist> 4388</refsect1> 4389<refsect1> 4390<title>Description</title> 4391<para> 4392 For encryption, the memory is filled with the associated data. For 4393 decryption, the memory must point to the associated data. 4394</para> 4395</refsect1> 4396</refentry> 4397 4398 </sect1> 4399 <sect1><title>Synchronous Block Cipher API</title> 4400<para> 4401 </para><para> 4402 The synchronous block cipher API is used with the ciphers of type 4403 CRYPTO_ALG_TYPE_BLKCIPHER (listed as type <quote>blkcipher</quote> in /proc/crypto) 4404 </para><para> 4405 Synchronous calls, have a context in the tfm. But since a single tfm can be 4406 used in multiple calls and in parallel, this info should not be changeable 4407 (unless a lock is used). This applies, for example, to the symmetric key. 4408 However, the IV is changeable, so there is an iv field in blkcipher_tfm 4409 structure for synchronous blkcipher api. So, its the only state info that can 4410 be kept for synchronous calls without using a big lock across a tfm. 4411 </para><para> 4412 The block cipher API allows the use of a complete cipher, i.e. a cipher 4413 consisting of a template (a block chaining mode) and a single block cipher 4414 primitive (e.g. AES). 4415 </para><para> 4416 The plaintext data buffer and the ciphertext data buffer are pointed to 4417 by using scatter/gather lists. The cipher operation is performed 4418 on all segments of the provided scatter/gather lists. 4419 </para><para> 4420 The kernel crypto API supports a cipher operation <quote>in-place</quote> which means that 4421 the caller may provide the same scatter/gather list for the plaintext and 4422 cipher text. After the completion of the cipher operation, the plaintext 4423 data is replaced with the ciphertext data in case of an encryption and vice 4424 versa for a decryption. The caller must ensure that the scatter/gather lists 4425 for the output data point to sufficiently large buffers, i.e. multiples of 4426 the block size of the cipher. 4427</para> 4428 4429<refentry id="API-crypto-alloc-blkcipher"> 4430<refentryinfo> 4431 <title>LINUX</title> 4432 <productname>Kernel Hackers Manual</productname> 4433 <date>July 2017</date> 4434</refentryinfo> 4435<refmeta> 4436 <refentrytitle><phrase>crypto_alloc_blkcipher</phrase></refentrytitle> 4437 <manvolnum>9</manvolnum> 4438 <refmiscinfo class="version">4.1.27</refmiscinfo> 4439</refmeta> 4440<refnamediv> 4441 <refname>crypto_alloc_blkcipher</refname> 4442 <refpurpose> 4443 allocate synchronous block cipher handle 4444 </refpurpose> 4445</refnamediv> 4446<refsynopsisdiv> 4447 <title>Synopsis</title> 4448 <funcsynopsis><funcprototype> 4449 <funcdef>struct crypto_blkcipher * <function>crypto_alloc_blkcipher </function></funcdef> 4450 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 4451 <paramdef>u32 <parameter>type</parameter></paramdef> 4452 <paramdef>u32 <parameter>mask</parameter></paramdef> 4453 </funcprototype></funcsynopsis> 4454</refsynopsisdiv> 4455<refsect1> 4456 <title>Arguments</title> 4457 <variablelist> 4458 <varlistentry> 4459 <term><parameter>alg_name</parameter></term> 4460 <listitem> 4461 <para> 4462 is the cra_name / name or cra_driver_name / driver name of the 4463 blkcipher cipher 4464 </para> 4465 </listitem> 4466 </varlistentry> 4467 <varlistentry> 4468 <term><parameter>type</parameter></term> 4469 <listitem> 4470 <para> 4471 specifies the type of the cipher 4472 </para> 4473 </listitem> 4474 </varlistentry> 4475 <varlistentry> 4476 <term><parameter>mask</parameter></term> 4477 <listitem> 4478 <para> 4479 specifies the mask for the cipher 4480 </para> 4481 </listitem> 4482 </varlistentry> 4483 </variablelist> 4484</refsect1> 4485<refsect1> 4486<title>Description</title> 4487<para> 4488 Allocate a cipher handle for a block cipher. The returned struct 4489 crypto_blkcipher is the cipher handle that is required for any subsequent 4490 API invocation for that block cipher. 4491</para> 4492</refsect1> 4493<refsect1> 4494<title>Return</title> 4495<para> 4496 allocated cipher handle in case of success; <function>IS_ERR</function> is true in case 4497 of an error, <function>PTR_ERR</function> returns the error code. 4498</para> 4499</refsect1> 4500</refentry> 4501 4502<refentry id="API-crypto-free-blkcipher"> 4503<refentryinfo> 4504 <title>LINUX</title> 4505 <productname>Kernel Hackers Manual</productname> 4506 <date>July 2017</date> 4507</refentryinfo> 4508<refmeta> 4509 <refentrytitle><phrase>crypto_free_blkcipher</phrase></refentrytitle> 4510 <manvolnum>9</manvolnum> 4511 <refmiscinfo class="version">4.1.27</refmiscinfo> 4512</refmeta> 4513<refnamediv> 4514 <refname>crypto_free_blkcipher</refname> 4515 <refpurpose> 4516 zeroize and free the block cipher handle 4517 </refpurpose> 4518</refnamediv> 4519<refsynopsisdiv> 4520 <title>Synopsis</title> 4521 <funcsynopsis><funcprototype> 4522 <funcdef>void <function>crypto_free_blkcipher </function></funcdef> 4523 <paramdef>struct crypto_blkcipher * <parameter>tfm</parameter></paramdef> 4524 </funcprototype></funcsynopsis> 4525</refsynopsisdiv> 4526<refsect1> 4527 <title>Arguments</title> 4528 <variablelist> 4529 <varlistentry> 4530 <term><parameter>tfm</parameter></term> 4531 <listitem> 4532 <para> 4533 cipher handle to be freed 4534 </para> 4535 </listitem> 4536 </varlistentry> 4537 </variablelist> 4538</refsect1> 4539</refentry> 4540 4541<refentry id="API-crypto-has-blkcipher"> 4542<refentryinfo> 4543 <title>LINUX</title> 4544 <productname>Kernel Hackers Manual</productname> 4545 <date>July 2017</date> 4546</refentryinfo> 4547<refmeta> 4548 <refentrytitle><phrase>crypto_has_blkcipher</phrase></refentrytitle> 4549 <manvolnum>9</manvolnum> 4550 <refmiscinfo class="version">4.1.27</refmiscinfo> 4551</refmeta> 4552<refnamediv> 4553 <refname>crypto_has_blkcipher</refname> 4554 <refpurpose> 4555 Search for the availability of a block cipher 4556 </refpurpose> 4557</refnamediv> 4558<refsynopsisdiv> 4559 <title>Synopsis</title> 4560 <funcsynopsis><funcprototype> 4561 <funcdef>int <function>crypto_has_blkcipher </function></funcdef> 4562 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 4563 <paramdef>u32 <parameter>type</parameter></paramdef> 4564 <paramdef>u32 <parameter>mask</parameter></paramdef> 4565 </funcprototype></funcsynopsis> 4566</refsynopsisdiv> 4567<refsect1> 4568 <title>Arguments</title> 4569 <variablelist> 4570 <varlistentry> 4571 <term><parameter>alg_name</parameter></term> 4572 <listitem> 4573 <para> 4574 is the cra_name / name or cra_driver_name / driver name of the 4575 block cipher 4576 </para> 4577 </listitem> 4578 </varlistentry> 4579 <varlistentry> 4580 <term><parameter>type</parameter></term> 4581 <listitem> 4582 <para> 4583 specifies the type of the cipher 4584 </para> 4585 </listitem> 4586 </varlistentry> 4587 <varlistentry> 4588 <term><parameter>mask</parameter></term> 4589 <listitem> 4590 <para> 4591 specifies the mask for the cipher 4592 </para> 4593 </listitem> 4594 </varlistentry> 4595 </variablelist> 4596</refsect1> 4597<refsect1> 4598<title>Return</title> 4599<para> 4600 true when the block cipher is known to the kernel crypto API; false 4601 otherwise 4602</para> 4603</refsect1> 4604</refentry> 4605 4606<refentry id="API-crypto-blkcipher-name"> 4607<refentryinfo> 4608 <title>LINUX</title> 4609 <productname>Kernel Hackers Manual</productname> 4610 <date>July 2017</date> 4611</refentryinfo> 4612<refmeta> 4613 <refentrytitle><phrase>crypto_blkcipher_name</phrase></refentrytitle> 4614 <manvolnum>9</manvolnum> 4615 <refmiscinfo class="version">4.1.27</refmiscinfo> 4616</refmeta> 4617<refnamediv> 4618 <refname>crypto_blkcipher_name</refname> 4619 <refpurpose> 4620 return the name / cra_name from the cipher handle 4621 </refpurpose> 4622</refnamediv> 4623<refsynopsisdiv> 4624 <title>Synopsis</title> 4625 <funcsynopsis><funcprototype> 4626 <funcdef>const char * <function>crypto_blkcipher_name </function></funcdef> 4627 <paramdef>struct crypto_blkcipher * <parameter>tfm</parameter></paramdef> 4628 </funcprototype></funcsynopsis> 4629</refsynopsisdiv> 4630<refsect1> 4631 <title>Arguments</title> 4632 <variablelist> 4633 <varlistentry> 4634 <term><parameter>tfm</parameter></term> 4635 <listitem> 4636 <para> 4637 cipher handle 4638 </para> 4639 </listitem> 4640 </varlistentry> 4641 </variablelist> 4642</refsect1> 4643<refsect1> 4644<title>Return</title> 4645<para> 4646 The character string holding the name of the cipher 4647</para> 4648</refsect1> 4649</refentry> 4650 4651<refentry id="API-crypto-blkcipher-ivsize"> 4652<refentryinfo> 4653 <title>LINUX</title> 4654 <productname>Kernel Hackers Manual</productname> 4655 <date>July 2017</date> 4656</refentryinfo> 4657<refmeta> 4658 <refentrytitle><phrase>crypto_blkcipher_ivsize</phrase></refentrytitle> 4659 <manvolnum>9</manvolnum> 4660 <refmiscinfo class="version">4.1.27</refmiscinfo> 4661</refmeta> 4662<refnamediv> 4663 <refname>crypto_blkcipher_ivsize</refname> 4664 <refpurpose> 4665 obtain IV size 4666 </refpurpose> 4667</refnamediv> 4668<refsynopsisdiv> 4669 <title>Synopsis</title> 4670 <funcsynopsis><funcprototype> 4671 <funcdef>unsigned int <function>crypto_blkcipher_ivsize </function></funcdef> 4672 <paramdef>struct crypto_blkcipher * <parameter>tfm</parameter></paramdef> 4673 </funcprototype></funcsynopsis> 4674</refsynopsisdiv> 4675<refsect1> 4676 <title>Arguments</title> 4677 <variablelist> 4678 <varlistentry> 4679 <term><parameter>tfm</parameter></term> 4680 <listitem> 4681 <para> 4682 cipher handle 4683 </para> 4684 </listitem> 4685 </varlistentry> 4686 </variablelist> 4687</refsect1> 4688<refsect1> 4689<title>Description</title> 4690<para> 4691 The size of the IV for the block cipher referenced by the cipher handle is 4692 returned. This IV size may be zero if the cipher does not need an IV. 4693</para> 4694</refsect1> 4695<refsect1> 4696<title>Return</title> 4697<para> 4698 IV size in bytes 4699</para> 4700</refsect1> 4701</refentry> 4702 4703<refentry id="API-crypto-blkcipher-blocksize"> 4704<refentryinfo> 4705 <title>LINUX</title> 4706 <productname>Kernel Hackers Manual</productname> 4707 <date>July 2017</date> 4708</refentryinfo> 4709<refmeta> 4710 <refentrytitle><phrase>crypto_blkcipher_blocksize</phrase></refentrytitle> 4711 <manvolnum>9</manvolnum> 4712 <refmiscinfo class="version">4.1.27</refmiscinfo> 4713</refmeta> 4714<refnamediv> 4715 <refname>crypto_blkcipher_blocksize</refname> 4716 <refpurpose> 4717 obtain block size of cipher 4718 </refpurpose> 4719</refnamediv> 4720<refsynopsisdiv> 4721 <title>Synopsis</title> 4722 <funcsynopsis><funcprototype> 4723 <funcdef>unsigned int <function>crypto_blkcipher_blocksize </function></funcdef> 4724 <paramdef>struct crypto_blkcipher * <parameter>tfm</parameter></paramdef> 4725 </funcprototype></funcsynopsis> 4726</refsynopsisdiv> 4727<refsect1> 4728 <title>Arguments</title> 4729 <variablelist> 4730 <varlistentry> 4731 <term><parameter>tfm</parameter></term> 4732 <listitem> 4733 <para> 4734 cipher handle 4735 </para> 4736 </listitem> 4737 </varlistentry> 4738 </variablelist> 4739</refsect1> 4740<refsect1> 4741<title>Description</title> 4742<para> 4743 The block size for the block cipher referenced with the cipher handle is 4744 returned. The caller may use that information to allocate appropriate 4745 memory for the data returned by the encryption or decryption operation. 4746</para> 4747</refsect1> 4748<refsect1> 4749<title>Return</title> 4750<para> 4751 block size of cipher 4752</para> 4753</refsect1> 4754</refentry> 4755 4756<refentry id="API-crypto-blkcipher-setkey"> 4757<refentryinfo> 4758 <title>LINUX</title> 4759 <productname>Kernel Hackers Manual</productname> 4760 <date>July 2017</date> 4761</refentryinfo> 4762<refmeta> 4763 <refentrytitle><phrase>crypto_blkcipher_setkey</phrase></refentrytitle> 4764 <manvolnum>9</manvolnum> 4765 <refmiscinfo class="version">4.1.27</refmiscinfo> 4766</refmeta> 4767<refnamediv> 4768 <refname>crypto_blkcipher_setkey</refname> 4769 <refpurpose> 4770 set key for cipher 4771 </refpurpose> 4772</refnamediv> 4773<refsynopsisdiv> 4774 <title>Synopsis</title> 4775 <funcsynopsis><funcprototype> 4776 <funcdef>int <function>crypto_blkcipher_setkey </function></funcdef> 4777 <paramdef>struct crypto_blkcipher * <parameter>tfm</parameter></paramdef> 4778 <paramdef>const u8 * <parameter>key</parameter></paramdef> 4779 <paramdef>unsigned int <parameter>keylen</parameter></paramdef> 4780 </funcprototype></funcsynopsis> 4781</refsynopsisdiv> 4782<refsect1> 4783 <title>Arguments</title> 4784 <variablelist> 4785 <varlistentry> 4786 <term><parameter>tfm</parameter></term> 4787 <listitem> 4788 <para> 4789 cipher handle 4790 </para> 4791 </listitem> 4792 </varlistentry> 4793 <varlistentry> 4794 <term><parameter>key</parameter></term> 4795 <listitem> 4796 <para> 4797 buffer holding the key 4798 </para> 4799 </listitem> 4800 </varlistentry> 4801 <varlistentry> 4802 <term><parameter>keylen</parameter></term> 4803 <listitem> 4804 <para> 4805 length of the key in bytes 4806 </para> 4807 </listitem> 4808 </varlistentry> 4809 </variablelist> 4810</refsect1> 4811<refsect1> 4812<title>Description</title> 4813<para> 4814 The caller provided key is set for the block cipher referenced by the cipher 4815 handle. 4816 </para><para> 4817 4818 Note, the key length determines the cipher type. Many block ciphers implement 4819 different cipher modes depending on the key size, such as AES-128 vs AES-192 4820 vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128 4821 is performed. 4822</para> 4823</refsect1> 4824<refsect1> 4825<title>Return</title> 4826<para> 4827 0 if the setting of the key was successful; < 0 if an error occurred 4828</para> 4829</refsect1> 4830</refentry> 4831 4832<refentry id="API-crypto-blkcipher-encrypt"> 4833<refentryinfo> 4834 <title>LINUX</title> 4835 <productname>Kernel Hackers Manual</productname> 4836 <date>July 2017</date> 4837</refentryinfo> 4838<refmeta> 4839 <refentrytitle><phrase>crypto_blkcipher_encrypt</phrase></refentrytitle> 4840 <manvolnum>9</manvolnum> 4841 <refmiscinfo class="version">4.1.27</refmiscinfo> 4842</refmeta> 4843<refnamediv> 4844 <refname>crypto_blkcipher_encrypt</refname> 4845 <refpurpose> 4846 encrypt plaintext 4847 </refpurpose> 4848</refnamediv> 4849<refsynopsisdiv> 4850 <title>Synopsis</title> 4851 <funcsynopsis><funcprototype> 4852 <funcdef>int <function>crypto_blkcipher_encrypt </function></funcdef> 4853 <paramdef>struct blkcipher_desc * <parameter>desc</parameter></paramdef> 4854 <paramdef>struct scatterlist * <parameter>dst</parameter></paramdef> 4855 <paramdef>struct scatterlist * <parameter>src</parameter></paramdef> 4856 <paramdef>unsigned int <parameter>nbytes</parameter></paramdef> 4857 </funcprototype></funcsynopsis> 4858</refsynopsisdiv> 4859<refsect1> 4860 <title>Arguments</title> 4861 <variablelist> 4862 <varlistentry> 4863 <term><parameter>desc</parameter></term> 4864 <listitem> 4865 <para> 4866 reference to the block cipher handle with meta data 4867 </para> 4868 </listitem> 4869 </varlistentry> 4870 <varlistentry> 4871 <term><parameter>dst</parameter></term> 4872 <listitem> 4873 <para> 4874 scatter/gather list that is filled by the cipher operation with the 4875 ciphertext 4876 </para> 4877 </listitem> 4878 </varlistentry> 4879 <varlistentry> 4880 <term><parameter>src</parameter></term> 4881 <listitem> 4882 <para> 4883 scatter/gather list that holds the plaintext 4884 </para> 4885 </listitem> 4886 </varlistentry> 4887 <varlistentry> 4888 <term><parameter>nbytes</parameter></term> 4889 <listitem> 4890 <para> 4891 number of bytes of the plaintext to encrypt. 4892 </para> 4893 </listitem> 4894 </varlistentry> 4895 </variablelist> 4896</refsect1> 4897<refsect1> 4898<title>Description</title> 4899<para> 4900 Encrypt plaintext data using the IV set by the caller with a preceding 4901 call of crypto_blkcipher_set_iv. 4902 </para><para> 4903 4904 The blkcipher_desc data structure must be filled by the caller and can 4905 reside on the stack. The caller must fill desc as follows: desc.tfm is filled 4906 with the block cipher handle; desc.flags is filled with either 4907 CRYPTO_TFM_REQ_MAY_SLEEP or 0. 4908</para> 4909</refsect1> 4910<refsect1> 4911<title>Return</title> 4912<para> 4913 0 if the cipher operation was successful; < 0 if an error occurred 4914</para> 4915</refsect1> 4916</refentry> 4917 4918<refentry id="API-crypto-blkcipher-encrypt-iv"> 4919<refentryinfo> 4920 <title>LINUX</title> 4921 <productname>Kernel Hackers Manual</productname> 4922 <date>July 2017</date> 4923</refentryinfo> 4924<refmeta> 4925 <refentrytitle><phrase>crypto_blkcipher_encrypt_iv</phrase></refentrytitle> 4926 <manvolnum>9</manvolnum> 4927 <refmiscinfo class="version">4.1.27</refmiscinfo> 4928</refmeta> 4929<refnamediv> 4930 <refname>crypto_blkcipher_encrypt_iv</refname> 4931 <refpurpose> 4932 encrypt plaintext with dedicated IV 4933 </refpurpose> 4934</refnamediv> 4935<refsynopsisdiv> 4936 <title>Synopsis</title> 4937 <funcsynopsis><funcprototype> 4938 <funcdef>int <function>crypto_blkcipher_encrypt_iv </function></funcdef> 4939 <paramdef>struct blkcipher_desc * <parameter>desc</parameter></paramdef> 4940 <paramdef>struct scatterlist * <parameter>dst</parameter></paramdef> 4941 <paramdef>struct scatterlist * <parameter>src</parameter></paramdef> 4942 <paramdef>unsigned int <parameter>nbytes</parameter></paramdef> 4943 </funcprototype></funcsynopsis> 4944</refsynopsisdiv> 4945<refsect1> 4946 <title>Arguments</title> 4947 <variablelist> 4948 <varlistentry> 4949 <term><parameter>desc</parameter></term> 4950 <listitem> 4951 <para> 4952 reference to the block cipher handle with meta data 4953 </para> 4954 </listitem> 4955 </varlistentry> 4956 <varlistentry> 4957 <term><parameter>dst</parameter></term> 4958 <listitem> 4959 <para> 4960 scatter/gather list that is filled by the cipher operation with the 4961 ciphertext 4962 </para> 4963 </listitem> 4964 </varlistentry> 4965 <varlistentry> 4966 <term><parameter>src</parameter></term> 4967 <listitem> 4968 <para> 4969 scatter/gather list that holds the plaintext 4970 </para> 4971 </listitem> 4972 </varlistentry> 4973 <varlistentry> 4974 <term><parameter>nbytes</parameter></term> 4975 <listitem> 4976 <para> 4977 number of bytes of the plaintext to encrypt. 4978 </para> 4979 </listitem> 4980 </varlistentry> 4981 </variablelist> 4982</refsect1> 4983<refsect1> 4984<title>Description</title> 4985<para> 4986 Encrypt plaintext data with the use of an IV that is solely used for this 4987 cipher operation. Any previously set IV is not used. 4988 </para><para> 4989 4990 The blkcipher_desc data structure must be filled by the caller and can 4991 reside on the stack. The caller must fill desc as follows: desc.tfm is filled 4992 with the block cipher handle; desc.info is filled with the IV to be used for 4993 the current operation; desc.flags is filled with either 4994 CRYPTO_TFM_REQ_MAY_SLEEP or 0. 4995</para> 4996</refsect1> 4997<refsect1> 4998<title>Return</title> 4999<para> 5000 0 if the cipher operation was successful; < 0 if an error occurred 5001</para> 5002</refsect1> 5003</refentry> 5004 5005<refentry id="API-crypto-blkcipher-decrypt"> 5006<refentryinfo> 5007 <title>LINUX</title> 5008 <productname>Kernel Hackers Manual</productname> 5009 <date>July 2017</date> 5010</refentryinfo> 5011<refmeta> 5012 <refentrytitle><phrase>crypto_blkcipher_decrypt</phrase></refentrytitle> 5013 <manvolnum>9</manvolnum> 5014 <refmiscinfo class="version">4.1.27</refmiscinfo> 5015</refmeta> 5016<refnamediv> 5017 <refname>crypto_blkcipher_decrypt</refname> 5018 <refpurpose> 5019 decrypt ciphertext 5020 </refpurpose> 5021</refnamediv> 5022<refsynopsisdiv> 5023 <title>Synopsis</title> 5024 <funcsynopsis><funcprototype> 5025 <funcdef>int <function>crypto_blkcipher_decrypt </function></funcdef> 5026 <paramdef>struct blkcipher_desc * <parameter>desc</parameter></paramdef> 5027 <paramdef>struct scatterlist * <parameter>dst</parameter></paramdef> 5028 <paramdef>struct scatterlist * <parameter>src</parameter></paramdef> 5029 <paramdef>unsigned int <parameter>nbytes</parameter></paramdef> 5030 </funcprototype></funcsynopsis> 5031</refsynopsisdiv> 5032<refsect1> 5033 <title>Arguments</title> 5034 <variablelist> 5035 <varlistentry> 5036 <term><parameter>desc</parameter></term> 5037 <listitem> 5038 <para> 5039 reference to the block cipher handle with meta data 5040 </para> 5041 </listitem> 5042 </varlistentry> 5043 <varlistentry> 5044 <term><parameter>dst</parameter></term> 5045 <listitem> 5046 <para> 5047 scatter/gather list that is filled by the cipher operation with the 5048 plaintext 5049 </para> 5050 </listitem> 5051 </varlistentry> 5052 <varlistentry> 5053 <term><parameter>src</parameter></term> 5054 <listitem> 5055 <para> 5056 scatter/gather list that holds the ciphertext 5057 </para> 5058 </listitem> 5059 </varlistentry> 5060 <varlistentry> 5061 <term><parameter>nbytes</parameter></term> 5062 <listitem> 5063 <para> 5064 number of bytes of the ciphertext to decrypt. 5065 </para> 5066 </listitem> 5067 </varlistentry> 5068 </variablelist> 5069</refsect1> 5070<refsect1> 5071<title>Description</title> 5072<para> 5073 Decrypt ciphertext data using the IV set by the caller with a preceding 5074 call of crypto_blkcipher_set_iv. 5075 </para><para> 5076 5077 The blkcipher_desc data structure must be filled by the caller as documented 5078 for the crypto_blkcipher_encrypt call above. 5079</para> 5080</refsect1> 5081<refsect1> 5082<title>Return</title> 5083<para> 5084 0 if the cipher operation was successful; < 0 if an error occurred 5085</para> 5086</refsect1> 5087</refentry> 5088 5089<refentry id="API-crypto-blkcipher-decrypt-iv"> 5090<refentryinfo> 5091 <title>LINUX</title> 5092 <productname>Kernel Hackers Manual</productname> 5093 <date>July 2017</date> 5094</refentryinfo> 5095<refmeta> 5096 <refentrytitle><phrase>crypto_blkcipher_decrypt_iv</phrase></refentrytitle> 5097 <manvolnum>9</manvolnum> 5098 <refmiscinfo class="version">4.1.27</refmiscinfo> 5099</refmeta> 5100<refnamediv> 5101 <refname>crypto_blkcipher_decrypt_iv</refname> 5102 <refpurpose> 5103 decrypt ciphertext with dedicated IV 5104 </refpurpose> 5105</refnamediv> 5106<refsynopsisdiv> 5107 <title>Synopsis</title> 5108 <funcsynopsis><funcprototype> 5109 <funcdef>int <function>crypto_blkcipher_decrypt_iv </function></funcdef> 5110 <paramdef>struct blkcipher_desc * <parameter>desc</parameter></paramdef> 5111 <paramdef>struct scatterlist * <parameter>dst</parameter></paramdef> 5112 <paramdef>struct scatterlist * <parameter>src</parameter></paramdef> 5113 <paramdef>unsigned int <parameter>nbytes</parameter></paramdef> 5114 </funcprototype></funcsynopsis> 5115</refsynopsisdiv> 5116<refsect1> 5117 <title>Arguments</title> 5118 <variablelist> 5119 <varlistentry> 5120 <term><parameter>desc</parameter></term> 5121 <listitem> 5122 <para> 5123 reference to the block cipher handle with meta data 5124 </para> 5125 </listitem> 5126 </varlistentry> 5127 <varlistentry> 5128 <term><parameter>dst</parameter></term> 5129 <listitem> 5130 <para> 5131 scatter/gather list that is filled by the cipher operation with the 5132 plaintext 5133 </para> 5134 </listitem> 5135 </varlistentry> 5136 <varlistentry> 5137 <term><parameter>src</parameter></term> 5138 <listitem> 5139 <para> 5140 scatter/gather list that holds the ciphertext 5141 </para> 5142 </listitem> 5143 </varlistentry> 5144 <varlistentry> 5145 <term><parameter>nbytes</parameter></term> 5146 <listitem> 5147 <para> 5148 number of bytes of the ciphertext to decrypt. 5149 </para> 5150 </listitem> 5151 </varlistentry> 5152 </variablelist> 5153</refsect1> 5154<refsect1> 5155<title>Description</title> 5156<para> 5157 Decrypt ciphertext data with the use of an IV that is solely used for this 5158 cipher operation. Any previously set IV is not used. 5159 </para><para> 5160 5161 The blkcipher_desc data structure must be filled by the caller as documented 5162 for the crypto_blkcipher_encrypt_iv call above. 5163</para> 5164</refsect1> 5165<refsect1> 5166<title>Return</title> 5167<para> 5168 0 if the cipher operation was successful; < 0 if an error occurred 5169</para> 5170</refsect1> 5171</refentry> 5172 5173<refentry id="API-crypto-blkcipher-set-iv"> 5174<refentryinfo> 5175 <title>LINUX</title> 5176 <productname>Kernel Hackers Manual</productname> 5177 <date>July 2017</date> 5178</refentryinfo> 5179<refmeta> 5180 <refentrytitle><phrase>crypto_blkcipher_set_iv</phrase></refentrytitle> 5181 <manvolnum>9</manvolnum> 5182 <refmiscinfo class="version">4.1.27</refmiscinfo> 5183</refmeta> 5184<refnamediv> 5185 <refname>crypto_blkcipher_set_iv</refname> 5186 <refpurpose> 5187 set IV for cipher 5188 </refpurpose> 5189</refnamediv> 5190<refsynopsisdiv> 5191 <title>Synopsis</title> 5192 <funcsynopsis><funcprototype> 5193 <funcdef>void <function>crypto_blkcipher_set_iv </function></funcdef> 5194 <paramdef>struct crypto_blkcipher * <parameter>tfm</parameter></paramdef> 5195 <paramdef>const u8 * <parameter>src</parameter></paramdef> 5196 <paramdef>unsigned int <parameter>len</parameter></paramdef> 5197 </funcprototype></funcsynopsis> 5198</refsynopsisdiv> 5199<refsect1> 5200 <title>Arguments</title> 5201 <variablelist> 5202 <varlistentry> 5203 <term><parameter>tfm</parameter></term> 5204 <listitem> 5205 <para> 5206 cipher handle 5207 </para> 5208 </listitem> 5209 </varlistentry> 5210 <varlistentry> 5211 <term><parameter>src</parameter></term> 5212 <listitem> 5213 <para> 5214 buffer holding the IV 5215 </para> 5216 </listitem> 5217 </varlistentry> 5218 <varlistentry> 5219 <term><parameter>len</parameter></term> 5220 <listitem> 5221 <para> 5222 length of the IV in bytes 5223 </para> 5224 </listitem> 5225 </varlistentry> 5226 </variablelist> 5227</refsect1> 5228<refsect1> 5229<title>Description</title> 5230<para> 5231 The caller provided IV is set for the block cipher referenced by the cipher 5232 handle. 5233</para> 5234</refsect1> 5235</refentry> 5236 5237<refentry id="API-crypto-blkcipher-get-iv"> 5238<refentryinfo> 5239 <title>LINUX</title> 5240 <productname>Kernel Hackers Manual</productname> 5241 <date>July 2017</date> 5242</refentryinfo> 5243<refmeta> 5244 <refentrytitle><phrase>crypto_blkcipher_get_iv</phrase></refentrytitle> 5245 <manvolnum>9</manvolnum> 5246 <refmiscinfo class="version">4.1.27</refmiscinfo> 5247</refmeta> 5248<refnamediv> 5249 <refname>crypto_blkcipher_get_iv</refname> 5250 <refpurpose> 5251 obtain IV from cipher 5252 </refpurpose> 5253</refnamediv> 5254<refsynopsisdiv> 5255 <title>Synopsis</title> 5256 <funcsynopsis><funcprototype> 5257 <funcdef>void <function>crypto_blkcipher_get_iv </function></funcdef> 5258 <paramdef>struct crypto_blkcipher * <parameter>tfm</parameter></paramdef> 5259 <paramdef>u8 * <parameter>dst</parameter></paramdef> 5260 <paramdef>unsigned int <parameter>len</parameter></paramdef> 5261 </funcprototype></funcsynopsis> 5262</refsynopsisdiv> 5263<refsect1> 5264 <title>Arguments</title> 5265 <variablelist> 5266 <varlistentry> 5267 <term><parameter>tfm</parameter></term> 5268 <listitem> 5269 <para> 5270 cipher handle 5271 </para> 5272 </listitem> 5273 </varlistentry> 5274 <varlistentry> 5275 <term><parameter>dst</parameter></term> 5276 <listitem> 5277 <para> 5278 buffer filled with the IV 5279 </para> 5280 </listitem> 5281 </varlistentry> 5282 <varlistentry> 5283 <term><parameter>len</parameter></term> 5284 <listitem> 5285 <para> 5286 length of the buffer dst 5287 </para> 5288 </listitem> 5289 </varlistentry> 5290 </variablelist> 5291</refsect1> 5292<refsect1> 5293<title>Description</title> 5294<para> 5295 The caller can obtain the IV set for the block cipher referenced by the 5296 cipher handle and store it into the user-provided buffer. If the buffer 5297 has an insufficient space, the IV is truncated to fit the buffer. 5298</para> 5299</refsect1> 5300</refentry> 5301 5302 </sect1> 5303 <sect1><title>Single Block Cipher API</title> 5304<para> 5305 </para><para> 5306 The single block cipher API is used with the ciphers of type 5307 CRYPTO_ALG_TYPE_CIPHER (listed as type <quote>cipher</quote> in /proc/crypto). 5308 </para><para> 5309 Using the single block cipher API calls, operations with the basic cipher 5310 primitive can be implemented. These cipher primitives exclude any block 5311 chaining operations including IV handling. 5312 </para><para> 5313 The purpose of this single block cipher API is to support the implementation 5314 of templates or other concepts that only need to perform the cipher operation 5315 on one block at a time. Templates invoke the underlying cipher primitive 5316 block-wise and process either the input or the output data of these cipher 5317 operations. 5318</para> 5319 5320<refentry id="API-crypto-alloc-cipher"> 5321<refentryinfo> 5322 <title>LINUX</title> 5323 <productname>Kernel Hackers Manual</productname> 5324 <date>July 2017</date> 5325</refentryinfo> 5326<refmeta> 5327 <refentrytitle><phrase>crypto_alloc_cipher</phrase></refentrytitle> 5328 <manvolnum>9</manvolnum> 5329 <refmiscinfo class="version">4.1.27</refmiscinfo> 5330</refmeta> 5331<refnamediv> 5332 <refname>crypto_alloc_cipher</refname> 5333 <refpurpose> 5334 allocate single block cipher handle 5335 </refpurpose> 5336</refnamediv> 5337<refsynopsisdiv> 5338 <title>Synopsis</title> 5339 <funcsynopsis><funcprototype> 5340 <funcdef>struct crypto_cipher * <function>crypto_alloc_cipher </function></funcdef> 5341 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 5342 <paramdef>u32 <parameter>type</parameter></paramdef> 5343 <paramdef>u32 <parameter>mask</parameter></paramdef> 5344 </funcprototype></funcsynopsis> 5345</refsynopsisdiv> 5346<refsect1> 5347 <title>Arguments</title> 5348 <variablelist> 5349 <varlistentry> 5350 <term><parameter>alg_name</parameter></term> 5351 <listitem> 5352 <para> 5353 is the cra_name / name or cra_driver_name / driver name of the 5354 single block cipher 5355 </para> 5356 </listitem> 5357 </varlistentry> 5358 <varlistentry> 5359 <term><parameter>type</parameter></term> 5360 <listitem> 5361 <para> 5362 specifies the type of the cipher 5363 </para> 5364 </listitem> 5365 </varlistentry> 5366 <varlistentry> 5367 <term><parameter>mask</parameter></term> 5368 <listitem> 5369 <para> 5370 specifies the mask for the cipher 5371 </para> 5372 </listitem> 5373 </varlistentry> 5374 </variablelist> 5375</refsect1> 5376<refsect1> 5377<title>Description</title> 5378<para> 5379 Allocate a cipher handle for a single block cipher. The returned struct 5380 crypto_cipher is the cipher handle that is required for any subsequent API 5381 invocation for that single block cipher. 5382</para> 5383</refsect1> 5384<refsect1> 5385<title>Return</title> 5386<para> 5387 allocated cipher handle in case of success; <function>IS_ERR</function> is true in case 5388 of an error, <function>PTR_ERR</function> returns the error code. 5389</para> 5390</refsect1> 5391</refentry> 5392 5393<refentry id="API-crypto-free-cipher"> 5394<refentryinfo> 5395 <title>LINUX</title> 5396 <productname>Kernel Hackers Manual</productname> 5397 <date>July 2017</date> 5398</refentryinfo> 5399<refmeta> 5400 <refentrytitle><phrase>crypto_free_cipher</phrase></refentrytitle> 5401 <manvolnum>9</manvolnum> 5402 <refmiscinfo class="version">4.1.27</refmiscinfo> 5403</refmeta> 5404<refnamediv> 5405 <refname>crypto_free_cipher</refname> 5406 <refpurpose> 5407 zeroize and free the single block cipher handle 5408 </refpurpose> 5409</refnamediv> 5410<refsynopsisdiv> 5411 <title>Synopsis</title> 5412 <funcsynopsis><funcprototype> 5413 <funcdef>void <function>crypto_free_cipher </function></funcdef> 5414 <paramdef>struct crypto_cipher * <parameter>tfm</parameter></paramdef> 5415 </funcprototype></funcsynopsis> 5416</refsynopsisdiv> 5417<refsect1> 5418 <title>Arguments</title> 5419 <variablelist> 5420 <varlistentry> 5421 <term><parameter>tfm</parameter></term> 5422 <listitem> 5423 <para> 5424 cipher handle to be freed 5425 </para> 5426 </listitem> 5427 </varlistentry> 5428 </variablelist> 5429</refsect1> 5430</refentry> 5431 5432<refentry id="API-crypto-has-cipher"> 5433<refentryinfo> 5434 <title>LINUX</title> 5435 <productname>Kernel Hackers Manual</productname> 5436 <date>July 2017</date> 5437</refentryinfo> 5438<refmeta> 5439 <refentrytitle><phrase>crypto_has_cipher</phrase></refentrytitle> 5440 <manvolnum>9</manvolnum> 5441 <refmiscinfo class="version">4.1.27</refmiscinfo> 5442</refmeta> 5443<refnamediv> 5444 <refname>crypto_has_cipher</refname> 5445 <refpurpose> 5446 Search for the availability of a single block cipher 5447 </refpurpose> 5448</refnamediv> 5449<refsynopsisdiv> 5450 <title>Synopsis</title> 5451 <funcsynopsis><funcprototype> 5452 <funcdef>int <function>crypto_has_cipher </function></funcdef> 5453 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 5454 <paramdef>u32 <parameter>type</parameter></paramdef> 5455 <paramdef>u32 <parameter>mask</parameter></paramdef> 5456 </funcprototype></funcsynopsis> 5457</refsynopsisdiv> 5458<refsect1> 5459 <title>Arguments</title> 5460 <variablelist> 5461 <varlistentry> 5462 <term><parameter>alg_name</parameter></term> 5463 <listitem> 5464 <para> 5465 is the cra_name / name or cra_driver_name / driver name of the 5466 single block cipher 5467 </para> 5468 </listitem> 5469 </varlistentry> 5470 <varlistentry> 5471 <term><parameter>type</parameter></term> 5472 <listitem> 5473 <para> 5474 specifies the type of the cipher 5475 </para> 5476 </listitem> 5477 </varlistentry> 5478 <varlistentry> 5479 <term><parameter>mask</parameter></term> 5480 <listitem> 5481 <para> 5482 specifies the mask for the cipher 5483 </para> 5484 </listitem> 5485 </varlistentry> 5486 </variablelist> 5487</refsect1> 5488<refsect1> 5489<title>Return</title> 5490<para> 5491 true when the single block cipher is known to the kernel crypto API; 5492 false otherwise 5493</para> 5494</refsect1> 5495</refentry> 5496 5497<refentry id="API-crypto-cipher-blocksize"> 5498<refentryinfo> 5499 <title>LINUX</title> 5500 <productname>Kernel Hackers Manual</productname> 5501 <date>July 2017</date> 5502</refentryinfo> 5503<refmeta> 5504 <refentrytitle><phrase>crypto_cipher_blocksize</phrase></refentrytitle> 5505 <manvolnum>9</manvolnum> 5506 <refmiscinfo class="version">4.1.27</refmiscinfo> 5507</refmeta> 5508<refnamediv> 5509 <refname>crypto_cipher_blocksize</refname> 5510 <refpurpose> 5511 obtain block size for cipher 5512 </refpurpose> 5513</refnamediv> 5514<refsynopsisdiv> 5515 <title>Synopsis</title> 5516 <funcsynopsis><funcprototype> 5517 <funcdef>unsigned int <function>crypto_cipher_blocksize </function></funcdef> 5518 <paramdef>struct crypto_cipher * <parameter>tfm</parameter></paramdef> 5519 </funcprototype></funcsynopsis> 5520</refsynopsisdiv> 5521<refsect1> 5522 <title>Arguments</title> 5523 <variablelist> 5524 <varlistentry> 5525 <term><parameter>tfm</parameter></term> 5526 <listitem> 5527 <para> 5528 cipher handle 5529 </para> 5530 </listitem> 5531 </varlistentry> 5532 </variablelist> 5533</refsect1> 5534<refsect1> 5535<title>Description</title> 5536<para> 5537 The block size for the single block cipher referenced with the cipher handle 5538 tfm is returned. The caller may use that information to allocate appropriate 5539 memory for the data returned by the encryption or decryption operation 5540</para> 5541</refsect1> 5542<refsect1> 5543<title>Return</title> 5544<para> 5545 block size of cipher 5546</para> 5547</refsect1> 5548</refentry> 5549 5550<refentry id="API-crypto-cipher-setkey"> 5551<refentryinfo> 5552 <title>LINUX</title> 5553 <productname>Kernel Hackers Manual</productname> 5554 <date>July 2017</date> 5555</refentryinfo> 5556<refmeta> 5557 <refentrytitle><phrase>crypto_cipher_setkey</phrase></refentrytitle> 5558 <manvolnum>9</manvolnum> 5559 <refmiscinfo class="version">4.1.27</refmiscinfo> 5560</refmeta> 5561<refnamediv> 5562 <refname>crypto_cipher_setkey</refname> 5563 <refpurpose> 5564 set key for cipher 5565 </refpurpose> 5566</refnamediv> 5567<refsynopsisdiv> 5568 <title>Synopsis</title> 5569 <funcsynopsis><funcprototype> 5570 <funcdef>int <function>crypto_cipher_setkey </function></funcdef> 5571 <paramdef>struct crypto_cipher * <parameter>tfm</parameter></paramdef> 5572 <paramdef>const u8 * <parameter>key</parameter></paramdef> 5573 <paramdef>unsigned int <parameter>keylen</parameter></paramdef> 5574 </funcprototype></funcsynopsis> 5575</refsynopsisdiv> 5576<refsect1> 5577 <title>Arguments</title> 5578 <variablelist> 5579 <varlistentry> 5580 <term><parameter>tfm</parameter></term> 5581 <listitem> 5582 <para> 5583 cipher handle 5584 </para> 5585 </listitem> 5586 </varlistentry> 5587 <varlistentry> 5588 <term><parameter>key</parameter></term> 5589 <listitem> 5590 <para> 5591 buffer holding the key 5592 </para> 5593 </listitem> 5594 </varlistentry> 5595 <varlistentry> 5596 <term><parameter>keylen</parameter></term> 5597 <listitem> 5598 <para> 5599 length of the key in bytes 5600 </para> 5601 </listitem> 5602 </varlistentry> 5603 </variablelist> 5604</refsect1> 5605<refsect1> 5606<title>Description</title> 5607<para> 5608 The caller provided key is set for the single block cipher referenced by the 5609 cipher handle. 5610 </para><para> 5611 5612 Note, the key length determines the cipher type. Many block ciphers implement 5613 different cipher modes depending on the key size, such as AES-128 vs AES-192 5614 vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128 5615 is performed. 5616</para> 5617</refsect1> 5618<refsect1> 5619<title>Return</title> 5620<para> 5621 0 if the setting of the key was successful; < 0 if an error occurred 5622</para> 5623</refsect1> 5624</refentry> 5625 5626<refentry id="API-crypto-cipher-encrypt-one"> 5627<refentryinfo> 5628 <title>LINUX</title> 5629 <productname>Kernel Hackers Manual</productname> 5630 <date>July 2017</date> 5631</refentryinfo> 5632<refmeta> 5633 <refentrytitle><phrase>crypto_cipher_encrypt_one</phrase></refentrytitle> 5634 <manvolnum>9</manvolnum> 5635 <refmiscinfo class="version">4.1.27</refmiscinfo> 5636</refmeta> 5637<refnamediv> 5638 <refname>crypto_cipher_encrypt_one</refname> 5639 <refpurpose> 5640 encrypt one block of plaintext 5641 </refpurpose> 5642</refnamediv> 5643<refsynopsisdiv> 5644 <title>Synopsis</title> 5645 <funcsynopsis><funcprototype> 5646 <funcdef>void <function>crypto_cipher_encrypt_one </function></funcdef> 5647 <paramdef>struct crypto_cipher * <parameter>tfm</parameter></paramdef> 5648 <paramdef>u8 * <parameter>dst</parameter></paramdef> 5649 <paramdef>const u8 * <parameter>src</parameter></paramdef> 5650 </funcprototype></funcsynopsis> 5651</refsynopsisdiv> 5652<refsect1> 5653 <title>Arguments</title> 5654 <variablelist> 5655 <varlistentry> 5656 <term><parameter>tfm</parameter></term> 5657 <listitem> 5658 <para> 5659 cipher handle 5660 </para> 5661 </listitem> 5662 </varlistentry> 5663 <varlistentry> 5664 <term><parameter>dst</parameter></term> 5665 <listitem> 5666 <para> 5667 points to the buffer that will be filled with the ciphertext 5668 </para> 5669 </listitem> 5670 </varlistentry> 5671 <varlistentry> 5672 <term><parameter>src</parameter></term> 5673 <listitem> 5674 <para> 5675 buffer holding the plaintext to be encrypted 5676 </para> 5677 </listitem> 5678 </varlistentry> 5679 </variablelist> 5680</refsect1> 5681<refsect1> 5682<title>Description</title> 5683<para> 5684 Invoke the encryption operation of one block. The caller must ensure that 5685 the plaintext and ciphertext buffers are at least one block in size. 5686</para> 5687</refsect1> 5688</refentry> 5689 5690<refentry id="API-crypto-cipher-decrypt-one"> 5691<refentryinfo> 5692 <title>LINUX</title> 5693 <productname>Kernel Hackers Manual</productname> 5694 <date>July 2017</date> 5695</refentryinfo> 5696<refmeta> 5697 <refentrytitle><phrase>crypto_cipher_decrypt_one</phrase></refentrytitle> 5698 <manvolnum>9</manvolnum> 5699 <refmiscinfo class="version">4.1.27</refmiscinfo> 5700</refmeta> 5701<refnamediv> 5702 <refname>crypto_cipher_decrypt_one</refname> 5703 <refpurpose> 5704 decrypt one block of ciphertext 5705 </refpurpose> 5706</refnamediv> 5707<refsynopsisdiv> 5708 <title>Synopsis</title> 5709 <funcsynopsis><funcprototype> 5710 <funcdef>void <function>crypto_cipher_decrypt_one </function></funcdef> 5711 <paramdef>struct crypto_cipher * <parameter>tfm</parameter></paramdef> 5712 <paramdef>u8 * <parameter>dst</parameter></paramdef> 5713 <paramdef>const u8 * <parameter>src</parameter></paramdef> 5714 </funcprototype></funcsynopsis> 5715</refsynopsisdiv> 5716<refsect1> 5717 <title>Arguments</title> 5718 <variablelist> 5719 <varlistentry> 5720 <term><parameter>tfm</parameter></term> 5721 <listitem> 5722 <para> 5723 cipher handle 5724 </para> 5725 </listitem> 5726 </varlistentry> 5727 <varlistentry> 5728 <term><parameter>dst</parameter></term> 5729 <listitem> 5730 <para> 5731 points to the buffer that will be filled with the plaintext 5732 </para> 5733 </listitem> 5734 </varlistentry> 5735 <varlistentry> 5736 <term><parameter>src</parameter></term> 5737 <listitem> 5738 <para> 5739 buffer holding the ciphertext to be decrypted 5740 </para> 5741 </listitem> 5742 </varlistentry> 5743 </variablelist> 5744</refsect1> 5745<refsect1> 5746<title>Description</title> 5747<para> 5748 Invoke the decryption operation of one block. The caller must ensure that 5749 the plaintext and ciphertext buffers are at least one block in size. 5750</para> 5751</refsect1> 5752</refentry> 5753 5754 </sect1> 5755 <sect1><title>Synchronous Message Digest API</title> 5756<para> 5757 </para><para> 5758 The synchronous message digest API is used with the ciphers of type 5759 CRYPTO_ALG_TYPE_HASH (listed as type <quote>hash</quote> in /proc/crypto) 5760</para> 5761 5762<refentry id="API-crypto-alloc-hash"> 5763<refentryinfo> 5764 <title>LINUX</title> 5765 <productname>Kernel Hackers Manual</productname> 5766 <date>July 2017</date> 5767</refentryinfo> 5768<refmeta> 5769 <refentrytitle><phrase>crypto_alloc_hash</phrase></refentrytitle> 5770 <manvolnum>9</manvolnum> 5771 <refmiscinfo class="version">4.1.27</refmiscinfo> 5772</refmeta> 5773<refnamediv> 5774 <refname>crypto_alloc_hash</refname> 5775 <refpurpose> 5776 allocate synchronous message digest handle 5777 </refpurpose> 5778</refnamediv> 5779<refsynopsisdiv> 5780 <title>Synopsis</title> 5781 <funcsynopsis><funcprototype> 5782 <funcdef>struct crypto_hash * <function>crypto_alloc_hash </function></funcdef> 5783 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 5784 <paramdef>u32 <parameter>type</parameter></paramdef> 5785 <paramdef>u32 <parameter>mask</parameter></paramdef> 5786 </funcprototype></funcsynopsis> 5787</refsynopsisdiv> 5788<refsect1> 5789 <title>Arguments</title> 5790 <variablelist> 5791 <varlistentry> 5792 <term><parameter>alg_name</parameter></term> 5793 <listitem> 5794 <para> 5795 is the cra_name / name or cra_driver_name / driver name of the 5796 message digest cipher 5797 </para> 5798 </listitem> 5799 </varlistentry> 5800 <varlistentry> 5801 <term><parameter>type</parameter></term> 5802 <listitem> 5803 <para> 5804 specifies the type of the cipher 5805 </para> 5806 </listitem> 5807 </varlistentry> 5808 <varlistentry> 5809 <term><parameter>mask</parameter></term> 5810 <listitem> 5811 <para> 5812 specifies the mask for the cipher 5813 </para> 5814 </listitem> 5815 </varlistentry> 5816 </variablelist> 5817</refsect1> 5818<refsect1> 5819<title>Description</title> 5820<para> 5821 Allocate a cipher handle for a message digest. The returned struct 5822 crypto_hash is the cipher handle that is required for any subsequent 5823 API invocation for that message digest. 5824</para> 5825</refsect1> 5826<refsect1> 5827<title>Return</title> 5828<para> 5829 allocated cipher handle in case of success; <function>IS_ERR</function> is true in case 5830 of an error, <function>PTR_ERR</function> returns the error code. 5831</para> 5832</refsect1> 5833</refentry> 5834 5835<refentry id="API-crypto-free-hash"> 5836<refentryinfo> 5837 <title>LINUX</title> 5838 <productname>Kernel Hackers Manual</productname> 5839 <date>July 2017</date> 5840</refentryinfo> 5841<refmeta> 5842 <refentrytitle><phrase>crypto_free_hash</phrase></refentrytitle> 5843 <manvolnum>9</manvolnum> 5844 <refmiscinfo class="version">4.1.27</refmiscinfo> 5845</refmeta> 5846<refnamediv> 5847 <refname>crypto_free_hash</refname> 5848 <refpurpose> 5849 zeroize and free message digest handle 5850 </refpurpose> 5851</refnamediv> 5852<refsynopsisdiv> 5853 <title>Synopsis</title> 5854 <funcsynopsis><funcprototype> 5855 <funcdef>void <function>crypto_free_hash </function></funcdef> 5856 <paramdef>struct crypto_hash * <parameter>tfm</parameter></paramdef> 5857 </funcprototype></funcsynopsis> 5858</refsynopsisdiv> 5859<refsect1> 5860 <title>Arguments</title> 5861 <variablelist> 5862 <varlistentry> 5863 <term><parameter>tfm</parameter></term> 5864 <listitem> 5865 <para> 5866 cipher handle to be freed 5867 </para> 5868 </listitem> 5869 </varlistentry> 5870 </variablelist> 5871</refsect1> 5872</refentry> 5873 5874<refentry id="API-crypto-has-hash"> 5875<refentryinfo> 5876 <title>LINUX</title> 5877 <productname>Kernel Hackers Manual</productname> 5878 <date>July 2017</date> 5879</refentryinfo> 5880<refmeta> 5881 <refentrytitle><phrase>crypto_has_hash</phrase></refentrytitle> 5882 <manvolnum>9</manvolnum> 5883 <refmiscinfo class="version">4.1.27</refmiscinfo> 5884</refmeta> 5885<refnamediv> 5886 <refname>crypto_has_hash</refname> 5887 <refpurpose> 5888 Search for the availability of a message digest 5889 </refpurpose> 5890</refnamediv> 5891<refsynopsisdiv> 5892 <title>Synopsis</title> 5893 <funcsynopsis><funcprototype> 5894 <funcdef>int <function>crypto_has_hash </function></funcdef> 5895 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 5896 <paramdef>u32 <parameter>type</parameter></paramdef> 5897 <paramdef>u32 <parameter>mask</parameter></paramdef> 5898 </funcprototype></funcsynopsis> 5899</refsynopsisdiv> 5900<refsect1> 5901 <title>Arguments</title> 5902 <variablelist> 5903 <varlistentry> 5904 <term><parameter>alg_name</parameter></term> 5905 <listitem> 5906 <para> 5907 is the cra_name / name or cra_driver_name / driver name of the 5908 message digest cipher 5909 </para> 5910 </listitem> 5911 </varlistentry> 5912 <varlistentry> 5913 <term><parameter>type</parameter></term> 5914 <listitem> 5915 <para> 5916 specifies the type of the cipher 5917 </para> 5918 </listitem> 5919 </varlistentry> 5920 <varlistentry> 5921 <term><parameter>mask</parameter></term> 5922 <listitem> 5923 <para> 5924 specifies the mask for the cipher 5925 </para> 5926 </listitem> 5927 </varlistentry> 5928 </variablelist> 5929</refsect1> 5930<refsect1> 5931<title>Return</title> 5932<para> 5933 true when the message digest cipher is known to the kernel crypto 5934 API; false otherwise 5935</para> 5936</refsect1> 5937</refentry> 5938 5939<refentry id="API-crypto-hash-blocksize"> 5940<refentryinfo> 5941 <title>LINUX</title> 5942 <productname>Kernel Hackers Manual</productname> 5943 <date>July 2017</date> 5944</refentryinfo> 5945<refmeta> 5946 <refentrytitle><phrase>crypto_hash_blocksize</phrase></refentrytitle> 5947 <manvolnum>9</manvolnum> 5948 <refmiscinfo class="version">4.1.27</refmiscinfo> 5949</refmeta> 5950<refnamediv> 5951 <refname>crypto_hash_blocksize</refname> 5952 <refpurpose> 5953 obtain block size for message digest 5954 </refpurpose> 5955</refnamediv> 5956<refsynopsisdiv> 5957 <title>Synopsis</title> 5958 <funcsynopsis><funcprototype> 5959 <funcdef>unsigned int <function>crypto_hash_blocksize </function></funcdef> 5960 <paramdef>struct crypto_hash * <parameter>tfm</parameter></paramdef> 5961 </funcprototype></funcsynopsis> 5962</refsynopsisdiv> 5963<refsect1> 5964 <title>Arguments</title> 5965 <variablelist> 5966 <varlistentry> 5967 <term><parameter>tfm</parameter></term> 5968 <listitem> 5969 <para> 5970 cipher handle 5971 </para> 5972 </listitem> 5973 </varlistentry> 5974 </variablelist> 5975</refsect1> 5976<refsect1> 5977<title>Description</title> 5978<para> 5979 The block size for the message digest cipher referenced with the cipher 5980 handle is returned. 5981</para> 5982</refsect1> 5983<refsect1> 5984<title>Return</title> 5985<para> 5986 block size of cipher 5987</para> 5988</refsect1> 5989</refentry> 5990 5991<refentry id="API-crypto-hash-digestsize"> 5992<refentryinfo> 5993 <title>LINUX</title> 5994 <productname>Kernel Hackers Manual</productname> 5995 <date>July 2017</date> 5996</refentryinfo> 5997<refmeta> 5998 <refentrytitle><phrase>crypto_hash_digestsize</phrase></refentrytitle> 5999 <manvolnum>9</manvolnum> 6000 <refmiscinfo class="version">4.1.27</refmiscinfo> 6001</refmeta> 6002<refnamediv> 6003 <refname>crypto_hash_digestsize</refname> 6004 <refpurpose> 6005 obtain message digest size 6006 </refpurpose> 6007</refnamediv> 6008<refsynopsisdiv> 6009 <title>Synopsis</title> 6010 <funcsynopsis><funcprototype> 6011 <funcdef>unsigned int <function>crypto_hash_digestsize </function></funcdef> 6012 <paramdef>struct crypto_hash * <parameter>tfm</parameter></paramdef> 6013 </funcprototype></funcsynopsis> 6014</refsynopsisdiv> 6015<refsect1> 6016 <title>Arguments</title> 6017 <variablelist> 6018 <varlistentry> 6019 <term><parameter>tfm</parameter></term> 6020 <listitem> 6021 <para> 6022 cipher handle 6023 </para> 6024 </listitem> 6025 </varlistentry> 6026 </variablelist> 6027</refsect1> 6028<refsect1> 6029<title>Description</title> 6030<para> 6031 The size for the message digest created by the message digest cipher 6032 referenced with the cipher handle is returned. 6033</para> 6034</refsect1> 6035<refsect1> 6036<title>Return</title> 6037<para> 6038 message digest size 6039</para> 6040</refsect1> 6041</refentry> 6042 6043<refentry id="API-crypto-hash-init"> 6044<refentryinfo> 6045 <title>LINUX</title> 6046 <productname>Kernel Hackers Manual</productname> 6047 <date>July 2017</date> 6048</refentryinfo> 6049<refmeta> 6050 <refentrytitle><phrase>crypto_hash_init</phrase></refentrytitle> 6051 <manvolnum>9</manvolnum> 6052 <refmiscinfo class="version">4.1.27</refmiscinfo> 6053</refmeta> 6054<refnamediv> 6055 <refname>crypto_hash_init</refname> 6056 <refpurpose> 6057 (re)initialize message digest handle 6058 </refpurpose> 6059</refnamediv> 6060<refsynopsisdiv> 6061 <title>Synopsis</title> 6062 <funcsynopsis><funcprototype> 6063 <funcdef>int <function>crypto_hash_init </function></funcdef> 6064 <paramdef>struct hash_desc * <parameter>desc</parameter></paramdef> 6065 </funcprototype></funcsynopsis> 6066</refsynopsisdiv> 6067<refsect1> 6068 <title>Arguments</title> 6069 <variablelist> 6070 <varlistentry> 6071 <term><parameter>desc</parameter></term> 6072 <listitem> 6073 <para> 6074 cipher request handle that to be filled by caller -- 6075 desc.tfm is filled with the hash cipher handle; 6076 desc.flags is filled with either CRYPTO_TFM_REQ_MAY_SLEEP or 0. 6077 </para> 6078 </listitem> 6079 </varlistentry> 6080 </variablelist> 6081</refsect1> 6082<refsect1> 6083<title>Description</title> 6084<para> 6085 The call (re-)initializes the message digest referenced by the hash cipher 6086 request handle. Any potentially existing state created by previous 6087 operations is discarded. 6088</para> 6089</refsect1> 6090<refsect1> 6091<title>Return</title> 6092<para> 6093 0 if the message digest initialization was successful; < 0 if an 6094 error occurred 6095</para> 6096</refsect1> 6097</refentry> 6098 6099<refentry id="API-crypto-hash-update"> 6100<refentryinfo> 6101 <title>LINUX</title> 6102 <productname>Kernel Hackers Manual</productname> 6103 <date>July 2017</date> 6104</refentryinfo> 6105<refmeta> 6106 <refentrytitle><phrase>crypto_hash_update</phrase></refentrytitle> 6107 <manvolnum>9</manvolnum> 6108 <refmiscinfo class="version">4.1.27</refmiscinfo> 6109</refmeta> 6110<refnamediv> 6111 <refname>crypto_hash_update</refname> 6112 <refpurpose> 6113 add data to message digest for processing 6114 </refpurpose> 6115</refnamediv> 6116<refsynopsisdiv> 6117 <title>Synopsis</title> 6118 <funcsynopsis><funcprototype> 6119 <funcdef>int <function>crypto_hash_update </function></funcdef> 6120 <paramdef>struct hash_desc * <parameter>desc</parameter></paramdef> 6121 <paramdef>struct scatterlist * <parameter>sg</parameter></paramdef> 6122 <paramdef>unsigned int <parameter>nbytes</parameter></paramdef> 6123 </funcprototype></funcsynopsis> 6124</refsynopsisdiv> 6125<refsect1> 6126 <title>Arguments</title> 6127 <variablelist> 6128 <varlistentry> 6129 <term><parameter>desc</parameter></term> 6130 <listitem> 6131 <para> 6132 cipher request handle 6133 </para> 6134 </listitem> 6135 </varlistentry> 6136 <varlistentry> 6137 <term><parameter>sg</parameter></term> 6138 <listitem> 6139 <para> 6140 scatter / gather list pointing to the data to be added to the message 6141 digest 6142 </para> 6143 </listitem> 6144 </varlistentry> 6145 <varlistentry> 6146 <term><parameter>nbytes</parameter></term> 6147 <listitem> 6148 <para> 6149 number of bytes to be processed from <parameter>sg</parameter> 6150 </para> 6151 </listitem> 6152 </varlistentry> 6153 </variablelist> 6154</refsect1> 6155<refsect1> 6156<title>Description</title> 6157<para> 6158 Updates the message digest state of the cipher handle pointed to by the 6159 hash cipher request handle with the input data pointed to by the 6160 scatter/gather list. 6161</para> 6162</refsect1> 6163<refsect1> 6164<title>Return</title> 6165<para> 6166 0 if the message digest update was successful; < 0 if an error 6167 occurred 6168</para> 6169</refsect1> 6170</refentry> 6171 6172<refentry id="API-crypto-hash-final"> 6173<refentryinfo> 6174 <title>LINUX</title> 6175 <productname>Kernel Hackers Manual</productname> 6176 <date>July 2017</date> 6177</refentryinfo> 6178<refmeta> 6179 <refentrytitle><phrase>crypto_hash_final</phrase></refentrytitle> 6180 <manvolnum>9</manvolnum> 6181 <refmiscinfo class="version">4.1.27</refmiscinfo> 6182</refmeta> 6183<refnamediv> 6184 <refname>crypto_hash_final</refname> 6185 <refpurpose> 6186 calculate message digest 6187 </refpurpose> 6188</refnamediv> 6189<refsynopsisdiv> 6190 <title>Synopsis</title> 6191 <funcsynopsis><funcprototype> 6192 <funcdef>int <function>crypto_hash_final </function></funcdef> 6193 <paramdef>struct hash_desc * <parameter>desc</parameter></paramdef> 6194 <paramdef>u8 * <parameter>out</parameter></paramdef> 6195 </funcprototype></funcsynopsis> 6196</refsynopsisdiv> 6197<refsect1> 6198 <title>Arguments</title> 6199 <variablelist> 6200 <varlistentry> 6201 <term><parameter>desc</parameter></term> 6202 <listitem> 6203 <para> 6204 cipher request handle 6205 </para> 6206 </listitem> 6207 </varlistentry> 6208 <varlistentry> 6209 <term><parameter>out</parameter></term> 6210 <listitem> 6211 <para> 6212 message digest output buffer -- The caller must ensure that the out 6213 buffer has a sufficient size (e.g. by using the crypto_hash_digestsize 6214 function). 6215 </para> 6216 </listitem> 6217 </varlistentry> 6218 </variablelist> 6219</refsect1> 6220<refsect1> 6221<title>Description</title> 6222<para> 6223 Finalize the message digest operation and create the message digest 6224 based on all data added to the cipher handle. The message digest is placed 6225 into the output buffer. 6226</para> 6227</refsect1> 6228<refsect1> 6229<title>Return</title> 6230<para> 6231 0 if the message digest creation was successful; < 0 if an error 6232 occurred 6233</para> 6234</refsect1> 6235</refentry> 6236 6237<refentry id="API-crypto-hash-digest"> 6238<refentryinfo> 6239 <title>LINUX</title> 6240 <productname>Kernel Hackers Manual</productname> 6241 <date>July 2017</date> 6242</refentryinfo> 6243<refmeta> 6244 <refentrytitle><phrase>crypto_hash_digest</phrase></refentrytitle> 6245 <manvolnum>9</manvolnum> 6246 <refmiscinfo class="version">4.1.27</refmiscinfo> 6247</refmeta> 6248<refnamediv> 6249 <refname>crypto_hash_digest</refname> 6250 <refpurpose> 6251 calculate message digest for a buffer 6252 </refpurpose> 6253</refnamediv> 6254<refsynopsisdiv> 6255 <title>Synopsis</title> 6256 <funcsynopsis><funcprototype> 6257 <funcdef>int <function>crypto_hash_digest </function></funcdef> 6258 <paramdef>struct hash_desc * <parameter>desc</parameter></paramdef> 6259 <paramdef>struct scatterlist * <parameter>sg</parameter></paramdef> 6260 <paramdef>unsigned int <parameter>nbytes</parameter></paramdef> 6261 <paramdef>u8 * <parameter>out</parameter></paramdef> 6262 </funcprototype></funcsynopsis> 6263</refsynopsisdiv> 6264<refsect1> 6265 <title>Arguments</title> 6266 <variablelist> 6267 <varlistentry> 6268 <term><parameter>desc</parameter></term> 6269 <listitem> 6270 <para> 6271 see <function>crypto_hash_final</function> 6272 </para> 6273 </listitem> 6274 </varlistentry> 6275 <varlistentry> 6276 <term><parameter>sg</parameter></term> 6277 <listitem> 6278 <para> 6279 see <function>crypto_hash_update</function> 6280 </para> 6281 </listitem> 6282 </varlistentry> 6283 <varlistentry> 6284 <term><parameter>nbytes</parameter></term> 6285 <listitem> 6286 <para> 6287 see <function>crypto_hash_update</function> 6288 </para> 6289 </listitem> 6290 </varlistentry> 6291 <varlistentry> 6292 <term><parameter>out</parameter></term> 6293 <listitem> 6294 <para> 6295 see <function>crypto_hash_final</function> 6296 </para> 6297 </listitem> 6298 </varlistentry> 6299 </variablelist> 6300</refsect1> 6301<refsect1> 6302<title>Description</title> 6303<para> 6304 This function is a <quote>short-hand</quote> for the function calls of crypto_hash_init, 6305 crypto_hash_update and crypto_hash_final. The parameters have the same 6306 meaning as discussed for those separate three functions. 6307</para> 6308</refsect1> 6309<refsect1> 6310<title>Return</title> 6311<para> 6312 0 if the message digest creation was successful; < 0 if an error 6313 occurred 6314</para> 6315</refsect1> 6316</refentry> 6317 6318<refentry id="API-crypto-hash-setkey"> 6319<refentryinfo> 6320 <title>LINUX</title> 6321 <productname>Kernel Hackers Manual</productname> 6322 <date>July 2017</date> 6323</refentryinfo> 6324<refmeta> 6325 <refentrytitle><phrase>crypto_hash_setkey</phrase></refentrytitle> 6326 <manvolnum>9</manvolnum> 6327 <refmiscinfo class="version">4.1.27</refmiscinfo> 6328</refmeta> 6329<refnamediv> 6330 <refname>crypto_hash_setkey</refname> 6331 <refpurpose> 6332 set key for message digest 6333 </refpurpose> 6334</refnamediv> 6335<refsynopsisdiv> 6336 <title>Synopsis</title> 6337 <funcsynopsis><funcprototype> 6338 <funcdef>int <function>crypto_hash_setkey </function></funcdef> 6339 <paramdef>struct crypto_hash * <parameter>hash</parameter></paramdef> 6340 <paramdef>const u8 * <parameter>key</parameter></paramdef> 6341 <paramdef>unsigned int <parameter>keylen</parameter></paramdef> 6342 </funcprototype></funcsynopsis> 6343</refsynopsisdiv> 6344<refsect1> 6345 <title>Arguments</title> 6346 <variablelist> 6347 <varlistentry> 6348 <term><parameter>hash</parameter></term> 6349 <listitem> 6350 <para> 6351 cipher handle 6352 </para> 6353 </listitem> 6354 </varlistentry> 6355 <varlistentry> 6356 <term><parameter>key</parameter></term> 6357 <listitem> 6358 <para> 6359 buffer holding the key 6360 </para> 6361 </listitem> 6362 </varlistentry> 6363 <varlistentry> 6364 <term><parameter>keylen</parameter></term> 6365 <listitem> 6366 <para> 6367 length of the key in bytes 6368 </para> 6369 </listitem> 6370 </varlistentry> 6371 </variablelist> 6372</refsect1> 6373<refsect1> 6374<title>Description</title> 6375<para> 6376 The caller provided key is set for the message digest cipher. The cipher 6377 handle must point to a keyed hash in order for this function to succeed. 6378</para> 6379</refsect1> 6380<refsect1> 6381<title>Return</title> 6382<para> 6383 0 if the setting of the key was successful; < 0 if an error occurred 6384</para> 6385</refsect1> 6386</refentry> 6387 6388 </sect1> 6389 <sect1><title>Message Digest Algorithm Definitions</title> 6390<para> 6391 </para><para> 6392 These data structures define modular message digest algorithm 6393 implementations, managed via <function>crypto_register_ahash</function>, 6394 <function>crypto_register_shash</function>, <function>crypto_unregister_ahash</function> and 6395 <function>crypto_unregister_shash</function>. 6396</para> 6397 6398<refentry id="API-struct-hash-alg-common"> 6399<refentryinfo> 6400 <title>LINUX</title> 6401 <productname>Kernel Hackers Manual</productname> 6402 <date>July 2017</date> 6403</refentryinfo> 6404<refmeta> 6405 <refentrytitle><phrase>struct hash_alg_common</phrase></refentrytitle> 6406 <manvolnum>9</manvolnum> 6407 <refmiscinfo class="version">4.1.27</refmiscinfo> 6408</refmeta> 6409<refnamediv> 6410 <refname>struct hash_alg_common</refname> 6411 <refpurpose> 6412 define properties of message digest 6413 </refpurpose> 6414</refnamediv> 6415<refsynopsisdiv> 6416 <title>Synopsis</title> 6417 <programlisting> 6418struct hash_alg_common { 6419 unsigned int digestsize; 6420 unsigned int statesize; 6421 struct crypto_alg base; 6422}; </programlisting> 6423</refsynopsisdiv> 6424 <refsect1> 6425 <title>Members</title> 6426 <variablelist> 6427 <varlistentry> <term>digestsize</term> 6428 <listitem><para> 6429Size of the result of the transformation. A buffer of this size 6430must be available to the <parameter>final</parameter> and <parameter>finup</parameter> calls, so they can 6431store the resulting hash into it. For various predefined sizes, 6432search include/crypto/ using 6433git grep _DIGEST_SIZE include/crypto. 6434 </para></listitem> 6435 </varlistentry> 6436 <varlistentry> <term>statesize</term> 6437 <listitem><para> 6438Size of the block for partial state of the transformation. A 6439buffer of this size must be passed to the <parameter>export</parameter> function as it 6440will save the partial state of the transformation into it. On the 6441other side, the <parameter>import</parameter> function will load the state from a 6442buffer of this size as well. 6443 </para></listitem> 6444 </varlistentry> 6445 <varlistentry> <term>base</term> 6446 <listitem><para> 6447Start of data structure of cipher algorithm. The common data 6448structure of crypto_alg contains information common to all ciphers. 6449The hash_alg_common data structure now adds the hash-specific 6450information. 6451 </para></listitem> 6452 </varlistentry> 6453 </variablelist> 6454 </refsect1> 6455</refentry> 6456 6457<refentry id="API-struct-ahash-alg"> 6458<refentryinfo> 6459 <title>LINUX</title> 6460 <productname>Kernel Hackers Manual</productname> 6461 <date>July 2017</date> 6462</refentryinfo> 6463<refmeta> 6464 <refentrytitle><phrase>struct ahash_alg</phrase></refentrytitle> 6465 <manvolnum>9</manvolnum> 6466 <refmiscinfo class="version">4.1.27</refmiscinfo> 6467</refmeta> 6468<refnamediv> 6469 <refname>struct ahash_alg</refname> 6470 <refpurpose> 6471 asynchronous message digest definition 6472 </refpurpose> 6473</refnamediv> 6474<refsynopsisdiv> 6475 <title>Synopsis</title> 6476 <programlisting> 6477struct ahash_alg { 6478 int (* init) (struct ahash_request *req); 6479 int (* update) (struct ahash_request *req); 6480 int (* final) (struct ahash_request *req); 6481 int (* finup) (struct ahash_request *req); 6482 int (* digest) (struct ahash_request *req); 6483 int (* export) (struct ahash_request *req, void *out); 6484 int (* import) (struct ahash_request *req, const void *in); 6485 int (* setkey) (struct crypto_ahash *tfm, const u8 *key,unsigned int keylen); 6486 struct hash_alg_common halg; 6487}; </programlisting> 6488</refsynopsisdiv> 6489 <refsect1> 6490 <title>Members</title> 6491 <variablelist> 6492 <varlistentry> <term>init</term> 6493 <listitem><para> 6494Initialize the transformation context. Intended only to initialize the 6495state of the HASH transformation at the begining. This shall fill in 6496the internal structures used during the entire duration of the whole 6497transformation. No data processing happens at this point. 6498 </para></listitem> 6499 </varlistentry> 6500 <varlistentry> <term>update</term> 6501 <listitem><para> 6502Push a chunk of data into the driver for transformation. This 6503function actually pushes blocks of data from upper layers into the 6504driver, which then passes those to the hardware as seen fit. This 6505function must not finalize the HASH transformation by calculating the 6506final message digest as this only adds more data into the 6507transformation. This function shall not modify the transformation 6508context, as this function may be called in parallel with the same 6509transformation object. Data processing can happen synchronously 6510[SHASH] or asynchronously [AHASH] at this point. 6511 </para></listitem> 6512 </varlistentry> 6513 <varlistentry> <term>final</term> 6514 <listitem><para> 6515Retrieve result from the driver. This function finalizes the 6516transformation and retrieves the resulting hash from the driver and 6517pushes it back to upper layers. No data processing happens at this 6518point. 6519 </para></listitem> 6520 </varlistentry> 6521 <varlistentry> <term>finup</term> 6522 <listitem><para> 6523Combination of <parameter>update</parameter> and <parameter>final</parameter>. This function is effectively a 6524combination of <parameter>update</parameter> and <parameter>final</parameter> calls issued in sequence. As some 6525hardware cannot do <parameter>update</parameter> and <parameter>final</parameter> separately, this callback was 6526added to allow such hardware to be used at least by IPsec. Data 6527processing can happen synchronously [SHASH] or asynchronously [AHASH] 6528at this point. 6529 </para></listitem> 6530 </varlistentry> 6531 <varlistentry> <term>digest</term> 6532 <listitem><para> 6533Combination of <parameter>init</parameter> and <parameter>update</parameter> and <parameter>final</parameter>. This function 6534effectively behaves as the entire chain of operations, <parameter>init</parameter>, 6535<parameter>update</parameter> and <parameter>final</parameter> issued in sequence. Just like <parameter>finup</parameter>, this was 6536added for hardware which cannot do even the <parameter>finup</parameter>, but can only do 6537the whole transformation in one run. Data processing can happen 6538synchronously [SHASH] or asynchronously [AHASH] at this point. 6539 </para></listitem> 6540 </varlistentry> 6541 <varlistentry> <term>export</term> 6542 <listitem><para> 6543Export partial state of the transformation. This function dumps the 6544entire state of the ongoing transformation into a provided block of 6545data so it can be <parameter>import</parameter> 'ed back later on. This is useful in case 6546you want to save partial result of the transformation after 6547processing certain amount of data and reload this partial result 6548multiple times later on for multiple re-use. No data processing 6549happens at this point. 6550 </para></listitem> 6551 </varlistentry> 6552 <varlistentry> <term>import</term> 6553 <listitem><para> 6554Import partial state of the transformation. This function loads the 6555entire state of the ongoing transformation from a provided block of 6556data so the transformation can continue from this point onward. No 6557data processing happens at this point. 6558 </para></listitem> 6559 </varlistentry> 6560 <varlistentry> <term>setkey</term> 6561 <listitem><para> 6562Set optional key used by the hashing algorithm. Intended to push 6563optional key used by the hashing algorithm from upper layers into 6564the driver. This function can store the key in the transformation 6565context or can outright program it into the hardware. In the former 6566case, one must be careful to program the key into the hardware at 6567appropriate time and one must be careful that .<function>setkey</function> can be 6568called multiple times during the existence of the transformation 6569object. Not all hashing algorithms do implement this function as it 6570is only needed for keyed message digests. SHAx/MDx/CRCx do NOT 6571implement this function. HMAC(MDx)/HMAC(SHAx)/CMAC(AES) do implement 6572this function. This function must be called before any other of the 6573<parameter>init</parameter>, <parameter>update</parameter>, <parameter>final</parameter>, <parameter>finup</parameter>, <parameter>digest</parameter> is called. No data 6574processing happens at this point. 6575 </para></listitem> 6576 </varlistentry> 6577 <varlistentry> <term>halg</term> 6578 <listitem><para> 6579see struct hash_alg_common 6580 </para></listitem> 6581 </varlistentry> 6582 </variablelist> 6583 </refsect1> 6584</refentry> 6585 6586<refentry id="API-struct-shash-alg"> 6587<refentryinfo> 6588 <title>LINUX</title> 6589 <productname>Kernel Hackers Manual</productname> 6590 <date>July 2017</date> 6591</refentryinfo> 6592<refmeta> 6593 <refentrytitle><phrase>struct shash_alg</phrase></refentrytitle> 6594 <manvolnum>9</manvolnum> 6595 <refmiscinfo class="version">4.1.27</refmiscinfo> 6596</refmeta> 6597<refnamediv> 6598 <refname>struct shash_alg</refname> 6599 <refpurpose> 6600 synchronous message digest definition 6601 </refpurpose> 6602</refnamediv> 6603<refsynopsisdiv> 6604 <title>Synopsis</title> 6605 <programlisting> 6606struct shash_alg { 6607 int (* init) (struct shash_desc *desc); 6608 int (* update) (struct shash_desc *desc, const u8 *data,unsigned int len); 6609 int (* final) (struct shash_desc *desc, u8 *out); 6610 int (* finup) (struct shash_desc *desc, const u8 *data,unsigned int len, u8 *out); 6611 int (* digest) (struct shash_desc *desc, const u8 *data,unsigned int len, u8 *out); 6612 int (* export) (struct shash_desc *desc, void *out); 6613 int (* import) (struct shash_desc *desc, const void *in); 6614 int (* setkey) (struct crypto_shash *tfm, const u8 *key,unsigned int keylen); 6615 unsigned int descsize; 6616 unsigned int statesize; 6617 struct crypto_alg base; 6618}; </programlisting> 6619</refsynopsisdiv> 6620 <refsect1> 6621 <title>Members</title> 6622 <variablelist> 6623 <varlistentry> <term>init</term> 6624 <listitem><para> 6625see struct ahash_alg 6626 </para></listitem> 6627 </varlistentry> 6628 <varlistentry> <term>update</term> 6629 <listitem><para> 6630see struct ahash_alg 6631 </para></listitem> 6632 </varlistentry> 6633 <varlistentry> <term>final</term> 6634 <listitem><para> 6635see struct ahash_alg 6636 </para></listitem> 6637 </varlistentry> 6638 <varlistentry> <term>finup</term> 6639 <listitem><para> 6640see struct ahash_alg 6641 </para></listitem> 6642 </varlistentry> 6643 <varlistentry> <term>digest</term> 6644 <listitem><para> 6645see struct ahash_alg 6646 </para></listitem> 6647 </varlistentry> 6648 <varlistentry> <term>export</term> 6649 <listitem><para> 6650see struct ahash_alg 6651 </para></listitem> 6652 </varlistentry> 6653 <varlistentry> <term>import</term> 6654 <listitem><para> 6655see struct ahash_alg 6656 </para></listitem> 6657 </varlistentry> 6658 <varlistentry> <term>setkey</term> 6659 <listitem><para> 6660see struct ahash_alg 6661 </para></listitem> 6662 </varlistentry> 6663 <varlistentry> <term>descsize</term> 6664 <listitem><para> 6665Size of the operational state for the message digest. This state 6666size is the memory size that needs to be allocated for 6667shash_desc.__ctx 6668 </para></listitem> 6669 </varlistentry> 6670 <varlistentry> <term>statesize</term> 6671 <listitem><para> 6672see struct ahash_alg 6673 </para></listitem> 6674 </varlistentry> 6675 <varlistentry> <term>base</term> 6676 <listitem><para> 6677internally used 6678 </para></listitem> 6679 </varlistentry> 6680 </variablelist> 6681 </refsect1> 6682</refentry> 6683 6684 </sect1> 6685 <sect1><title>Asynchronous Message Digest API</title> 6686<para> 6687 </para><para> 6688 The asynchronous message digest API is used with the ciphers of type 6689 CRYPTO_ALG_TYPE_AHASH (listed as type <quote>ahash</quote> in /proc/crypto) 6690 </para><para> 6691 The asynchronous cipher operation discussion provided for the 6692 CRYPTO_ALG_TYPE_ABLKCIPHER API applies here as well. 6693</para> 6694 6695<refentry id="API-crypto-alloc-ahash"> 6696<refentryinfo> 6697 <title>LINUX</title> 6698 <productname>Kernel Hackers Manual</productname> 6699 <date>July 2017</date> 6700</refentryinfo> 6701<refmeta> 6702 <refentrytitle><phrase>crypto_alloc_ahash</phrase></refentrytitle> 6703 <manvolnum>9</manvolnum> 6704 <refmiscinfo class="version">4.1.27</refmiscinfo> 6705</refmeta> 6706<refnamediv> 6707 <refname>crypto_alloc_ahash</refname> 6708 <refpurpose> 6709 allocate ahash cipher handle 6710 </refpurpose> 6711</refnamediv> 6712<refsynopsisdiv> 6713 <title>Synopsis</title> 6714 <funcsynopsis><funcprototype> 6715 <funcdef>struct crypto_ahash * <function>crypto_alloc_ahash </function></funcdef> 6716 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 6717 <paramdef>u32 <parameter>type</parameter></paramdef> 6718 <paramdef>u32 <parameter>mask</parameter></paramdef> 6719 </funcprototype></funcsynopsis> 6720</refsynopsisdiv> 6721<refsect1> 6722 <title>Arguments</title> 6723 <variablelist> 6724 <varlistentry> 6725 <term><parameter>alg_name</parameter></term> 6726 <listitem> 6727 <para> 6728 is the cra_name / name or cra_driver_name / driver name of the 6729 ahash cipher 6730 </para> 6731 </listitem> 6732 </varlistentry> 6733 <varlistentry> 6734 <term><parameter>type</parameter></term> 6735 <listitem> 6736 <para> 6737 specifies the type of the cipher 6738 </para> 6739 </listitem> 6740 </varlistentry> 6741 <varlistentry> 6742 <term><parameter>mask</parameter></term> 6743 <listitem> 6744 <para> 6745 specifies the mask for the cipher 6746 </para> 6747 </listitem> 6748 </varlistentry> 6749 </variablelist> 6750</refsect1> 6751<refsect1> 6752<title>Description</title> 6753<para> 6754 Allocate a cipher handle for an ahash. The returned struct 6755 crypto_ahash is the cipher handle that is required for any subsequent 6756 API invocation for that ahash. 6757</para> 6758</refsect1> 6759<refsect1> 6760<title>Return</title> 6761<para> 6762 allocated cipher handle in case of success; <function>IS_ERR</function> is true in case 6763 of an error, <function>PTR_ERR</function> returns the error code. 6764</para> 6765</refsect1> 6766</refentry> 6767 6768<refentry id="API-crypto-free-ahash"> 6769<refentryinfo> 6770 <title>LINUX</title> 6771 <productname>Kernel Hackers Manual</productname> 6772 <date>July 2017</date> 6773</refentryinfo> 6774<refmeta> 6775 <refentrytitle><phrase>crypto_free_ahash</phrase></refentrytitle> 6776 <manvolnum>9</manvolnum> 6777 <refmiscinfo class="version">4.1.27</refmiscinfo> 6778</refmeta> 6779<refnamediv> 6780 <refname>crypto_free_ahash</refname> 6781 <refpurpose> 6782 zeroize and free the ahash handle 6783 </refpurpose> 6784</refnamediv> 6785<refsynopsisdiv> 6786 <title>Synopsis</title> 6787 <funcsynopsis><funcprototype> 6788 <funcdef>void <function>crypto_free_ahash </function></funcdef> 6789 <paramdef>struct crypto_ahash * <parameter>tfm</parameter></paramdef> 6790 </funcprototype></funcsynopsis> 6791</refsynopsisdiv> 6792<refsect1> 6793 <title>Arguments</title> 6794 <variablelist> 6795 <varlistentry> 6796 <term><parameter>tfm</parameter></term> 6797 <listitem> 6798 <para> 6799 cipher handle to be freed 6800 </para> 6801 </listitem> 6802 </varlistentry> 6803 </variablelist> 6804</refsect1> 6805</refentry> 6806 6807<refentry id="API-crypto-ahash-init"> 6808<refentryinfo> 6809 <title>LINUX</title> 6810 <productname>Kernel Hackers Manual</productname> 6811 <date>July 2017</date> 6812</refentryinfo> 6813<refmeta> 6814 <refentrytitle><phrase>crypto_ahash_init</phrase></refentrytitle> 6815 <manvolnum>9</manvolnum> 6816 <refmiscinfo class="version">4.1.27</refmiscinfo> 6817</refmeta> 6818<refnamediv> 6819 <refname>crypto_ahash_init</refname> 6820 <refpurpose> 6821 (re)initialize message digest handle 6822 </refpurpose> 6823</refnamediv> 6824<refsynopsisdiv> 6825 <title>Synopsis</title> 6826 <funcsynopsis><funcprototype> 6827 <funcdef>int <function>crypto_ahash_init </function></funcdef> 6828 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 6829 </funcprototype></funcsynopsis> 6830</refsynopsisdiv> 6831<refsect1> 6832 <title>Arguments</title> 6833 <variablelist> 6834 <varlistentry> 6835 <term><parameter>req</parameter></term> 6836 <listitem> 6837 <para> 6838 ahash_request handle that already is initialized with all necessary 6839 data using the ahash_request_* API functions 6840 </para> 6841 </listitem> 6842 </varlistentry> 6843 </variablelist> 6844</refsect1> 6845<refsect1> 6846<title>Description</title> 6847<para> 6848 The call (re-)initializes the message digest referenced by the ahash_request 6849 handle. Any potentially existing state created by previous operations is 6850 discarded. 6851</para> 6852</refsect1> 6853<refsect1> 6854<title>Return</title> 6855<para> 6856 0 if the message digest initialization was successful; < 0 if an 6857 error occurred 6858</para> 6859</refsect1> 6860</refentry> 6861 6862<refentry id="API-crypto-ahash-digestsize"> 6863<refentryinfo> 6864 <title>LINUX</title> 6865 <productname>Kernel Hackers Manual</productname> 6866 <date>July 2017</date> 6867</refentryinfo> 6868<refmeta> 6869 <refentrytitle><phrase>crypto_ahash_digestsize</phrase></refentrytitle> 6870 <manvolnum>9</manvolnum> 6871 <refmiscinfo class="version">4.1.27</refmiscinfo> 6872</refmeta> 6873<refnamediv> 6874 <refname>crypto_ahash_digestsize</refname> 6875 <refpurpose> 6876 obtain message digest size 6877 </refpurpose> 6878</refnamediv> 6879<refsynopsisdiv> 6880 <title>Synopsis</title> 6881 <funcsynopsis><funcprototype> 6882 <funcdef>unsigned int <function>crypto_ahash_digestsize </function></funcdef> 6883 <paramdef>struct crypto_ahash * <parameter>tfm</parameter></paramdef> 6884 </funcprototype></funcsynopsis> 6885</refsynopsisdiv> 6886<refsect1> 6887 <title>Arguments</title> 6888 <variablelist> 6889 <varlistentry> 6890 <term><parameter>tfm</parameter></term> 6891 <listitem> 6892 <para> 6893 cipher handle 6894 </para> 6895 </listitem> 6896 </varlistentry> 6897 </variablelist> 6898</refsect1> 6899<refsect1> 6900<title>Description</title> 6901<para> 6902 The size for the message digest created by the message digest cipher 6903 referenced with the cipher handle is returned. 6904</para> 6905</refsect1> 6906<refsect1> 6907<title>Return</title> 6908<para> 6909 message digest size of cipher 6910</para> 6911</refsect1> 6912</refentry> 6913 6914<refentry id="API-crypto-ahash-reqtfm"> 6915<refentryinfo> 6916 <title>LINUX</title> 6917 <productname>Kernel Hackers Manual</productname> 6918 <date>July 2017</date> 6919</refentryinfo> 6920<refmeta> 6921 <refentrytitle><phrase>crypto_ahash_reqtfm</phrase></refentrytitle> 6922 <manvolnum>9</manvolnum> 6923 <refmiscinfo class="version">4.1.27</refmiscinfo> 6924</refmeta> 6925<refnamediv> 6926 <refname>crypto_ahash_reqtfm</refname> 6927 <refpurpose> 6928 obtain cipher handle from request 6929 </refpurpose> 6930</refnamediv> 6931<refsynopsisdiv> 6932 <title>Synopsis</title> 6933 <funcsynopsis><funcprototype> 6934 <funcdef>struct crypto_ahash * <function>crypto_ahash_reqtfm </function></funcdef> 6935 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 6936 </funcprototype></funcsynopsis> 6937</refsynopsisdiv> 6938<refsect1> 6939 <title>Arguments</title> 6940 <variablelist> 6941 <varlistentry> 6942 <term><parameter>req</parameter></term> 6943 <listitem> 6944 <para> 6945 asynchronous request handle that contains the reference to the ahash 6946 cipher handle 6947 </para> 6948 </listitem> 6949 </varlistentry> 6950 </variablelist> 6951</refsect1> 6952<refsect1> 6953<title>Description</title> 6954<para> 6955 Return the ahash cipher handle that is registered with the asynchronous 6956 request handle ahash_request. 6957</para> 6958</refsect1> 6959<refsect1> 6960<title>Return</title> 6961<para> 6962 ahash cipher handle 6963</para> 6964</refsect1> 6965</refentry> 6966 6967<refentry id="API-crypto-ahash-reqsize"> 6968<refentryinfo> 6969 <title>LINUX</title> 6970 <productname>Kernel Hackers Manual</productname> 6971 <date>July 2017</date> 6972</refentryinfo> 6973<refmeta> 6974 <refentrytitle><phrase>crypto_ahash_reqsize</phrase></refentrytitle> 6975 <manvolnum>9</manvolnum> 6976 <refmiscinfo class="version">4.1.27</refmiscinfo> 6977</refmeta> 6978<refnamediv> 6979 <refname>crypto_ahash_reqsize</refname> 6980 <refpurpose> 6981 obtain size of the request data structure 6982 </refpurpose> 6983</refnamediv> 6984<refsynopsisdiv> 6985 <title>Synopsis</title> 6986 <funcsynopsis><funcprototype> 6987 <funcdef>unsigned int <function>crypto_ahash_reqsize </function></funcdef> 6988 <paramdef>struct crypto_ahash * <parameter>tfm</parameter></paramdef> 6989 </funcprototype></funcsynopsis> 6990</refsynopsisdiv> 6991<refsect1> 6992 <title>Arguments</title> 6993 <variablelist> 6994 <varlistentry> 6995 <term><parameter>tfm</parameter></term> 6996 <listitem> 6997 <para> 6998 cipher handle 6999 </para> 7000 </listitem> 7001 </varlistentry> 7002 </variablelist> 7003</refsect1> 7004<refsect1> 7005<title>Description</title> 7006<para> 7007 Return the size of the ahash state size. With the crypto_ahash_export 7008 function, the caller can export the state into a buffer whose size is 7009 defined with this function. 7010</para> 7011</refsect1> 7012<refsect1> 7013<title>Return</title> 7014<para> 7015 size of the ahash state 7016</para> 7017</refsect1> 7018</refentry> 7019 7020<refentry id="API-crypto-ahash-setkey"> 7021<refentryinfo> 7022 <title>LINUX</title> 7023 <productname>Kernel Hackers Manual</productname> 7024 <date>July 2017</date> 7025</refentryinfo> 7026<refmeta> 7027 <refentrytitle><phrase>crypto_ahash_setkey</phrase></refentrytitle> 7028 <manvolnum>9</manvolnum> 7029 <refmiscinfo class="version">4.1.27</refmiscinfo> 7030</refmeta> 7031<refnamediv> 7032 <refname>crypto_ahash_setkey</refname> 7033 <refpurpose> 7034 set key for cipher handle 7035 </refpurpose> 7036</refnamediv> 7037<refsynopsisdiv> 7038 <title>Synopsis</title> 7039 <funcsynopsis><funcprototype> 7040 <funcdef>int <function>crypto_ahash_setkey </function></funcdef> 7041 <paramdef>struct crypto_ahash * <parameter>tfm</parameter></paramdef> 7042 <paramdef>const u8 * <parameter>key</parameter></paramdef> 7043 <paramdef>unsigned int <parameter>keylen</parameter></paramdef> 7044 </funcprototype></funcsynopsis> 7045</refsynopsisdiv> 7046<refsect1> 7047 <title>Arguments</title> 7048 <variablelist> 7049 <varlistentry> 7050 <term><parameter>tfm</parameter></term> 7051 <listitem> 7052 <para> 7053 cipher handle 7054 </para> 7055 </listitem> 7056 </varlistentry> 7057 <varlistentry> 7058 <term><parameter>key</parameter></term> 7059 <listitem> 7060 <para> 7061 buffer holding the key 7062 </para> 7063 </listitem> 7064 </varlistentry> 7065 <varlistentry> 7066 <term><parameter>keylen</parameter></term> 7067 <listitem> 7068 <para> 7069 length of the key in bytes 7070 </para> 7071 </listitem> 7072 </varlistentry> 7073 </variablelist> 7074</refsect1> 7075<refsect1> 7076<title>Description</title> 7077<para> 7078 The caller provided key is set for the ahash cipher. The cipher 7079 handle must point to a keyed hash in order for this function to succeed. 7080</para> 7081</refsect1> 7082<refsect1> 7083<title>Return</title> 7084<para> 7085 0 if the setting of the key was successful; < 0 if an error occurred 7086</para> 7087</refsect1> 7088</refentry> 7089 7090<refentry id="API-crypto-ahash-finup"> 7091<refentryinfo> 7092 <title>LINUX</title> 7093 <productname>Kernel Hackers Manual</productname> 7094 <date>July 2017</date> 7095</refentryinfo> 7096<refmeta> 7097 <refentrytitle><phrase>crypto_ahash_finup</phrase></refentrytitle> 7098 <manvolnum>9</manvolnum> 7099 <refmiscinfo class="version">4.1.27</refmiscinfo> 7100</refmeta> 7101<refnamediv> 7102 <refname>crypto_ahash_finup</refname> 7103 <refpurpose> 7104 update and finalize message digest 7105 </refpurpose> 7106</refnamediv> 7107<refsynopsisdiv> 7108 <title>Synopsis</title> 7109 <funcsynopsis><funcprototype> 7110 <funcdef>int <function>crypto_ahash_finup </function></funcdef> 7111 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 7112 </funcprototype></funcsynopsis> 7113</refsynopsisdiv> 7114<refsect1> 7115 <title>Arguments</title> 7116 <variablelist> 7117 <varlistentry> 7118 <term><parameter>req</parameter></term> 7119 <listitem> 7120 <para> 7121 reference to the ahash_request handle that holds all information 7122 needed to perform the cipher operation 7123 </para> 7124 </listitem> 7125 </varlistentry> 7126 </variablelist> 7127</refsect1> 7128<refsect1> 7129<title>Description</title> 7130<para> 7131 This function is a <quote>short-hand</quote> for the function calls of 7132 crypto_ahash_update and crypto_shash_final. The parameters have the same 7133 meaning as discussed for those separate functions. 7134</para> 7135</refsect1> 7136<refsect1> 7137<title>Return</title> 7138<para> 7139 0 if the message digest creation was successful; < 0 if an error 7140 occurred 7141</para> 7142</refsect1> 7143</refentry> 7144 7145<refentry id="API-crypto-ahash-final"> 7146<refentryinfo> 7147 <title>LINUX</title> 7148 <productname>Kernel Hackers Manual</productname> 7149 <date>July 2017</date> 7150</refentryinfo> 7151<refmeta> 7152 <refentrytitle><phrase>crypto_ahash_final</phrase></refentrytitle> 7153 <manvolnum>9</manvolnum> 7154 <refmiscinfo class="version">4.1.27</refmiscinfo> 7155</refmeta> 7156<refnamediv> 7157 <refname>crypto_ahash_final</refname> 7158 <refpurpose> 7159 calculate message digest 7160 </refpurpose> 7161</refnamediv> 7162<refsynopsisdiv> 7163 <title>Synopsis</title> 7164 <funcsynopsis><funcprototype> 7165 <funcdef>int <function>crypto_ahash_final </function></funcdef> 7166 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 7167 </funcprototype></funcsynopsis> 7168</refsynopsisdiv> 7169<refsect1> 7170 <title>Arguments</title> 7171 <variablelist> 7172 <varlistentry> 7173 <term><parameter>req</parameter></term> 7174 <listitem> 7175 <para> 7176 reference to the ahash_request handle that holds all information 7177 needed to perform the cipher operation 7178 </para> 7179 </listitem> 7180 </varlistentry> 7181 </variablelist> 7182</refsect1> 7183<refsect1> 7184<title>Description</title> 7185<para> 7186 Finalize the message digest operation and create the message digest 7187 based on all data added to the cipher handle. The message digest is placed 7188 into the output buffer registered with the ahash_request handle. 7189</para> 7190</refsect1> 7191<refsect1> 7192<title>Return</title> 7193<para> 7194 0 if the message digest creation was successful; < 0 if an error 7195 occurred 7196</para> 7197</refsect1> 7198</refentry> 7199 7200<refentry id="API-crypto-ahash-digest"> 7201<refentryinfo> 7202 <title>LINUX</title> 7203 <productname>Kernel Hackers Manual</productname> 7204 <date>July 2017</date> 7205</refentryinfo> 7206<refmeta> 7207 <refentrytitle><phrase>crypto_ahash_digest</phrase></refentrytitle> 7208 <manvolnum>9</manvolnum> 7209 <refmiscinfo class="version">4.1.27</refmiscinfo> 7210</refmeta> 7211<refnamediv> 7212 <refname>crypto_ahash_digest</refname> 7213 <refpurpose> 7214 calculate message digest for a buffer 7215 </refpurpose> 7216</refnamediv> 7217<refsynopsisdiv> 7218 <title>Synopsis</title> 7219 <funcsynopsis><funcprototype> 7220 <funcdef>int <function>crypto_ahash_digest </function></funcdef> 7221 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 7222 </funcprototype></funcsynopsis> 7223</refsynopsisdiv> 7224<refsect1> 7225 <title>Arguments</title> 7226 <variablelist> 7227 <varlistentry> 7228 <term><parameter>req</parameter></term> 7229 <listitem> 7230 <para> 7231 reference to the ahash_request handle that holds all information 7232 needed to perform the cipher operation 7233 </para> 7234 </listitem> 7235 </varlistentry> 7236 </variablelist> 7237</refsect1> 7238<refsect1> 7239<title>Description</title> 7240<para> 7241 This function is a <quote>short-hand</quote> for the function calls of crypto_ahash_init, 7242 crypto_ahash_update and crypto_ahash_final. The parameters have the same 7243 meaning as discussed for those separate three functions. 7244</para> 7245</refsect1> 7246<refsect1> 7247<title>Return</title> 7248<para> 7249 0 if the message digest creation was successful; < 0 if an error 7250 occurred 7251</para> 7252</refsect1> 7253</refentry> 7254 7255<refentry id="API-crypto-ahash-export"> 7256<refentryinfo> 7257 <title>LINUX</title> 7258 <productname>Kernel Hackers Manual</productname> 7259 <date>July 2017</date> 7260</refentryinfo> 7261<refmeta> 7262 <refentrytitle><phrase>crypto_ahash_export</phrase></refentrytitle> 7263 <manvolnum>9</manvolnum> 7264 <refmiscinfo class="version">4.1.27</refmiscinfo> 7265</refmeta> 7266<refnamediv> 7267 <refname>crypto_ahash_export</refname> 7268 <refpurpose> 7269 extract current message digest state 7270 </refpurpose> 7271</refnamediv> 7272<refsynopsisdiv> 7273 <title>Synopsis</title> 7274 <funcsynopsis><funcprototype> 7275 <funcdef>int <function>crypto_ahash_export </function></funcdef> 7276 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 7277 <paramdef>void * <parameter>out</parameter></paramdef> 7278 </funcprototype></funcsynopsis> 7279</refsynopsisdiv> 7280<refsect1> 7281 <title>Arguments</title> 7282 <variablelist> 7283 <varlistentry> 7284 <term><parameter>req</parameter></term> 7285 <listitem> 7286 <para> 7287 reference to the ahash_request handle whose state is exported 7288 </para> 7289 </listitem> 7290 </varlistentry> 7291 <varlistentry> 7292 <term><parameter>out</parameter></term> 7293 <listitem> 7294 <para> 7295 output buffer of sufficient size that can hold the hash state 7296 </para> 7297 </listitem> 7298 </varlistentry> 7299 </variablelist> 7300</refsect1> 7301<refsect1> 7302<title>Description</title> 7303<para> 7304 This function exports the hash state of the ahash_request handle into the 7305 caller-allocated output buffer out which must have sufficient size (e.g. by 7306 calling crypto_ahash_reqsize). 7307</para> 7308</refsect1> 7309<refsect1> 7310<title>Return</title> 7311<para> 7312 0 if the export was successful; < 0 if an error occurred 7313</para> 7314</refsect1> 7315</refentry> 7316 7317<refentry id="API-crypto-ahash-import"> 7318<refentryinfo> 7319 <title>LINUX</title> 7320 <productname>Kernel Hackers Manual</productname> 7321 <date>July 2017</date> 7322</refentryinfo> 7323<refmeta> 7324 <refentrytitle><phrase>crypto_ahash_import</phrase></refentrytitle> 7325 <manvolnum>9</manvolnum> 7326 <refmiscinfo class="version">4.1.27</refmiscinfo> 7327</refmeta> 7328<refnamediv> 7329 <refname>crypto_ahash_import</refname> 7330 <refpurpose> 7331 import message digest state 7332 </refpurpose> 7333</refnamediv> 7334<refsynopsisdiv> 7335 <title>Synopsis</title> 7336 <funcsynopsis><funcprototype> 7337 <funcdef>int <function>crypto_ahash_import </function></funcdef> 7338 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 7339 <paramdef>const void * <parameter>in</parameter></paramdef> 7340 </funcprototype></funcsynopsis> 7341</refsynopsisdiv> 7342<refsect1> 7343 <title>Arguments</title> 7344 <variablelist> 7345 <varlistentry> 7346 <term><parameter>req</parameter></term> 7347 <listitem> 7348 <para> 7349 reference to ahash_request handle the state is imported into 7350 </para> 7351 </listitem> 7352 </varlistentry> 7353 <varlistentry> 7354 <term><parameter>in</parameter></term> 7355 <listitem> 7356 <para> 7357 buffer holding the state 7358 </para> 7359 </listitem> 7360 </varlistentry> 7361 </variablelist> 7362</refsect1> 7363<refsect1> 7364<title>Description</title> 7365<para> 7366 This function imports the hash state into the ahash_request handle from the 7367 input buffer. That buffer should have been generated with the 7368 crypto_ahash_export function. 7369</para> 7370</refsect1> 7371<refsect1> 7372<title>Return</title> 7373<para> 7374 0 if the import was successful; < 0 if an error occurred 7375</para> 7376</refsect1> 7377</refentry> 7378 7379 </sect1> 7380 <sect1><title>Asynchronous Hash Request Handle</title> 7381<para> 7382 </para><para> 7383 The <structname>ahash_request</structname> data structure contains all pointers to data 7384 required for the asynchronous cipher operation. This includes the cipher 7385 handle (which can be used by multiple <structname>ahash_request</structname> instances), pointer 7386 to plaintext and the message digest output buffer, asynchronous callback 7387 function, etc. It acts as a handle to the ahash_request_* API calls in a 7388 similar way as ahash handle to the crypto_ahash_* API calls. 7389</para> 7390 7391<refentry id="API-ahash-request-set-tfm"> 7392<refentryinfo> 7393 <title>LINUX</title> 7394 <productname>Kernel Hackers Manual</productname> 7395 <date>July 2017</date> 7396</refentryinfo> 7397<refmeta> 7398 <refentrytitle><phrase>ahash_request_set_tfm</phrase></refentrytitle> 7399 <manvolnum>9</manvolnum> 7400 <refmiscinfo class="version">4.1.27</refmiscinfo> 7401</refmeta> 7402<refnamediv> 7403 <refname>ahash_request_set_tfm</refname> 7404 <refpurpose> 7405 update cipher handle reference in request 7406 </refpurpose> 7407</refnamediv> 7408<refsynopsisdiv> 7409 <title>Synopsis</title> 7410 <funcsynopsis><funcprototype> 7411 <funcdef>void <function>ahash_request_set_tfm </function></funcdef> 7412 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 7413 <paramdef>struct crypto_ahash * <parameter>tfm</parameter></paramdef> 7414 </funcprototype></funcsynopsis> 7415</refsynopsisdiv> 7416<refsect1> 7417 <title>Arguments</title> 7418 <variablelist> 7419 <varlistentry> 7420 <term><parameter>req</parameter></term> 7421 <listitem> 7422 <para> 7423 request handle to be modified 7424 </para> 7425 </listitem> 7426 </varlistentry> 7427 <varlistentry> 7428 <term><parameter>tfm</parameter></term> 7429 <listitem> 7430 <para> 7431 cipher handle that shall be added to the request handle 7432 </para> 7433 </listitem> 7434 </varlistentry> 7435 </variablelist> 7436</refsect1> 7437<refsect1> 7438<title>Description</title> 7439<para> 7440 Allow the caller to replace the existing ahash handle in the request 7441 data structure with a different one. 7442</para> 7443</refsect1> 7444</refentry> 7445 7446<refentry id="API-ahash-request-alloc"> 7447<refentryinfo> 7448 <title>LINUX</title> 7449 <productname>Kernel Hackers Manual</productname> 7450 <date>July 2017</date> 7451</refentryinfo> 7452<refmeta> 7453 <refentrytitle><phrase>ahash_request_alloc</phrase></refentrytitle> 7454 <manvolnum>9</manvolnum> 7455 <refmiscinfo class="version">4.1.27</refmiscinfo> 7456</refmeta> 7457<refnamediv> 7458 <refname>ahash_request_alloc</refname> 7459 <refpurpose> 7460 allocate request data structure 7461 </refpurpose> 7462</refnamediv> 7463<refsynopsisdiv> 7464 <title>Synopsis</title> 7465 <funcsynopsis><funcprototype> 7466 <funcdef>struct ahash_request * <function>ahash_request_alloc </function></funcdef> 7467 <paramdef>struct crypto_ahash * <parameter>tfm</parameter></paramdef> 7468 <paramdef>gfp_t <parameter>gfp</parameter></paramdef> 7469 </funcprototype></funcsynopsis> 7470</refsynopsisdiv> 7471<refsect1> 7472 <title>Arguments</title> 7473 <variablelist> 7474 <varlistentry> 7475 <term><parameter>tfm</parameter></term> 7476 <listitem> 7477 <para> 7478 cipher handle to be registered with the request 7479 </para> 7480 </listitem> 7481 </varlistentry> 7482 <varlistentry> 7483 <term><parameter>gfp</parameter></term> 7484 <listitem> 7485 <para> 7486 memory allocation flag that is handed to kmalloc by the API call. 7487 </para> 7488 </listitem> 7489 </varlistentry> 7490 </variablelist> 7491</refsect1> 7492<refsect1> 7493<title>Description</title> 7494<para> 7495 Allocate the request data structure that must be used with the ahash 7496 message digest API calls. During 7497 the allocation, the provided ahash handle 7498 is registered in the request data structure. 7499</para> 7500</refsect1> 7501<refsect1> 7502<title>Return</title> 7503<para> 7504 allocated request handle in case of success; <function>IS_ERR</function> is true in case 7505 of an error, <function>PTR_ERR</function> returns the error code. 7506</para> 7507</refsect1> 7508</refentry> 7509 7510<refentry id="API-ahash-request-free"> 7511<refentryinfo> 7512 <title>LINUX</title> 7513 <productname>Kernel Hackers Manual</productname> 7514 <date>July 2017</date> 7515</refentryinfo> 7516<refmeta> 7517 <refentrytitle><phrase>ahash_request_free</phrase></refentrytitle> 7518 <manvolnum>9</manvolnum> 7519 <refmiscinfo class="version">4.1.27</refmiscinfo> 7520</refmeta> 7521<refnamediv> 7522 <refname>ahash_request_free</refname> 7523 <refpurpose> 7524 zeroize and free the request data structure 7525 </refpurpose> 7526</refnamediv> 7527<refsynopsisdiv> 7528 <title>Synopsis</title> 7529 <funcsynopsis><funcprototype> 7530 <funcdef>void <function>ahash_request_free </function></funcdef> 7531 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 7532 </funcprototype></funcsynopsis> 7533</refsynopsisdiv> 7534<refsect1> 7535 <title>Arguments</title> 7536 <variablelist> 7537 <varlistentry> 7538 <term><parameter>req</parameter></term> 7539 <listitem> 7540 <para> 7541 request data structure cipher handle to be freed 7542 </para> 7543 </listitem> 7544 </varlistentry> 7545 </variablelist> 7546</refsect1> 7547</refentry> 7548 7549<refentry id="API-ahash-request-set-callback"> 7550<refentryinfo> 7551 <title>LINUX</title> 7552 <productname>Kernel Hackers Manual</productname> 7553 <date>July 2017</date> 7554</refentryinfo> 7555<refmeta> 7556 <refentrytitle><phrase>ahash_request_set_callback</phrase></refentrytitle> 7557 <manvolnum>9</manvolnum> 7558 <refmiscinfo class="version">4.1.27</refmiscinfo> 7559</refmeta> 7560<refnamediv> 7561 <refname>ahash_request_set_callback</refname> 7562 <refpurpose> 7563 set asynchronous callback function 7564 </refpurpose> 7565</refnamediv> 7566<refsynopsisdiv> 7567 <title>Synopsis</title> 7568 <funcsynopsis><funcprototype> 7569 <funcdef>void <function>ahash_request_set_callback </function></funcdef> 7570 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 7571 <paramdef>u32 <parameter>flags</parameter></paramdef> 7572 <paramdef>crypto_completion_t <parameter>compl</parameter></paramdef> 7573 <paramdef>void * <parameter>data</parameter></paramdef> 7574 </funcprototype></funcsynopsis> 7575</refsynopsisdiv> 7576<refsect1> 7577 <title>Arguments</title> 7578 <variablelist> 7579 <varlistentry> 7580 <term><parameter>req</parameter></term> 7581 <listitem> 7582 <para> 7583 request handle 7584 </para> 7585 </listitem> 7586 </varlistentry> 7587 <varlistentry> 7588 <term><parameter>flags</parameter></term> 7589 <listitem> 7590 <para> 7591 specify zero or an ORing of the flags 7592 CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and 7593 increase the wait queue beyond the initial maximum size; 7594 CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep 7595 </para> 7596 </listitem> 7597 </varlistentry> 7598 <varlistentry> 7599 <term><parameter>compl</parameter></term> 7600 <listitem> 7601 <para> 7602 callback function pointer to be registered with the request handle 7603 </para> 7604 </listitem> 7605 </varlistentry> 7606 <varlistentry> 7607 <term><parameter>data</parameter></term> 7608 <listitem> 7609 <para> 7610 The data pointer refers to memory that is not used by the kernel 7611 crypto API, but provided to the callback function for it to use. Here, 7612 the caller can provide a reference to memory the callback function can 7613 operate on. As the callback function is invoked asynchronously to the 7614 related functionality, it may need to access data structures of the 7615 related functionality which can be referenced using this pointer. The 7616 callback function can access the memory via the <quote>data</quote> field in the 7617 <structname>crypto_async_request</structname> data structure provided to the callback function. 7618 </para> 7619 </listitem> 7620 </varlistentry> 7621 </variablelist> 7622</refsect1> 7623<refsect1> 7624<title>Description</title> 7625<para> 7626 This function allows setting the callback function that is triggered once 7627 the cipher operation completes. 7628 </para><para> 7629 7630 The callback function is registered with the <structname>ahash_request</structname> handle and 7631 must comply with the following template 7632 </para><para> 7633 7634 void callback_function(struct crypto_async_request *req, int error) 7635</para> 7636</refsect1> 7637</refentry> 7638 7639<refentry id="API-ahash-request-set-crypt"> 7640<refentryinfo> 7641 <title>LINUX</title> 7642 <productname>Kernel Hackers Manual</productname> 7643 <date>July 2017</date> 7644</refentryinfo> 7645<refmeta> 7646 <refentrytitle><phrase>ahash_request_set_crypt</phrase></refentrytitle> 7647 <manvolnum>9</manvolnum> 7648 <refmiscinfo class="version">4.1.27</refmiscinfo> 7649</refmeta> 7650<refnamediv> 7651 <refname>ahash_request_set_crypt</refname> 7652 <refpurpose> 7653 set data buffers 7654 </refpurpose> 7655</refnamediv> 7656<refsynopsisdiv> 7657 <title>Synopsis</title> 7658 <funcsynopsis><funcprototype> 7659 <funcdef>void <function>ahash_request_set_crypt </function></funcdef> 7660 <paramdef>struct ahash_request * <parameter>req</parameter></paramdef> 7661 <paramdef>struct scatterlist * <parameter>src</parameter></paramdef> 7662 <paramdef>u8 * <parameter>result</parameter></paramdef> 7663 <paramdef>unsigned int <parameter>nbytes</parameter></paramdef> 7664 </funcprototype></funcsynopsis> 7665</refsynopsisdiv> 7666<refsect1> 7667 <title>Arguments</title> 7668 <variablelist> 7669 <varlistentry> 7670 <term><parameter>req</parameter></term> 7671 <listitem> 7672 <para> 7673 ahash_request handle to be updated 7674 </para> 7675 </listitem> 7676 </varlistentry> 7677 <varlistentry> 7678 <term><parameter>src</parameter></term> 7679 <listitem> 7680 <para> 7681 source scatter/gather list 7682 </para> 7683 </listitem> 7684 </varlistentry> 7685 <varlistentry> 7686 <term><parameter>result</parameter></term> 7687 <listitem> 7688 <para> 7689 buffer that is filled with the message digest -- the caller must 7690 ensure that the buffer has sufficient space by, for example, calling 7691 <function>crypto_ahash_digestsize</function> 7692 </para> 7693 </listitem> 7694 </varlistentry> 7695 <varlistentry> 7696 <term><parameter>nbytes</parameter></term> 7697 <listitem> 7698 <para> 7699 number of bytes to process from the source scatter/gather list 7700 </para> 7701 </listitem> 7702 </varlistentry> 7703 </variablelist> 7704</refsect1> 7705<refsect1> 7706<title>Description</title> 7707<para> 7708 By using this call, the caller references the source scatter/gather list. 7709 The source scatter/gather list points to the data the message digest is to 7710 be calculated for. 7711</para> 7712</refsect1> 7713</refentry> 7714 7715 </sect1> 7716 <sect1><title>Synchronous Message Digest API</title> 7717<para> 7718 </para><para> 7719 The synchronous message digest API is used with the ciphers of type 7720 CRYPTO_ALG_TYPE_SHASH (listed as type <quote>shash</quote> in /proc/crypto) 7721 </para><para> 7722 The message digest API is able to maintain state information for the 7723 caller. 7724 </para><para> 7725 The synchronous message digest API can store user-related context in in its 7726 shash_desc request data structure. 7727</para> 7728 7729<refentry id="API-crypto-alloc-shash"> 7730<refentryinfo> 7731 <title>LINUX</title> 7732 <productname>Kernel Hackers Manual</productname> 7733 <date>July 2017</date> 7734</refentryinfo> 7735<refmeta> 7736 <refentrytitle><phrase>crypto_alloc_shash</phrase></refentrytitle> 7737 <manvolnum>9</manvolnum> 7738 <refmiscinfo class="version">4.1.27</refmiscinfo> 7739</refmeta> 7740<refnamediv> 7741 <refname>crypto_alloc_shash</refname> 7742 <refpurpose> 7743 allocate message digest handle 7744 </refpurpose> 7745</refnamediv> 7746<refsynopsisdiv> 7747 <title>Synopsis</title> 7748 <funcsynopsis><funcprototype> 7749 <funcdef>struct crypto_shash * <function>crypto_alloc_shash </function></funcdef> 7750 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 7751 <paramdef>u32 <parameter>type</parameter></paramdef> 7752 <paramdef>u32 <parameter>mask</parameter></paramdef> 7753 </funcprototype></funcsynopsis> 7754</refsynopsisdiv> 7755<refsect1> 7756 <title>Arguments</title> 7757 <variablelist> 7758 <varlistentry> 7759 <term><parameter>alg_name</parameter></term> 7760 <listitem> 7761 <para> 7762 is the cra_name / name or cra_driver_name / driver name of the 7763 message digest cipher 7764 </para> 7765 </listitem> 7766 </varlistentry> 7767 <varlistentry> 7768 <term><parameter>type</parameter></term> 7769 <listitem> 7770 <para> 7771 specifies the type of the cipher 7772 </para> 7773 </listitem> 7774 </varlistentry> 7775 <varlistentry> 7776 <term><parameter>mask</parameter></term> 7777 <listitem> 7778 <para> 7779 specifies the mask for the cipher 7780 </para> 7781 </listitem> 7782 </varlistentry> 7783 </variablelist> 7784</refsect1> 7785<refsect1> 7786<title>Description</title> 7787<para> 7788 Allocate a cipher handle for a message digest. The returned <structname>struct 7789 crypto_shash</structname> is the cipher handle that is required for any subsequent 7790 API invocation for that message digest. 7791</para> 7792</refsect1> 7793<refsect1> 7794<title>Return</title> 7795<para> 7796 allocated cipher handle in case of success; <function>IS_ERR</function> is true in case 7797 of an error, <function>PTR_ERR</function> returns the error code. 7798</para> 7799</refsect1> 7800</refentry> 7801 7802<refentry id="API-crypto-free-shash"> 7803<refentryinfo> 7804 <title>LINUX</title> 7805 <productname>Kernel Hackers Manual</productname> 7806 <date>July 2017</date> 7807</refentryinfo> 7808<refmeta> 7809 <refentrytitle><phrase>crypto_free_shash</phrase></refentrytitle> 7810 <manvolnum>9</manvolnum> 7811 <refmiscinfo class="version">4.1.27</refmiscinfo> 7812</refmeta> 7813<refnamediv> 7814 <refname>crypto_free_shash</refname> 7815 <refpurpose> 7816 zeroize and free the message digest handle 7817 </refpurpose> 7818</refnamediv> 7819<refsynopsisdiv> 7820 <title>Synopsis</title> 7821 <funcsynopsis><funcprototype> 7822 <funcdef>void <function>crypto_free_shash </function></funcdef> 7823 <paramdef>struct crypto_shash * <parameter>tfm</parameter></paramdef> 7824 </funcprototype></funcsynopsis> 7825</refsynopsisdiv> 7826<refsect1> 7827 <title>Arguments</title> 7828 <variablelist> 7829 <varlistentry> 7830 <term><parameter>tfm</parameter></term> 7831 <listitem> 7832 <para> 7833 cipher handle to be freed 7834 </para> 7835 </listitem> 7836 </varlistentry> 7837 </variablelist> 7838</refsect1> 7839</refentry> 7840 7841<refentry id="API-crypto-shash-blocksize"> 7842<refentryinfo> 7843 <title>LINUX</title> 7844 <productname>Kernel Hackers Manual</productname> 7845 <date>July 2017</date> 7846</refentryinfo> 7847<refmeta> 7848 <refentrytitle><phrase>crypto_shash_blocksize</phrase></refentrytitle> 7849 <manvolnum>9</manvolnum> 7850 <refmiscinfo class="version">4.1.27</refmiscinfo> 7851</refmeta> 7852<refnamediv> 7853 <refname>crypto_shash_blocksize</refname> 7854 <refpurpose> 7855 obtain block size for cipher 7856 </refpurpose> 7857</refnamediv> 7858<refsynopsisdiv> 7859 <title>Synopsis</title> 7860 <funcsynopsis><funcprototype> 7861 <funcdef>unsigned int <function>crypto_shash_blocksize </function></funcdef> 7862 <paramdef>struct crypto_shash * <parameter>tfm</parameter></paramdef> 7863 </funcprototype></funcsynopsis> 7864</refsynopsisdiv> 7865<refsect1> 7866 <title>Arguments</title> 7867 <variablelist> 7868 <varlistentry> 7869 <term><parameter>tfm</parameter></term> 7870 <listitem> 7871 <para> 7872 cipher handle 7873 </para> 7874 </listitem> 7875 </varlistentry> 7876 </variablelist> 7877</refsect1> 7878<refsect1> 7879<title>Description</title> 7880<para> 7881 The block size for the message digest cipher referenced with the cipher 7882 handle is returned. 7883</para> 7884</refsect1> 7885<refsect1> 7886<title>Return</title> 7887<para> 7888 block size of cipher 7889</para> 7890</refsect1> 7891</refentry> 7892 7893<refentry id="API-crypto-shash-digestsize"> 7894<refentryinfo> 7895 <title>LINUX</title> 7896 <productname>Kernel Hackers Manual</productname> 7897 <date>July 2017</date> 7898</refentryinfo> 7899<refmeta> 7900 <refentrytitle><phrase>crypto_shash_digestsize</phrase></refentrytitle> 7901 <manvolnum>9</manvolnum> 7902 <refmiscinfo class="version">4.1.27</refmiscinfo> 7903</refmeta> 7904<refnamediv> 7905 <refname>crypto_shash_digestsize</refname> 7906 <refpurpose> 7907 obtain message digest size 7908 </refpurpose> 7909</refnamediv> 7910<refsynopsisdiv> 7911 <title>Synopsis</title> 7912 <funcsynopsis><funcprototype> 7913 <funcdef>unsigned int <function>crypto_shash_digestsize </function></funcdef> 7914 <paramdef>struct crypto_shash * <parameter>tfm</parameter></paramdef> 7915 </funcprototype></funcsynopsis> 7916</refsynopsisdiv> 7917<refsect1> 7918 <title>Arguments</title> 7919 <variablelist> 7920 <varlistentry> 7921 <term><parameter>tfm</parameter></term> 7922 <listitem> 7923 <para> 7924 cipher handle 7925 </para> 7926 </listitem> 7927 </varlistentry> 7928 </variablelist> 7929</refsect1> 7930<refsect1> 7931<title>Description</title> 7932<para> 7933 The size for the message digest created by the message digest cipher 7934 referenced with the cipher handle is returned. 7935</para> 7936</refsect1> 7937<refsect1> 7938<title>Return</title> 7939<para> 7940 digest size of cipher 7941</para> 7942</refsect1> 7943</refentry> 7944 7945<refentry id="API-crypto-shash-descsize"> 7946<refentryinfo> 7947 <title>LINUX</title> 7948 <productname>Kernel Hackers Manual</productname> 7949 <date>July 2017</date> 7950</refentryinfo> 7951<refmeta> 7952 <refentrytitle><phrase>crypto_shash_descsize</phrase></refentrytitle> 7953 <manvolnum>9</manvolnum> 7954 <refmiscinfo class="version">4.1.27</refmiscinfo> 7955</refmeta> 7956<refnamediv> 7957 <refname>crypto_shash_descsize</refname> 7958 <refpurpose> 7959 obtain the operational state size 7960 </refpurpose> 7961</refnamediv> 7962<refsynopsisdiv> 7963 <title>Synopsis</title> 7964 <funcsynopsis><funcprototype> 7965 <funcdef>unsigned int <function>crypto_shash_descsize </function></funcdef> 7966 <paramdef>struct crypto_shash * <parameter>tfm</parameter></paramdef> 7967 </funcprototype></funcsynopsis> 7968</refsynopsisdiv> 7969<refsect1> 7970 <title>Arguments</title> 7971 <variablelist> 7972 <varlistentry> 7973 <term><parameter>tfm</parameter></term> 7974 <listitem> 7975 <para> 7976 cipher handle 7977 </para> 7978 </listitem> 7979 </varlistentry> 7980 </variablelist> 7981</refsect1> 7982<refsect1> 7983<title>Description</title> 7984<para> 7985 The size of the operational state the cipher needs during operation is 7986 returned for the hash referenced with the cipher handle. This size is 7987 required to calculate the memory requirements to allow the caller allocating 7988 sufficient memory for operational state. 7989 </para><para> 7990 7991 The operational state is defined with struct shash_desc where the size of 7992 that data structure is to be calculated as 7993 sizeof(struct shash_desc) + crypto_shash_descsize(alg) 7994</para> 7995</refsect1> 7996<refsect1> 7997<title>Return</title> 7998<para> 7999 size of the operational state 8000</para> 8001</refsect1> 8002</refentry> 8003 8004<refentry id="API-crypto-shash-setkey"> 8005<refentryinfo> 8006 <title>LINUX</title> 8007 <productname>Kernel Hackers Manual</productname> 8008 <date>July 2017</date> 8009</refentryinfo> 8010<refmeta> 8011 <refentrytitle><phrase>crypto_shash_setkey</phrase></refentrytitle> 8012 <manvolnum>9</manvolnum> 8013 <refmiscinfo class="version">4.1.27</refmiscinfo> 8014</refmeta> 8015<refnamediv> 8016 <refname>crypto_shash_setkey</refname> 8017 <refpurpose> 8018 set key for message digest 8019 </refpurpose> 8020</refnamediv> 8021<refsynopsisdiv> 8022 <title>Synopsis</title> 8023 <funcsynopsis><funcprototype> 8024 <funcdef>int <function>crypto_shash_setkey </function></funcdef> 8025 <paramdef>struct crypto_shash * <parameter>tfm</parameter></paramdef> 8026 <paramdef>const u8 * <parameter>key</parameter></paramdef> 8027 <paramdef>unsigned int <parameter>keylen</parameter></paramdef> 8028 </funcprototype></funcsynopsis> 8029</refsynopsisdiv> 8030<refsect1> 8031 <title>Arguments</title> 8032 <variablelist> 8033 <varlistentry> 8034 <term><parameter>tfm</parameter></term> 8035 <listitem> 8036 <para> 8037 cipher handle 8038 </para> 8039 </listitem> 8040 </varlistentry> 8041 <varlistentry> 8042 <term><parameter>key</parameter></term> 8043 <listitem> 8044 <para> 8045 buffer holding the key 8046 </para> 8047 </listitem> 8048 </varlistentry> 8049 <varlistentry> 8050 <term><parameter>keylen</parameter></term> 8051 <listitem> 8052 <para> 8053 length of the key in bytes 8054 </para> 8055 </listitem> 8056 </varlistentry> 8057 </variablelist> 8058</refsect1> 8059<refsect1> 8060<title>Description</title> 8061<para> 8062 The caller provided key is set for the keyed message digest cipher. The 8063 cipher handle must point to a keyed message digest cipher in order for this 8064 function to succeed. 8065</para> 8066</refsect1> 8067<refsect1> 8068<title>Return</title> 8069<para> 8070 0 if the setting of the key was successful; < 0 if an error occurred 8071</para> 8072</refsect1> 8073</refentry> 8074 8075<refentry id="API-crypto-shash-digest"> 8076<refentryinfo> 8077 <title>LINUX</title> 8078 <productname>Kernel Hackers Manual</productname> 8079 <date>July 2017</date> 8080</refentryinfo> 8081<refmeta> 8082 <refentrytitle><phrase>crypto_shash_digest</phrase></refentrytitle> 8083 <manvolnum>9</manvolnum> 8084 <refmiscinfo class="version">4.1.27</refmiscinfo> 8085</refmeta> 8086<refnamediv> 8087 <refname>crypto_shash_digest</refname> 8088 <refpurpose> 8089 calculate message digest for buffer 8090 </refpurpose> 8091</refnamediv> 8092<refsynopsisdiv> 8093 <title>Synopsis</title> 8094 <funcsynopsis><funcprototype> 8095 <funcdef>int <function>crypto_shash_digest </function></funcdef> 8096 <paramdef>struct shash_desc * <parameter>desc</parameter></paramdef> 8097 <paramdef>const u8 * <parameter>data</parameter></paramdef> 8098 <paramdef>unsigned int <parameter>len</parameter></paramdef> 8099 <paramdef>u8 * <parameter>out</parameter></paramdef> 8100 </funcprototype></funcsynopsis> 8101</refsynopsisdiv> 8102<refsect1> 8103 <title>Arguments</title> 8104 <variablelist> 8105 <varlistentry> 8106 <term><parameter>desc</parameter></term> 8107 <listitem> 8108 <para> 8109 see <function>crypto_shash_final</function> 8110 </para> 8111 </listitem> 8112 </varlistentry> 8113 <varlistentry> 8114 <term><parameter>data</parameter></term> 8115 <listitem> 8116 <para> 8117 see <function>crypto_shash_update</function> 8118 </para> 8119 </listitem> 8120 </varlistentry> 8121 <varlistentry> 8122 <term><parameter>len</parameter></term> 8123 <listitem> 8124 <para> 8125 see <function>crypto_shash_update</function> 8126 </para> 8127 </listitem> 8128 </varlistentry> 8129 <varlistentry> 8130 <term><parameter>out</parameter></term> 8131 <listitem> 8132 <para> 8133 see <function>crypto_shash_final</function> 8134 </para> 8135 </listitem> 8136 </varlistentry> 8137 </variablelist> 8138</refsect1> 8139<refsect1> 8140<title>Description</title> 8141<para> 8142 This function is a <quote>short-hand</quote> for the function calls of crypto_shash_init, 8143 crypto_shash_update and crypto_shash_final. The parameters have the same 8144 meaning as discussed for those separate three functions. 8145</para> 8146</refsect1> 8147<refsect1> 8148<title>Return</title> 8149<para> 8150 0 if the message digest creation was successful; < 0 if an error 8151 occurred 8152</para> 8153</refsect1> 8154</refentry> 8155 8156<refentry id="API-crypto-shash-export"> 8157<refentryinfo> 8158 <title>LINUX</title> 8159 <productname>Kernel Hackers Manual</productname> 8160 <date>July 2017</date> 8161</refentryinfo> 8162<refmeta> 8163 <refentrytitle><phrase>crypto_shash_export</phrase></refentrytitle> 8164 <manvolnum>9</manvolnum> 8165 <refmiscinfo class="version">4.1.27</refmiscinfo> 8166</refmeta> 8167<refnamediv> 8168 <refname>crypto_shash_export</refname> 8169 <refpurpose> 8170 extract operational state for message digest 8171 </refpurpose> 8172</refnamediv> 8173<refsynopsisdiv> 8174 <title>Synopsis</title> 8175 <funcsynopsis><funcprototype> 8176 <funcdef>int <function>crypto_shash_export </function></funcdef> 8177 <paramdef>struct shash_desc * <parameter>desc</parameter></paramdef> 8178 <paramdef>void * <parameter>out</parameter></paramdef> 8179 </funcprototype></funcsynopsis> 8180</refsynopsisdiv> 8181<refsect1> 8182 <title>Arguments</title> 8183 <variablelist> 8184 <varlistentry> 8185 <term><parameter>desc</parameter></term> 8186 <listitem> 8187 <para> 8188 reference to the operational state handle whose state is exported 8189 </para> 8190 </listitem> 8191 </varlistentry> 8192 <varlistentry> 8193 <term><parameter>out</parameter></term> 8194 <listitem> 8195 <para> 8196 output buffer of sufficient size that can hold the hash state 8197 </para> 8198 </listitem> 8199 </varlistentry> 8200 </variablelist> 8201</refsect1> 8202<refsect1> 8203<title>Description</title> 8204<para> 8205 This function exports the hash state of the operational state handle into the 8206 caller-allocated output buffer out which must have sufficient size (e.g. by 8207 calling crypto_shash_descsize). 8208</para> 8209</refsect1> 8210<refsect1> 8211<title>Return</title> 8212<para> 8213 0 if the export creation was successful; < 0 if an error occurred 8214</para> 8215</refsect1> 8216</refentry> 8217 8218<refentry id="API-crypto-shash-import"> 8219<refentryinfo> 8220 <title>LINUX</title> 8221 <productname>Kernel Hackers Manual</productname> 8222 <date>July 2017</date> 8223</refentryinfo> 8224<refmeta> 8225 <refentrytitle><phrase>crypto_shash_import</phrase></refentrytitle> 8226 <manvolnum>9</manvolnum> 8227 <refmiscinfo class="version">4.1.27</refmiscinfo> 8228</refmeta> 8229<refnamediv> 8230 <refname>crypto_shash_import</refname> 8231 <refpurpose> 8232 import operational state 8233 </refpurpose> 8234</refnamediv> 8235<refsynopsisdiv> 8236 <title>Synopsis</title> 8237 <funcsynopsis><funcprototype> 8238 <funcdef>int <function>crypto_shash_import </function></funcdef> 8239 <paramdef>struct shash_desc * <parameter>desc</parameter></paramdef> 8240 <paramdef>const void * <parameter>in</parameter></paramdef> 8241 </funcprototype></funcsynopsis> 8242</refsynopsisdiv> 8243<refsect1> 8244 <title>Arguments</title> 8245 <variablelist> 8246 <varlistentry> 8247 <term><parameter>desc</parameter></term> 8248 <listitem> 8249 <para> 8250 reference to the operational state handle the state imported into 8251 </para> 8252 </listitem> 8253 </varlistentry> 8254 <varlistentry> 8255 <term><parameter>in</parameter></term> 8256 <listitem> 8257 <para> 8258 buffer holding the state 8259 </para> 8260 </listitem> 8261 </varlistentry> 8262 </variablelist> 8263</refsect1> 8264<refsect1> 8265<title>Description</title> 8266<para> 8267 This function imports the hash state into the operational state handle from 8268 the input buffer. That buffer should have been generated with the 8269 crypto_ahash_export function. 8270</para> 8271</refsect1> 8272<refsect1> 8273<title>Return</title> 8274<para> 8275 0 if the import was successful; < 0 if an error occurred 8276</para> 8277</refsect1> 8278</refentry> 8279 8280<refentry id="API-crypto-shash-init"> 8281<refentryinfo> 8282 <title>LINUX</title> 8283 <productname>Kernel Hackers Manual</productname> 8284 <date>July 2017</date> 8285</refentryinfo> 8286<refmeta> 8287 <refentrytitle><phrase>crypto_shash_init</phrase></refentrytitle> 8288 <manvolnum>9</manvolnum> 8289 <refmiscinfo class="version">4.1.27</refmiscinfo> 8290</refmeta> 8291<refnamediv> 8292 <refname>crypto_shash_init</refname> 8293 <refpurpose> 8294 (re)initialize message digest 8295 </refpurpose> 8296</refnamediv> 8297<refsynopsisdiv> 8298 <title>Synopsis</title> 8299 <funcsynopsis><funcprototype> 8300 <funcdef>int <function>crypto_shash_init </function></funcdef> 8301 <paramdef>struct shash_desc * <parameter>desc</parameter></paramdef> 8302 </funcprototype></funcsynopsis> 8303</refsynopsisdiv> 8304<refsect1> 8305 <title>Arguments</title> 8306 <variablelist> 8307 <varlistentry> 8308 <term><parameter>desc</parameter></term> 8309 <listitem> 8310 <para> 8311 operational state handle that is already filled 8312 </para> 8313 </listitem> 8314 </varlistentry> 8315 </variablelist> 8316</refsect1> 8317<refsect1> 8318<title>Description</title> 8319<para> 8320 The call (re-)initializes the message digest referenced by the 8321 operational state handle. Any potentially existing state created by 8322 previous operations is discarded. 8323</para> 8324</refsect1> 8325<refsect1> 8326<title>Return</title> 8327<para> 8328 0 if the message digest initialization was successful; < 0 if an 8329 error occurred 8330</para> 8331</refsect1> 8332</refentry> 8333 8334<refentry id="API-crypto-shash-update"> 8335<refentryinfo> 8336 <title>LINUX</title> 8337 <productname>Kernel Hackers Manual</productname> 8338 <date>July 2017</date> 8339</refentryinfo> 8340<refmeta> 8341 <refentrytitle><phrase>crypto_shash_update</phrase></refentrytitle> 8342 <manvolnum>9</manvolnum> 8343 <refmiscinfo class="version">4.1.27</refmiscinfo> 8344</refmeta> 8345<refnamediv> 8346 <refname>crypto_shash_update</refname> 8347 <refpurpose> 8348 add data to message digest for processing 8349 </refpurpose> 8350</refnamediv> 8351<refsynopsisdiv> 8352 <title>Synopsis</title> 8353 <funcsynopsis><funcprototype> 8354 <funcdef>int <function>crypto_shash_update </function></funcdef> 8355 <paramdef>struct shash_desc * <parameter>desc</parameter></paramdef> 8356 <paramdef>const u8 * <parameter>data</parameter></paramdef> 8357 <paramdef>unsigned int <parameter>len</parameter></paramdef> 8358 </funcprototype></funcsynopsis> 8359</refsynopsisdiv> 8360<refsect1> 8361 <title>Arguments</title> 8362 <variablelist> 8363 <varlistentry> 8364 <term><parameter>desc</parameter></term> 8365 <listitem> 8366 <para> 8367 operational state handle that is already initialized 8368 </para> 8369 </listitem> 8370 </varlistentry> 8371 <varlistentry> 8372 <term><parameter>data</parameter></term> 8373 <listitem> 8374 <para> 8375 input data to be added to the message digest 8376 </para> 8377 </listitem> 8378 </varlistentry> 8379 <varlistentry> 8380 <term><parameter>len</parameter></term> 8381 <listitem> 8382 <para> 8383 length of the input data 8384 </para> 8385 </listitem> 8386 </varlistentry> 8387 </variablelist> 8388</refsect1> 8389<refsect1> 8390<title>Description</title> 8391<para> 8392 Updates the message digest state of the operational state handle. 8393</para> 8394</refsect1> 8395<refsect1> 8396<title>Return</title> 8397<para> 8398 0 if the message digest update was successful; < 0 if an error 8399 occurred 8400</para> 8401</refsect1> 8402</refentry> 8403 8404<refentry id="API-crypto-shash-final"> 8405<refentryinfo> 8406 <title>LINUX</title> 8407 <productname>Kernel Hackers Manual</productname> 8408 <date>July 2017</date> 8409</refentryinfo> 8410<refmeta> 8411 <refentrytitle><phrase>crypto_shash_final</phrase></refentrytitle> 8412 <manvolnum>9</manvolnum> 8413 <refmiscinfo class="version">4.1.27</refmiscinfo> 8414</refmeta> 8415<refnamediv> 8416 <refname>crypto_shash_final</refname> 8417 <refpurpose> 8418 calculate message digest 8419 </refpurpose> 8420</refnamediv> 8421<refsynopsisdiv> 8422 <title>Synopsis</title> 8423 <funcsynopsis><funcprototype> 8424 <funcdef>int <function>crypto_shash_final </function></funcdef> 8425 <paramdef>struct shash_desc * <parameter>desc</parameter></paramdef> 8426 <paramdef>u8 * <parameter>out</parameter></paramdef> 8427 </funcprototype></funcsynopsis> 8428</refsynopsisdiv> 8429<refsect1> 8430 <title>Arguments</title> 8431 <variablelist> 8432 <varlistentry> 8433 <term><parameter>desc</parameter></term> 8434 <listitem> 8435 <para> 8436 operational state handle that is already filled with data 8437 </para> 8438 </listitem> 8439 </varlistentry> 8440 <varlistentry> 8441 <term><parameter>out</parameter></term> 8442 <listitem> 8443 <para> 8444 output buffer filled with the message digest 8445 </para> 8446 </listitem> 8447 </varlistentry> 8448 </variablelist> 8449</refsect1> 8450<refsect1> 8451<title>Description</title> 8452<para> 8453 Finalize the message digest operation and create the message digest 8454 based on all data added to the cipher handle. The message digest is placed 8455 into the output buffer. The caller must ensure that the output buffer is 8456 large enough by using crypto_shash_digestsize. 8457</para> 8458</refsect1> 8459<refsect1> 8460<title>Return</title> 8461<para> 8462 0 if the message digest creation was successful; < 0 if an error 8463 occurred 8464</para> 8465</refsect1> 8466</refentry> 8467 8468<refentry id="API-crypto-shash-finup"> 8469<refentryinfo> 8470 <title>LINUX</title> 8471 <productname>Kernel Hackers Manual</productname> 8472 <date>July 2017</date> 8473</refentryinfo> 8474<refmeta> 8475 <refentrytitle><phrase>crypto_shash_finup</phrase></refentrytitle> 8476 <manvolnum>9</manvolnum> 8477 <refmiscinfo class="version">4.1.27</refmiscinfo> 8478</refmeta> 8479<refnamediv> 8480 <refname>crypto_shash_finup</refname> 8481 <refpurpose> 8482 calculate message digest of buffer 8483 </refpurpose> 8484</refnamediv> 8485<refsynopsisdiv> 8486 <title>Synopsis</title> 8487 <funcsynopsis><funcprototype> 8488 <funcdef>int <function>crypto_shash_finup </function></funcdef> 8489 <paramdef>struct shash_desc * <parameter>desc</parameter></paramdef> 8490 <paramdef>const u8 * <parameter>data</parameter></paramdef> 8491 <paramdef>unsigned int <parameter>len</parameter></paramdef> 8492 <paramdef>u8 * <parameter>out</parameter></paramdef> 8493 </funcprototype></funcsynopsis> 8494</refsynopsisdiv> 8495<refsect1> 8496 <title>Arguments</title> 8497 <variablelist> 8498 <varlistentry> 8499 <term><parameter>desc</parameter></term> 8500 <listitem> 8501 <para> 8502 see <function>crypto_shash_final</function> 8503 </para> 8504 </listitem> 8505 </varlistentry> 8506 <varlistentry> 8507 <term><parameter>data</parameter></term> 8508 <listitem> 8509 <para> 8510 see <function>crypto_shash_update</function> 8511 </para> 8512 </listitem> 8513 </varlistentry> 8514 <varlistentry> 8515 <term><parameter>len</parameter></term> 8516 <listitem> 8517 <para> 8518 see <function>crypto_shash_update</function> 8519 </para> 8520 </listitem> 8521 </varlistentry> 8522 <varlistentry> 8523 <term><parameter>out</parameter></term> 8524 <listitem> 8525 <para> 8526 see <function>crypto_shash_final</function> 8527 </para> 8528 </listitem> 8529 </varlistentry> 8530 </variablelist> 8531</refsect1> 8532<refsect1> 8533<title>Description</title> 8534<para> 8535 This function is a <quote>short-hand</quote> for the function calls of 8536 crypto_shash_update and crypto_shash_final. The parameters have the same 8537 meaning as discussed for those separate functions. 8538</para> 8539</refsect1> 8540<refsect1> 8541<title>Return</title> 8542<para> 8543 0 if the message digest creation was successful; < 0 if an error 8544 occurred 8545</para> 8546</refsect1> 8547</refentry> 8548 8549 </sect1> 8550 <sect1><title>Crypto API Random Number API</title> 8551<para> 8552 </para><para> 8553 The random number generator API is used with the ciphers of type 8554 CRYPTO_ALG_TYPE_RNG (listed as type <quote>rng</quote> in /proc/crypto) 8555</para> 8556 8557<refentry id="API-crypto-alloc-rng"> 8558<refentryinfo> 8559 <title>LINUX</title> 8560 <productname>Kernel Hackers Manual</productname> 8561 <date>July 2017</date> 8562</refentryinfo> 8563<refmeta> 8564 <refentrytitle><phrase>crypto_alloc_rng</phrase></refentrytitle> 8565 <manvolnum>9</manvolnum> 8566 <refmiscinfo class="version">4.1.27</refmiscinfo> 8567</refmeta> 8568<refnamediv> 8569 <refname>crypto_alloc_rng</refname> 8570 <refpurpose> 8571 - allocate RNG handle 8572 </refpurpose> 8573</refnamediv> 8574<refsynopsisdiv> 8575 <title>Synopsis</title> 8576 <funcsynopsis><funcprototype> 8577 <funcdef>struct crypto_rng * <function>crypto_alloc_rng </function></funcdef> 8578 <paramdef>const char * <parameter>alg_name</parameter></paramdef> 8579 <paramdef>u32 <parameter>type</parameter></paramdef> 8580 <paramdef>u32 <parameter>mask</parameter></paramdef> 8581 </funcprototype></funcsynopsis> 8582</refsynopsisdiv> 8583<refsect1> 8584 <title>Arguments</title> 8585 <variablelist> 8586 <varlistentry> 8587 <term><parameter>alg_name</parameter></term> 8588 <listitem> 8589 <para> 8590 is the cra_name / name or cra_driver_name / driver name of the 8591 message digest cipher 8592 </para> 8593 </listitem> 8594 </varlistentry> 8595 <varlistentry> 8596 <term><parameter>type</parameter></term> 8597 <listitem> 8598 <para> 8599 specifies the type of the cipher 8600 </para> 8601 </listitem> 8602 </varlistentry> 8603 <varlistentry> 8604 <term><parameter>mask</parameter></term> 8605 <listitem> 8606 <para> 8607 specifies the mask for the cipher 8608 </para> 8609 </listitem> 8610 </varlistentry> 8611 </variablelist> 8612</refsect1> 8613<refsect1> 8614<title>Description</title> 8615<para> 8616 Allocate a cipher handle for a random number generator. The returned struct 8617 crypto_rng is the cipher handle that is required for any subsequent 8618 API invocation for that random number generator. 8619 </para><para> 8620 8621 For all random number generators, this call creates a new private copy of 8622 the random number generator that does not share a state with other 8623 instances. The only exception is the <quote>krng</quote> random number generator which 8624 is a kernel crypto API use case for the <function>get_random_bytes</function> function of the 8625 /dev/random driver. 8626</para> 8627</refsect1> 8628<refsect1> 8629<title>Return</title> 8630<para> 8631 allocated cipher handle in case of success; <function>IS_ERR</function> is true in case 8632 of an error, <function>PTR_ERR</function> returns the error code. 8633</para> 8634</refsect1> 8635</refentry> 8636 8637<refentry id="API-crypto-rng-alg"> 8638<refentryinfo> 8639 <title>LINUX</title> 8640 <productname>Kernel Hackers Manual</productname> 8641 <date>July 2017</date> 8642</refentryinfo> 8643<refmeta> 8644 <refentrytitle><phrase>crypto_rng_alg</phrase></refentrytitle> 8645 <manvolnum>9</manvolnum> 8646 <refmiscinfo class="version">4.1.27</refmiscinfo> 8647</refmeta> 8648<refnamediv> 8649 <refname>crypto_rng_alg</refname> 8650 <refpurpose> 8651 obtain name of RNG 8652 </refpurpose> 8653</refnamediv> 8654<refsynopsisdiv> 8655 <title>Synopsis</title> 8656 <funcsynopsis><funcprototype> 8657 <funcdef>struct rng_alg * <function>crypto_rng_alg </function></funcdef> 8658 <paramdef>struct crypto_rng * <parameter>tfm</parameter></paramdef> 8659 </funcprototype></funcsynopsis> 8660</refsynopsisdiv> 8661<refsect1> 8662 <title>Arguments</title> 8663 <variablelist> 8664 <varlistentry> 8665 <term><parameter>tfm</parameter></term> 8666 <listitem> 8667 <para> 8668 cipher handle 8669 </para> 8670 </listitem> 8671 </varlistentry> 8672 </variablelist> 8673</refsect1> 8674<refsect1> 8675<title>Description</title> 8676<para> 8677 Return the generic name (cra_name) of the initialized random number generator 8678</para> 8679</refsect1> 8680<refsect1> 8681<title>Return</title> 8682<para> 8683 generic name string 8684</para> 8685</refsect1> 8686</refentry> 8687 8688<refentry id="API-crypto-free-rng"> 8689<refentryinfo> 8690 <title>LINUX</title> 8691 <productname>Kernel Hackers Manual</productname> 8692 <date>July 2017</date> 8693</refentryinfo> 8694<refmeta> 8695 <refentrytitle><phrase>crypto_free_rng</phrase></refentrytitle> 8696 <manvolnum>9</manvolnum> 8697 <refmiscinfo class="version">4.1.27</refmiscinfo> 8698</refmeta> 8699<refnamediv> 8700 <refname>crypto_free_rng</refname> 8701 <refpurpose> 8702 zeroize and free RNG handle 8703 </refpurpose> 8704</refnamediv> 8705<refsynopsisdiv> 8706 <title>Synopsis</title> 8707 <funcsynopsis><funcprototype> 8708 <funcdef>void <function>crypto_free_rng </function></funcdef> 8709 <paramdef>struct crypto_rng * <parameter>tfm</parameter></paramdef> 8710 </funcprototype></funcsynopsis> 8711</refsynopsisdiv> 8712<refsect1> 8713 <title>Arguments</title> 8714 <variablelist> 8715 <varlistentry> 8716 <term><parameter>tfm</parameter></term> 8717 <listitem> 8718 <para> 8719 cipher handle to be freed 8720 </para> 8721 </listitem> 8722 </varlistentry> 8723 </variablelist> 8724</refsect1> 8725</refentry> 8726 8727<refentry id="API-crypto-rng-get-bytes"> 8728<refentryinfo> 8729 <title>LINUX</title> 8730 <productname>Kernel Hackers Manual</productname> 8731 <date>July 2017</date> 8732</refentryinfo> 8733<refmeta> 8734 <refentrytitle><phrase>crypto_rng_get_bytes</phrase></refentrytitle> 8735 <manvolnum>9</manvolnum> 8736 <refmiscinfo class="version">4.1.27</refmiscinfo> 8737</refmeta> 8738<refnamediv> 8739 <refname>crypto_rng_get_bytes</refname> 8740 <refpurpose> 8741 get random number 8742 </refpurpose> 8743</refnamediv> 8744<refsynopsisdiv> 8745 <title>Synopsis</title> 8746 <funcsynopsis><funcprototype> 8747 <funcdef>int <function>crypto_rng_get_bytes </function></funcdef> 8748 <paramdef>struct crypto_rng * <parameter>tfm</parameter></paramdef> 8749 <paramdef>u8 * <parameter>rdata</parameter></paramdef> 8750 <paramdef>unsigned int <parameter>dlen</parameter></paramdef> 8751 </funcprototype></funcsynopsis> 8752</refsynopsisdiv> 8753<refsect1> 8754 <title>Arguments</title> 8755 <variablelist> 8756 <varlistentry> 8757 <term><parameter>tfm</parameter></term> 8758 <listitem> 8759 <para> 8760 cipher handle 8761 </para> 8762 </listitem> 8763 </varlistentry> 8764 <varlistentry> 8765 <term><parameter>rdata</parameter></term> 8766 <listitem> 8767 <para> 8768 output buffer holding the random numbers 8769 </para> 8770 </listitem> 8771 </varlistentry> 8772 <varlistentry> 8773 <term><parameter>dlen</parameter></term> 8774 <listitem> 8775 <para> 8776 length of the output buffer 8777 </para> 8778 </listitem> 8779 </varlistentry> 8780 </variablelist> 8781</refsect1> 8782<refsect1> 8783<title>Description</title> 8784<para> 8785 This function fills the caller-allocated buffer with random numbers using the 8786 random number generator referenced by the cipher handle. 8787</para> 8788</refsect1> 8789<refsect1> 8790<title>Return</title> 8791<para> 8792 0 function was successful; < 0 if an error occurred 8793</para> 8794</refsect1> 8795</refentry> 8796 8797<refentry id="API-crypto-rng-reset"> 8798<refentryinfo> 8799 <title>LINUX</title> 8800 <productname>Kernel Hackers Manual</productname> 8801 <date>July 2017</date> 8802</refentryinfo> 8803<refmeta> 8804 <refentrytitle><phrase>crypto_rng_reset</phrase></refentrytitle> 8805 <manvolnum>9</manvolnum> 8806 <refmiscinfo class="version">4.1.27</refmiscinfo> 8807</refmeta> 8808<refnamediv> 8809 <refname>crypto_rng_reset</refname> 8810 <refpurpose> 8811 re-initialize the RNG 8812 </refpurpose> 8813</refnamediv> 8814<refsynopsisdiv> 8815 <title>Synopsis</title> 8816 <funcsynopsis><funcprototype> 8817 <funcdef>int <function>crypto_rng_reset </function></funcdef> 8818 <paramdef>struct crypto_rng * <parameter>tfm</parameter></paramdef> 8819 <paramdef>u8 * <parameter>seed</parameter></paramdef> 8820 <paramdef>unsigned int <parameter>slen</parameter></paramdef> 8821 </funcprototype></funcsynopsis> 8822</refsynopsisdiv> 8823<refsect1> 8824 <title>Arguments</title> 8825 <variablelist> 8826 <varlistentry> 8827 <term><parameter>tfm</parameter></term> 8828 <listitem> 8829 <para> 8830 cipher handle 8831 </para> 8832 </listitem> 8833 </varlistentry> 8834 <varlistentry> 8835 <term><parameter>seed</parameter></term> 8836 <listitem> 8837 <para> 8838 seed input data 8839 </para> 8840 </listitem> 8841 </varlistentry> 8842 <varlistentry> 8843 <term><parameter>slen</parameter></term> 8844 <listitem> 8845 <para> 8846 length of the seed input data 8847 </para> 8848 </listitem> 8849 </varlistentry> 8850 </variablelist> 8851</refsect1> 8852<refsect1> 8853<title>Description</title> 8854<para> 8855 The reset function completely re-initializes the random number generator 8856 referenced by the cipher handle by clearing the current state. The new state 8857 is initialized with the caller provided seed or automatically, depending 8858 on the random number generator type (the ANSI X9.31 RNG requires 8859 caller-provided seed, the SP800-90A DRBGs perform an automatic seeding). 8860 The seed is provided as a parameter to this function call. The provided seed 8861 should have the length of the seed size defined for the random number 8862 generator as defined by crypto_rng_seedsize. 8863</para> 8864</refsect1> 8865<refsect1> 8866<title>Return</title> 8867<para> 8868 0 if the setting of the key was successful; < 0 if an error occurred 8869</para> 8870</refsect1> 8871</refentry> 8872 8873<refentry id="API-crypto-rng-seedsize"> 8874<refentryinfo> 8875 <title>LINUX</title> 8876 <productname>Kernel Hackers Manual</productname> 8877 <date>July 2017</date> 8878</refentryinfo> 8879<refmeta> 8880 <refentrytitle><phrase>crypto_rng_seedsize</phrase></refentrytitle> 8881 <manvolnum>9</manvolnum> 8882 <refmiscinfo class="version">4.1.27</refmiscinfo> 8883</refmeta> 8884<refnamediv> 8885 <refname>crypto_rng_seedsize</refname> 8886 <refpurpose> 8887 obtain seed size of RNG 8888 </refpurpose> 8889</refnamediv> 8890<refsynopsisdiv> 8891 <title>Synopsis</title> 8892 <funcsynopsis><funcprototype> 8893 <funcdef>int <function>crypto_rng_seedsize </function></funcdef> 8894 <paramdef>struct crypto_rng * <parameter>tfm</parameter></paramdef> 8895 </funcprototype></funcsynopsis> 8896</refsynopsisdiv> 8897<refsect1> 8898 <title>Arguments</title> 8899 <variablelist> 8900 <varlistentry> 8901 <term><parameter>tfm</parameter></term> 8902 <listitem> 8903 <para> 8904 cipher handle 8905 </para> 8906 </listitem> 8907 </varlistentry> 8908 </variablelist> 8909</refsect1> 8910<refsect1> 8911<title>Description</title> 8912<para> 8913 The function returns the seed size for the random number generator 8914 referenced by the cipher handle. This value may be zero if the random 8915 number generator does not implement or require a reseeding. For example, 8916 the SP800-90A DRBGs implement an automated reseeding after reaching a 8917 pre-defined threshold. 8918</para> 8919</refsect1> 8920<refsect1> 8921<title>Return</title> 8922<para> 8923 seed size for the random number generator 8924</para> 8925</refsect1> 8926</refentry> 8927 8928 </sect1> 8929 </chapter> 8930 8931 <chapter id="Code"><title>Code Examples</title> 8932 <sect1><title>Code Example For Asynchronous Block Cipher Operation</title> 8933 <programlisting> 8934 8935struct tcrypt_result { 8936 struct completion completion; 8937 int err; 8938}; 8939 8940/* tie all data structures together */ 8941struct ablkcipher_def { 8942 struct scatterlist sg; 8943 struct crypto_ablkcipher *tfm; 8944 struct ablkcipher_request *req; 8945 struct tcrypt_result result; 8946}; 8947 8948/* Callback function */ 8949static void test_ablkcipher_cb(struct crypto_async_request *req, int error) 8950{ 8951 struct tcrypt_result *result = req->data; 8952 8953 if (error == -EINPROGRESS) 8954 return; 8955 result->err = error; 8956 complete(&result->completion); 8957 pr_info("Encryption finished successfully\n"); 8958} 8959 8960/* Perform cipher operation */ 8961static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk, 8962 int enc) 8963{ 8964 int rc = 0; 8965 8966 if (enc) 8967 rc = crypto_ablkcipher_encrypt(ablk->req); 8968 else 8969 rc = crypto_ablkcipher_decrypt(ablk->req); 8970 8971 switch (rc) { 8972 case 0: 8973 break; 8974 case -EINPROGRESS: 8975 case -EBUSY: 8976 rc = wait_for_completion_interruptible( 8977 &ablk->result.completion); 8978 if (!rc && !ablk->result.err) { 8979 reinit_completion(&ablk->result.completion); 8980 break; 8981 } 8982 default: 8983 pr_info("ablkcipher encrypt returned with %d result %d\n", 8984 rc, ablk->result.err); 8985 break; 8986 } 8987 init_completion(&ablk->result.completion); 8988 8989 return rc; 8990} 8991 8992/* Initialize and trigger cipher operation */ 8993static int test_ablkcipher(void) 8994{ 8995 struct ablkcipher_def ablk; 8996 struct crypto_ablkcipher *ablkcipher = NULL; 8997 struct ablkcipher_request *req = NULL; 8998 char *scratchpad = NULL; 8999 char *ivdata = NULL; 9000 unsigned char key[32]; 9001 int ret = -EFAULT; 9002 9003 ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0); 9004 if (IS_ERR(ablkcipher)) { 9005 pr_info("could not allocate ablkcipher handle\n"); 9006 return PTR_ERR(ablkcipher); 9007 } 9008 9009 req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL); 9010 if (IS_ERR(req)) { 9011 pr_info("could not allocate request queue\n"); 9012 ret = PTR_ERR(req); 9013 goto out; 9014 } 9015 9016 ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, 9017 test_ablkcipher_cb, 9018 &ablk.result); 9019 9020 /* AES 256 with random key */ 9021 get_random_bytes(&key, 32); 9022 if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) { 9023 pr_info("key could not be set\n"); 9024 ret = -EAGAIN; 9025 goto out; 9026 } 9027 9028 /* IV will be random */ 9029 ivdata = kmalloc(16, GFP_KERNEL); 9030 if (!ivdata) { 9031 pr_info("could not allocate ivdata\n"); 9032 goto out; 9033 } 9034 get_random_bytes(ivdata, 16); 9035 9036 /* Input data will be random */ 9037 scratchpad = kmalloc(16, GFP_KERNEL); 9038 if (!scratchpad) { 9039 pr_info("could not allocate scratchpad\n"); 9040 goto out; 9041 } 9042 get_random_bytes(scratchpad, 16); 9043 9044 ablk.tfm = ablkcipher; 9045 ablk.req = req; 9046 9047 /* We encrypt one block */ 9048 sg_init_one(&ablk.sg, scratchpad, 16); 9049 ablkcipher_request_set_crypt(req, &ablk.sg, &ablk.sg, 16, ivdata); 9050 init_completion(&ablk.result.completion); 9051 9052 /* encrypt data */ 9053 ret = test_ablkcipher_encdec(&ablk, 1); 9054 if (ret) 9055 goto out; 9056 9057 pr_info("Encryption triggered successfully\n"); 9058 9059out: 9060 if (ablkcipher) 9061 crypto_free_ablkcipher(ablkcipher); 9062 if (req) 9063 ablkcipher_request_free(req); 9064 if (ivdata) 9065 kfree(ivdata); 9066 if (scratchpad) 9067 kfree(scratchpad); 9068 return ret; 9069} 9070 </programlisting> 9071 </sect1> 9072 9073 <sect1><title>Code Example For Synchronous Block Cipher Operation</title> 9074 <programlisting> 9075 9076static int test_blkcipher(void) 9077{ 9078 struct crypto_blkcipher *blkcipher = NULL; 9079 char *cipher = "cbc(aes)"; 9080 // AES 128 9081 charkey = 9082"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; 9083 chariv = 9084"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; 9085 unsigned int ivsize = 0; 9086 char *scratchpad = NULL; // holds plaintext and ciphertext 9087 struct scatterlist sg; 9088 struct blkcipher_desc desc; 9089 int ret = -EFAULT; 9090 9091 blkcipher = crypto_alloc_blkcipher(cipher, 0, 0); 9092 if (IS_ERR(blkcipher)) { 9093 printk("could not allocate blkcipher handle for %s\n", cipher); 9094 return -PTR_ERR(blkcipher); 9095 } 9096 9097 if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) { 9098 printk("key could not be set\n"); 9099 ret = -EAGAIN; 9100 goto out; 9101 } 9102 9103 ivsize = crypto_blkcipher_ivsize(blkcipher); 9104 if (ivsize) { 9105 if (ivsize != strlen(iv)) 9106 printk("IV length differs from expected length\n"); 9107 crypto_blkcipher_set_iv(blkcipher, iv, ivsize); 9108 } 9109 9110 scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL); 9111 if (!scratchpad) { 9112 printk("could not allocate scratchpad for %s\n", cipher); 9113 goto out; 9114 } 9115 /* get some random data that we want to encrypt */ 9116 get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher)); 9117 9118 desc.flags = 0; 9119 desc.tfm = blkcipher; 9120 sg_init_one(&sg, scratchpad, crypto_blkcipher_blocksize(blkcipher)); 9121 9122 /* encrypt data in place */ 9123 crypto_blkcipher_encrypt(&desc, &sg, &sg, 9124 crypto_blkcipher_blocksize(blkcipher)); 9125 9126 /* decrypt data in place 9127 * crypto_blkcipher_decrypt(&desc, &sg, &sg, 9128 */ crypto_blkcipher_blocksize(blkcipher)); 9129 9130 9131 printk("Cipher operation completed\n"); 9132 return 0; 9133 9134out: 9135 if (blkcipher) 9136 crypto_free_blkcipher(blkcipher); 9137 if (scratchpad) 9138 kzfree(scratchpad); 9139 return ret; 9140} 9141 </programlisting> 9142 </sect1> 9143 9144 <sect1><title>Code Example For Use of Operational State Memory With SHASH</title> 9145 <programlisting> 9146 9147struct sdesc { 9148 struct shash_desc shash; 9149 char ctx[]; 9150}; 9151 9152static struct sdescinit_sdesc(struct crypto_shash *alg) 9153{ 9154 struct sdescsdesc; 9155 int size; 9156 9157 size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); 9158 sdesc = kmalloc(size, GFP_KERNEL); 9159 if (!sdesc) 9160 return ERR_PTR(-ENOMEM); 9161 sdesc->shash.tfm = alg; 9162 sdesc->shash.flags = 0x0; 9163 return sdesc; 9164} 9165 9166static int calc_hash(struct crypto_shashalg, 9167 const unsigned chardata, unsigned int datalen, 9168 unsigned chardigest) { 9169 struct sdescsdesc; 9170 int ret; 9171 9172 sdesc = init_sdesc(alg); 9173 if (IS_ERR(sdesc)) { 9174 pr_info("trusted_key: can't alloc %s\n", hash_alg); 9175 return PTR_ERR(sdesc); 9176 } 9177 9178 ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest); 9179 kfree(sdesc); 9180 return ret; 9181} 9182 </programlisting> 9183 </sect1> 9184 9185 <sect1><title>Code Example For Random Number Generator Usage</title> 9186 <programlisting> 9187 9188static int get_random_numbers(u8 *buf, unsigned int len) 9189{ 9190 struct crypto_rngrng = NULL; 9191 chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ 9192 int ret; 9193 9194 if (!buf || !len) { 9195 pr_debug("No output buffer provided\n"); 9196 return -EINVAL; 9197 } 9198 9199 rng = crypto_alloc_rng(drbg, 0, 0); 9200 if (IS_ERR(rng)) { 9201 pr_debug("could not allocate RNG handle for %s\n", drbg); 9202 return -PTR_ERR(rng); 9203 } 9204 9205 ret = crypto_rng_get_bytes(rng, buf, len); 9206 if (ret < 0) 9207 pr_debug("generation of random numbers failed\n"); 9208 else if (ret == 0) 9209 pr_debug("RNG returned no data"); 9210 else 9211 pr_debug("RNG returned %d bytes of data\n", ret); 9212 9213out: 9214 crypto_free_rng(rng); 9215 return ret; 9216} 9217 </programlisting> 9218 </sect1> 9219 </chapter> 9220 </book> 9221