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 interchangeably. 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 AEAD cipher with a separate 540 IV generator. In 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| aead | <----------------------------------- 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_encrypt() to trigger an encryption 624 operation of the AEAD cipher with IV generator. 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] <ulink url="http://www.chronox.de/libkcapi.html">http://www.chronox.de/libkcapi.html</ulink> 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 family, 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] <ulink url="http://www.chronox.de/libkcapi.html">http://www.chronox.de/libkcapi.html</ulink> 1665 </para> 1666 1667 </sect1> 1668 1669 </chapter> 1670 1671 <chapter id="API"><title>Programming Interface</title> 1672 <para> 1673 Please note that the kernel crypto API contains the AEAD givcrypt 1674 API (crypto_aead_giv* and aead_givcrypt_* function calls in 1675 include/crypto/aead.h). This API is obsolete and will be removed 1676 in the future. To obtain the functionality of an AEAD cipher with 1677 internal IV generation, use the IV generator as a regular cipher. 1678 For example, rfc4106(gcm(aes)) is the AEAD cipher with external 1679 IV generation and seqniv(rfc4106(gcm(aes))) implies that the kernel 1680 crypto API generates the IV. Different IV generators are available. 1681 </para> 1682 <sect1><title>Block Cipher Context Data Structures</title> 1683!Pinclude/linux/crypto.h Block Cipher Context Data Structures 1684!Finclude/crypto/aead.h aead_request 1685 </sect1> 1686 <sect1><title>Block Cipher Algorithm Definitions</title> 1687!Pinclude/linux/crypto.h Block Cipher Algorithm Definitions 1688!Finclude/linux/crypto.h crypto_alg 1689!Finclude/linux/crypto.h ablkcipher_alg 1690!Finclude/crypto/aead.h aead_alg 1691!Finclude/linux/crypto.h blkcipher_alg 1692!Finclude/linux/crypto.h cipher_alg 1693!Finclude/crypto/rng.h rng_alg 1694 </sect1> 1695 <sect1><title>Asynchronous Block Cipher API</title> 1696!Pinclude/linux/crypto.h Asynchronous Block Cipher API 1697!Finclude/linux/crypto.h crypto_alloc_ablkcipher 1698!Finclude/linux/crypto.h crypto_free_ablkcipher 1699!Finclude/linux/crypto.h crypto_has_ablkcipher 1700!Finclude/linux/crypto.h crypto_ablkcipher_ivsize 1701!Finclude/linux/crypto.h crypto_ablkcipher_blocksize 1702!Finclude/linux/crypto.h crypto_ablkcipher_setkey 1703!Finclude/linux/crypto.h crypto_ablkcipher_reqtfm 1704!Finclude/linux/crypto.h crypto_ablkcipher_encrypt 1705!Finclude/linux/crypto.h crypto_ablkcipher_decrypt 1706 </sect1> 1707 <sect1><title>Asynchronous Cipher Request Handle</title> 1708!Pinclude/linux/crypto.h Asynchronous Cipher Request Handle 1709!Finclude/linux/crypto.h crypto_ablkcipher_reqsize 1710!Finclude/linux/crypto.h ablkcipher_request_set_tfm 1711!Finclude/linux/crypto.h ablkcipher_request_alloc 1712!Finclude/linux/crypto.h ablkcipher_request_free 1713!Finclude/linux/crypto.h ablkcipher_request_set_callback 1714!Finclude/linux/crypto.h ablkcipher_request_set_crypt 1715 </sect1> 1716 <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title> 1717!Pinclude/crypto/aead.h Authenticated Encryption With Associated Data (AEAD) Cipher API 1718!Finclude/crypto/aead.h crypto_alloc_aead 1719!Finclude/crypto/aead.h crypto_free_aead 1720!Finclude/crypto/aead.h crypto_aead_ivsize 1721!Finclude/crypto/aead.h crypto_aead_authsize 1722!Finclude/crypto/aead.h crypto_aead_blocksize 1723!Finclude/crypto/aead.h crypto_aead_setkey 1724!Finclude/crypto/aead.h crypto_aead_setauthsize 1725!Finclude/crypto/aead.h crypto_aead_encrypt 1726!Finclude/crypto/aead.h crypto_aead_decrypt 1727 </sect1> 1728 <sect1><title>Asynchronous AEAD Request Handle</title> 1729!Pinclude/crypto/aead.h Asynchronous AEAD Request Handle 1730!Finclude/crypto/aead.h crypto_aead_reqsize 1731!Finclude/crypto/aead.h aead_request_set_tfm 1732!Finclude/crypto/aead.h aead_request_alloc 1733!Finclude/crypto/aead.h aead_request_free 1734!Finclude/crypto/aead.h aead_request_set_callback 1735!Finclude/crypto/aead.h aead_request_set_crypt 1736!Finclude/crypto/aead.h aead_request_set_assoc 1737!Finclude/crypto/aead.h aead_request_set_ad 1738 </sect1> 1739 <sect1><title>Synchronous Block Cipher API</title> 1740!Pinclude/linux/crypto.h Synchronous Block Cipher API 1741!Finclude/linux/crypto.h crypto_alloc_blkcipher 1742!Finclude/linux/crypto.h crypto_free_blkcipher 1743!Finclude/linux/crypto.h crypto_has_blkcipher 1744!Finclude/linux/crypto.h crypto_blkcipher_name 1745!Finclude/linux/crypto.h crypto_blkcipher_ivsize 1746!Finclude/linux/crypto.h crypto_blkcipher_blocksize 1747!Finclude/linux/crypto.h crypto_blkcipher_setkey 1748!Finclude/linux/crypto.h crypto_blkcipher_encrypt 1749!Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv 1750!Finclude/linux/crypto.h crypto_blkcipher_decrypt 1751!Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv 1752!Finclude/linux/crypto.h crypto_blkcipher_set_iv 1753!Finclude/linux/crypto.h crypto_blkcipher_get_iv 1754 </sect1> 1755 <sect1><title>Single Block Cipher API</title> 1756!Pinclude/linux/crypto.h Single Block Cipher API 1757!Finclude/linux/crypto.h crypto_alloc_cipher 1758!Finclude/linux/crypto.h crypto_free_cipher 1759!Finclude/linux/crypto.h crypto_has_cipher 1760!Finclude/linux/crypto.h crypto_cipher_blocksize 1761!Finclude/linux/crypto.h crypto_cipher_setkey 1762!Finclude/linux/crypto.h crypto_cipher_encrypt_one 1763!Finclude/linux/crypto.h crypto_cipher_decrypt_one 1764 </sect1> 1765 <sect1><title>Synchronous Message Digest API</title> 1766!Pinclude/linux/crypto.h Synchronous Message Digest API 1767!Finclude/linux/crypto.h crypto_alloc_hash 1768!Finclude/linux/crypto.h crypto_free_hash 1769!Finclude/linux/crypto.h crypto_has_hash 1770!Finclude/linux/crypto.h crypto_hash_blocksize 1771!Finclude/linux/crypto.h crypto_hash_digestsize 1772!Finclude/linux/crypto.h crypto_hash_init 1773!Finclude/linux/crypto.h crypto_hash_update 1774!Finclude/linux/crypto.h crypto_hash_final 1775!Finclude/linux/crypto.h crypto_hash_digest 1776!Finclude/linux/crypto.h crypto_hash_setkey 1777 </sect1> 1778 <sect1><title>Message Digest Algorithm Definitions</title> 1779!Pinclude/crypto/hash.h Message Digest Algorithm Definitions 1780!Finclude/crypto/hash.h hash_alg_common 1781!Finclude/crypto/hash.h ahash_alg 1782!Finclude/crypto/hash.h shash_alg 1783 </sect1> 1784 <sect1><title>Asynchronous Message Digest API</title> 1785!Pinclude/crypto/hash.h Asynchronous Message Digest API 1786!Finclude/crypto/hash.h crypto_alloc_ahash 1787!Finclude/crypto/hash.h crypto_free_ahash 1788!Finclude/crypto/hash.h crypto_ahash_init 1789!Finclude/crypto/hash.h crypto_ahash_digestsize 1790!Finclude/crypto/hash.h crypto_ahash_reqtfm 1791!Finclude/crypto/hash.h crypto_ahash_reqsize 1792!Finclude/crypto/hash.h crypto_ahash_setkey 1793!Finclude/crypto/hash.h crypto_ahash_finup 1794!Finclude/crypto/hash.h crypto_ahash_final 1795!Finclude/crypto/hash.h crypto_ahash_digest 1796!Finclude/crypto/hash.h crypto_ahash_export 1797!Finclude/crypto/hash.h crypto_ahash_import 1798 </sect1> 1799 <sect1><title>Asynchronous Hash Request Handle</title> 1800!Pinclude/crypto/hash.h Asynchronous Hash Request Handle 1801!Finclude/crypto/hash.h ahash_request_set_tfm 1802!Finclude/crypto/hash.h ahash_request_alloc 1803!Finclude/crypto/hash.h ahash_request_free 1804!Finclude/crypto/hash.h ahash_request_set_callback 1805!Finclude/crypto/hash.h ahash_request_set_crypt 1806 </sect1> 1807 <sect1><title>Synchronous Message Digest API</title> 1808!Pinclude/crypto/hash.h Synchronous Message Digest API 1809!Finclude/crypto/hash.h crypto_alloc_shash 1810!Finclude/crypto/hash.h crypto_free_shash 1811!Finclude/crypto/hash.h crypto_shash_blocksize 1812!Finclude/crypto/hash.h crypto_shash_digestsize 1813!Finclude/crypto/hash.h crypto_shash_descsize 1814!Finclude/crypto/hash.h crypto_shash_setkey 1815!Finclude/crypto/hash.h crypto_shash_digest 1816!Finclude/crypto/hash.h crypto_shash_export 1817!Finclude/crypto/hash.h crypto_shash_import 1818!Finclude/crypto/hash.h crypto_shash_init 1819!Finclude/crypto/hash.h crypto_shash_update 1820!Finclude/crypto/hash.h crypto_shash_final 1821!Finclude/crypto/hash.h crypto_shash_finup 1822 </sect1> 1823 <sect1><title>Crypto API Random Number API</title> 1824!Pinclude/crypto/rng.h Random number generator API 1825!Finclude/crypto/rng.h crypto_alloc_rng 1826!Finclude/crypto/rng.h crypto_rng_alg 1827!Finclude/crypto/rng.h crypto_free_rng 1828!Finclude/crypto/rng.h crypto_rng_get_bytes 1829!Finclude/crypto/rng.h crypto_rng_reset 1830!Finclude/crypto/rng.h crypto_rng_seedsize 1831!Cinclude/crypto/rng.h 1832 </sect1> 1833 </chapter> 1834 1835 <chapter id="Code"><title>Code Examples</title> 1836 <sect1><title>Code Example For Asynchronous Block Cipher Operation</title> 1837 <programlisting> 1838 1839struct tcrypt_result { 1840 struct completion completion; 1841 int err; 1842}; 1843 1844/* tie all data structures together */ 1845struct ablkcipher_def { 1846 struct scatterlist sg; 1847 struct crypto_ablkcipher *tfm; 1848 struct ablkcipher_request *req; 1849 struct tcrypt_result result; 1850}; 1851 1852/* Callback function */ 1853static void test_ablkcipher_cb(struct crypto_async_request *req, int error) 1854{ 1855 struct tcrypt_result *result = req->data; 1856 1857 if (error == -EINPROGRESS) 1858 return; 1859 result->err = error; 1860 complete(&result->completion); 1861 pr_info("Encryption finished successfully\n"); 1862} 1863 1864/* Perform cipher operation */ 1865static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk, 1866 int enc) 1867{ 1868 int rc = 0; 1869 1870 if (enc) 1871 rc = crypto_ablkcipher_encrypt(ablk->req); 1872 else 1873 rc = crypto_ablkcipher_decrypt(ablk->req); 1874 1875 switch (rc) { 1876 case 0: 1877 break; 1878 case -EINPROGRESS: 1879 case -EBUSY: 1880 rc = wait_for_completion_interruptible( 1881 &ablk->result.completion); 1882 if (!rc && !ablk->result.err) { 1883 reinit_completion(&ablk->result.completion); 1884 break; 1885 } 1886 default: 1887 pr_info("ablkcipher encrypt returned with %d result %d\n", 1888 rc, ablk->result.err); 1889 break; 1890 } 1891 init_completion(&ablk->result.completion); 1892 1893 return rc; 1894} 1895 1896/* Initialize and trigger cipher operation */ 1897static int test_ablkcipher(void) 1898{ 1899 struct ablkcipher_def ablk; 1900 struct crypto_ablkcipher *ablkcipher = NULL; 1901 struct ablkcipher_request *req = NULL; 1902 char *scratchpad = NULL; 1903 char *ivdata = NULL; 1904 unsigned char key[32]; 1905 int ret = -EFAULT; 1906 1907 ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0); 1908 if (IS_ERR(ablkcipher)) { 1909 pr_info("could not allocate ablkcipher handle\n"); 1910 return PTR_ERR(ablkcipher); 1911 } 1912 1913 req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL); 1914 if (IS_ERR(req)) { 1915 pr_info("could not allocate request queue\n"); 1916 ret = PTR_ERR(req); 1917 goto out; 1918 } 1919 1920 ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, 1921 test_ablkcipher_cb, 1922 &ablk.result); 1923 1924 /* AES 256 with random key */ 1925 get_random_bytes(&key, 32); 1926 if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) { 1927 pr_info("key could not be set\n"); 1928 ret = -EAGAIN; 1929 goto out; 1930 } 1931 1932 /* IV will be random */ 1933 ivdata = kmalloc(16, GFP_KERNEL); 1934 if (!ivdata) { 1935 pr_info("could not allocate ivdata\n"); 1936 goto out; 1937 } 1938 get_random_bytes(ivdata, 16); 1939 1940 /* Input data will be random */ 1941 scratchpad = kmalloc(16, GFP_KERNEL); 1942 if (!scratchpad) { 1943 pr_info("could not allocate scratchpad\n"); 1944 goto out; 1945 } 1946 get_random_bytes(scratchpad, 16); 1947 1948 ablk.tfm = ablkcipher; 1949 ablk.req = req; 1950 1951 /* We encrypt one block */ 1952 sg_init_one(&ablk.sg, scratchpad, 16); 1953 ablkcipher_request_set_crypt(req, &ablk.sg, &ablk.sg, 16, ivdata); 1954 init_completion(&ablk.result.completion); 1955 1956 /* encrypt data */ 1957 ret = test_ablkcipher_encdec(&ablk, 1); 1958 if (ret) 1959 goto out; 1960 1961 pr_info("Encryption triggered successfully\n"); 1962 1963out: 1964 if (ablkcipher) 1965 crypto_free_ablkcipher(ablkcipher); 1966 if (req) 1967 ablkcipher_request_free(req); 1968 if (ivdata) 1969 kfree(ivdata); 1970 if (scratchpad) 1971 kfree(scratchpad); 1972 return ret; 1973} 1974 </programlisting> 1975 </sect1> 1976 1977 <sect1><title>Code Example For Synchronous Block Cipher Operation</title> 1978 <programlisting> 1979 1980static int test_blkcipher(void) 1981{ 1982 struct crypto_blkcipher *blkcipher = NULL; 1983 char *cipher = "cbc(aes)"; 1984 // AES 128 1985 charkey = 1986"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; 1987 chariv = 1988"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; 1989 unsigned int ivsize = 0; 1990 char *scratchpad = NULL; // holds plaintext and ciphertext 1991 struct scatterlist sg; 1992 struct blkcipher_desc desc; 1993 int ret = -EFAULT; 1994 1995 blkcipher = crypto_alloc_blkcipher(cipher, 0, 0); 1996 if (IS_ERR(blkcipher)) { 1997 printk("could not allocate blkcipher handle for %s\n", cipher); 1998 return -PTR_ERR(blkcipher); 1999 } 2000 2001 if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) { 2002 printk("key could not be set\n"); 2003 ret = -EAGAIN; 2004 goto out; 2005 } 2006 2007 ivsize = crypto_blkcipher_ivsize(blkcipher); 2008 if (ivsize) { 2009 if (ivsize != strlen(iv)) 2010 printk("IV length differs from expected length\n"); 2011 crypto_blkcipher_set_iv(blkcipher, iv, ivsize); 2012 } 2013 2014 scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL); 2015 if (!scratchpad) { 2016 printk("could not allocate scratchpad for %s\n", cipher); 2017 goto out; 2018 } 2019 /* get some random data that we want to encrypt */ 2020 get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher)); 2021 2022 desc.flags = 0; 2023 desc.tfm = blkcipher; 2024 sg_init_one(&sg, scratchpad, crypto_blkcipher_blocksize(blkcipher)); 2025 2026 /* encrypt data in place */ 2027 crypto_blkcipher_encrypt(&desc, &sg, &sg, 2028 crypto_blkcipher_blocksize(blkcipher)); 2029 2030 /* decrypt data in place 2031 * crypto_blkcipher_decrypt(&desc, &sg, &sg, 2032 */ crypto_blkcipher_blocksize(blkcipher)); 2033 2034 2035 printk("Cipher operation completed\n"); 2036 return 0; 2037 2038out: 2039 if (blkcipher) 2040 crypto_free_blkcipher(blkcipher); 2041 if (scratchpad) 2042 kzfree(scratchpad); 2043 return ret; 2044} 2045 </programlisting> 2046 </sect1> 2047 2048 <sect1><title>Code Example For Use of Operational State Memory With SHASH</title> 2049 <programlisting> 2050 2051struct sdesc { 2052 struct shash_desc shash; 2053 char ctx[]; 2054}; 2055 2056static struct sdescinit_sdesc(struct crypto_shash *alg) 2057{ 2058 struct sdescsdesc; 2059 int size; 2060 2061 size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); 2062 sdesc = kmalloc(size, GFP_KERNEL); 2063 if (!sdesc) 2064 return ERR_PTR(-ENOMEM); 2065 sdesc->shash.tfm = alg; 2066 sdesc->shash.flags = 0x0; 2067 return sdesc; 2068} 2069 2070static int calc_hash(struct crypto_shashalg, 2071 const unsigned chardata, unsigned int datalen, 2072 unsigned chardigest) { 2073 struct sdescsdesc; 2074 int ret; 2075 2076 sdesc = init_sdesc(alg); 2077 if (IS_ERR(sdesc)) { 2078 pr_info("trusted_key: can't alloc %s\n", hash_alg); 2079 return PTR_ERR(sdesc); 2080 } 2081 2082 ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest); 2083 kfree(sdesc); 2084 return ret; 2085} 2086 </programlisting> 2087 </sect1> 2088 2089 <sect1><title>Code Example For Random Number Generator Usage</title> 2090 <programlisting> 2091 2092static int get_random_numbers(u8 *buf, unsigned int len) 2093{ 2094 struct crypto_rngrng = NULL; 2095 chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ 2096 int ret; 2097 2098 if (!buf || !len) { 2099 pr_debug("No output buffer provided\n"); 2100 return -EINVAL; 2101 } 2102 2103 rng = crypto_alloc_rng(drbg, 0, 0); 2104 if (IS_ERR(rng)) { 2105 pr_debug("could not allocate RNG handle for %s\n", drbg); 2106 return -PTR_ERR(rng); 2107 } 2108 2109 ret = crypto_rng_get_bytes(rng, buf, len); 2110 if (ret < 0) 2111 pr_debug("generation of random numbers failed\n"); 2112 else if (ret == 0) 2113 pr_debug("RNG returned no data"); 2114 else 2115 pr_debug("RNG returned %d bytes of data\n", ret); 2116 2117out: 2118 crypto_free_rng(rng); 2119 return ret; 2120} 2121 </programlisting> 2122 </sect1> 2123 </chapter> 2124 </book> 2125