Documentation/DocBook/crypto-API.tmpl

   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 discusses 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>&lt;builtin&gt; 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   </chapter>
 513
 514   <chapter id="Development"><title>Developing Cipher Algorithms</title>
 515    <sect1><title>Registering And Unregistering Transformation</title>
 516     <para>
 517      There are three distinct types of registration functions in
 518      the Crypto API. One is used to register a generic cryptographic
 519      transformation, while the other two are specific to HASH
 520      transformations and COMPRESSion. We will discuss the latter
 521      two in a separate chapter, here we will only look at the
 522      generic ones.
 523     </para>
 524
 525     <para>
 526      Before discussing the register functions, the data structure
 527      to be filled with each, struct crypto_alg, must be considered
 528      -- see below for a description of this data structure.
 529     </para>
 530
 531     <para>
 532      The generic registration functions can be found in
 533      include/linux/crypto.h and their definition can be seen below.
 534      The former function registers a single transformation, while
 535      the latter works on an array of transformation descriptions.
 536      The latter is useful when registering transformations in bulk.
 537     </para>
 538
 539     <programlisting>
 540    int crypto_register_alg(struct crypto_alg *alg);
 541    int crypto_register_algs(struct crypto_alg *algs, int count);
 542     </programlisting>
 543
 544     <para>
 545      The counterparts to those functions are listed below.
 546     </para>
 547
 548     <programlisting>
 549    int crypto_unregister_alg(struct crypto_alg *alg);
 550    int crypto_unregister_algs(struct crypto_alg *algs, int count);
 551     </programlisting>
 552
 553     <para>
 554      Notice that both registration and unregistration functions
 555      do return a value, so make sure to handle errors. A return
 556      code of zero implies success. Any return code &lt; 0 implies
 557      an error.
 558     </para>
 559
 560     <para>
 561      The bulk registration / unregistration functions require
 562      that struct crypto_alg is an array of count size. These
 563      functions simply loop over that array and register /
 564      unregister each individual algorithm. If an error occurs,
 565      the loop is terminated at the offending algorithm definition.
 566      That means, the algorithms prior to the offending algorithm
 567      are successfully registered. Note, the caller has no way of
 568      knowing which cipher implementations have successfully
 569      registered. If this is important to know, the caller should
 570      loop through the different implementations using the single
 571      instance *_alg functions for each individual implementation.
 572     </para>
 573    </sect1>
 574
 575    <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title>
 576     <para>
 577      Example of transformations: aes, arc4, ...
 578     </para>
 579
 580     <para>
 581      This section describes the simplest of all transformation
 582      implementations, that being the CIPHER type used for symmetric
 583      ciphers. The CIPHER type is used for transformations which
 584      operate on exactly one block at a time and there are no
 585      dependencies between blocks at all.
 586     </para>
 587
 588     <sect2><title>Registration specifics</title>
 589      <para>
 590       The registration of [CIPHER] algorithm is specific in that
 591       struct crypto_alg field .cra_type is empty. The .cra_u.cipher
 592       has to be filled in with proper callbacks to implement this
 593       transformation.
 594      </para>
 595
 596      <para>
 597       See struct cipher_alg below.
 598      </para>
 599     </sect2>
 600
 601     <sect2><title>Cipher Definition With struct cipher_alg</title>
 602      <para>
 603       Struct cipher_alg defines a single block cipher.
 604      </para>
 605
 606      <para>
 607       Here are schematics of how these functions are called when
 608       operated from other part of the kernel. Note that the
 609       .cia_setkey() call might happen before or after any of these
 610       schematics happen, but must not happen during any of these
 611       are in-flight.
 612      </para>
 613
 614      <para>
 615       <programlisting>
 616          KEY ---.    PLAINTEXT ---.
 617                 v                 v
 618           .cia_setkey() -&gt; .cia_encrypt()
 619                                   |
 620                                   '-----&gt; CIPHERTEXT
 621       </programlisting>
 622      </para>
 623
 624      <para>
 625       Please note that a pattern where .cia_setkey() is called
 626       multiple times is also valid:
 627      </para>
 628
 629      <para>
 630       <programlisting>
 631
 632   KEY1 --.    PLAINTEXT1 --.         KEY2 --.    PLAINTEXT2 --.
 633          v                 v                v                 v
 634    .cia_setkey() -&gt; .cia_encrypt() -&gt; .cia_setkey() -&gt; .cia_encrypt()
 635                            |                                  |
 636                            '---&gt; CIPHERTEXT1                  '---&gt; CIPHERTEXT2
 637       </programlisting>
 638      </para>
 639
 640     </sect2>
 641    </sect1>
 642
 643    <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title>
 644     <para>
 645      Example of transformations: cbc(aes), ecb(arc4), ...
 646     </para>
 647
 648     <para>
 649      This section describes the multi-block cipher transformation
 650      implementations for both synchronous [BLKCIPHER] and
 651      asynchronous [ABLKCIPHER] case. The multi-block ciphers are
 652      used for transformations which operate on scatterlists of
 653      data supplied to the transformation functions. They output
 654      the result into a scatterlist of data as well.
 655     </para>
 656
 657     <sect2><title>Registration Specifics</title>
 658
 659      <para>
 660       The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms
 661       is one of the most standard procedures throughout the crypto API.
 662      </para>
 663
 664      <para>
 665       Note, if a cipher implementation requires a proper alignment
 666       of data, the caller should use the functions of
 667       crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask()
 668       respectively to identify a memory alignment mask. The kernel
 669       crypto API is able to process requests that are unaligned.
 670       This implies, however, additional overhead as the kernel
 671       crypto API needs to perform the realignment of the data which
 672       may imply moving of data.
 673      </para>
 674     </sect2>
 675
 676     <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title>
 677      <para>
 678       Struct blkcipher_alg defines a synchronous block cipher whereas
 679       struct ablkcipher_alg defines an asynchronous block cipher.
 680      </para>
 681
 682      <para>
 683       Please refer to the single block cipher description for schematics
 684       of the block cipher usage. The usage patterns are exactly the same
 685       for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER].
 686      </para>
 687     </sect2>
 688
 689     <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title>
 690      <para>
 691       There are a couple of specifics to the [ABLKCIPHER] interface.
 692      </para>
 693
 694      <para>
 695       First of all, some of the drivers will want to use the
 696       Generic ScatterWalk in case the hardware needs to be fed
 697       separate chunks of the scatterlist which contains the
 698       plaintext and will contain the ciphertext. Please refer
 699       to the ScatterWalk interface offered by the Linux kernel
 700       scatter / gather list implementation.
 701      </para>
 702     </sect2>
 703    </sect1>
 704
 705    <sect1><title>Hashing [HASH]</title>
 706
 707     <para>
 708      Example of transformations: crc32, md5, sha1, sha256,...
 709     </para>
 710
 711     <sect2><title>Registering And Unregistering The Transformation</title>
 712
 713      <para>
 714       There are multiple ways to register a HASH transformation,
 715       depending on whether the transformation is synchronous [SHASH]
 716       or asynchronous [AHASH] and the amount of HASH transformations
 717       we are registering. You can find the prototypes defined in
 718       include/crypto/internal/hash.h:
 719      </para>
 720
 721      <programlisting>
 722    int crypto_register_ahash(struct ahash_alg *alg);
 723
 724    int crypto_register_shash(struct shash_alg *alg);
 725    int crypto_register_shashes(struct shash_alg *algs, int count);
 726      </programlisting>
 727
 728      <para>
 729       The respective counterparts for unregistering the HASH
 730       transformation are as follows:
 731      </para>
 732
 733      <programlisting>
 734    int crypto_unregister_ahash(struct ahash_alg *alg);
 735
 736    int crypto_unregister_shash(struct shash_alg *alg);
 737    int crypto_unregister_shashes(struct shash_alg *algs, int count);
 738      </programlisting>
 739     </sect2>
 740
 741     <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title>
 742      <para>
 743       Here are schematics of how these functions are called when
 744       operated from other part of the kernel. Note that the .setkey()
 745       call might happen before or after any of these schematics happen,
 746       but must not happen during any of these are in-flight. Please note
 747       that calling .init() followed immediately by .finish() is also a
 748       perfectly valid transformation.
 749      </para>
 750
 751      <programlisting>
 752    I)   DATA -----------.
 753                         v
 754          .init() -&gt; .update() -&gt; .final()      ! .update() might not be called
 755                      ^    |         |            at all in this scenario.
 756                      '----'         '---&gt; HASH
 757
 758    II)  DATA -----------.-----------.
 759                         v           v
 760          .init() -&gt; .update() -&gt; .finup()      ! .update() may not be called
 761                      ^    |         |            at all in this scenario.
 762                      '----'         '---&gt; HASH
 763
 764    III) DATA -----------.
 765                         v
 766                     .digest()                  ! The entire process is handled
 767                         |                        by the .digest() call.
 768                         '---------------&gt; HASH
 769      </programlisting>
 770
 771      <para>
 772       Here is a schematic of how the .export()/.import() functions are
 773       called when used from another part of the kernel.
 774      </para>
 775
 776      <programlisting>
 777    KEY--.                 DATA--.
 778         v                       v                  ! .update() may not be called
 779     .setkey() -&gt; .init() -&gt; .update() -&gt; .export()   at all in this scenario.
 780                              ^     |         |
 781                              '-----'         '--&gt; PARTIAL_HASH
 782
 783    ----------- other transformations happen here -----------
 784
 785    PARTIAL_HASH--.   DATA1--.
 786                  v          v
 787              .import -&gt; .update() -&gt; .final()     ! .update() may not be called
 788                          ^    |         |           at all in this scenario.
 789                          '----'         '--&gt; HASH1
 790
 791    PARTIAL_HASH--.   DATA2-.
 792                  v         v
 793              .import -&gt; .finup()
 794                            |
 795                            '---------------&gt; HASH2
 796      </programlisting>
 797     </sect2>
 798
 799     <sect2><title>Specifics Of Asynchronous HASH Transformation</title>
 800      <para>
 801       Some of the drivers will want to use the Generic ScatterWalk
 802       in case the implementation needs to be fed separate chunks of the
 803       scatterlist which contains the input data. The buffer containing
 804       the resulting hash will always be properly aligned to
 805       .cra_alignmask so there is no need to worry about this.
 806      </para>
 807     </sect2>
 808    </sect1>
 809   </chapter>
 810
 811   <chapter id="API"><title>Programming Interface</title>
 812    <sect1><title>Block Cipher Context Data Structures</title>
 813 !Pinclude/linux/crypto.h Block Cipher Context Data Structures
 814 !Finclude/linux/crypto.h aead_request
 815    </sect1>
 816    <sect1><title>Block Cipher Algorithm Definitions</title>
 817 !Pinclude/linux/crypto.h Block Cipher Algorithm Definitions
 818 !Finclude/linux/crypto.h crypto_alg
 819 !Finclude/linux/crypto.h ablkcipher_alg
 820 !Finclude/linux/crypto.h aead_alg
 821 !Finclude/linux/crypto.h blkcipher_alg
 822 !Finclude/linux/crypto.h cipher_alg
 823 !Finclude/linux/crypto.h rng_alg
 824    </sect1>
 825    <sect1><title>Asynchronous Block Cipher API</title>
 826 !Pinclude/linux/crypto.h Asynchronous Block Cipher API
 827 !Finclude/linux/crypto.h crypto_alloc_ablkcipher
 828 !Finclude/linux/crypto.h crypto_free_ablkcipher
 829 !Finclude/linux/crypto.h crypto_has_ablkcipher
 830 !Finclude/linux/crypto.h crypto_ablkcipher_ivsize
 831 !Finclude/linux/crypto.h crypto_ablkcipher_blocksize
 832 !Finclude/linux/crypto.h crypto_ablkcipher_setkey
 833 !Finclude/linux/crypto.h crypto_ablkcipher_reqtfm
 834 !Finclude/linux/crypto.h crypto_ablkcipher_encrypt
 835 !Finclude/linux/crypto.h crypto_ablkcipher_decrypt
 836    </sect1>
 837    <sect1><title>Asynchronous Cipher Request Handle</title>
 838 !Pinclude/linux/crypto.h Asynchronous Cipher Request Handle
 839 !Finclude/linux/crypto.h crypto_ablkcipher_reqsize
 840 !Finclude/linux/crypto.h ablkcipher_request_set_tfm
 841 !Finclude/linux/crypto.h ablkcipher_request_alloc
 842 !Finclude/linux/crypto.h ablkcipher_request_free
 843 !Finclude/linux/crypto.h ablkcipher_request_set_callback
 844 !Finclude/linux/crypto.h ablkcipher_request_set_crypt
 845    </sect1>
 846    <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title>
 847 !Pinclude/linux/crypto.h Authenticated Encryption With Associated Data (AEAD) Cipher API
 848 !Finclude/linux/crypto.h crypto_alloc_aead
 849 !Finclude/linux/crypto.h crypto_free_aead
 850 !Finclude/linux/crypto.h crypto_aead_ivsize
 851 !Finclude/linux/crypto.h crypto_aead_authsize
 852 !Finclude/linux/crypto.h crypto_aead_blocksize
 853 !Finclude/linux/crypto.h crypto_aead_setkey
 854 !Finclude/linux/crypto.h crypto_aead_setauthsize
 855 !Finclude/linux/crypto.h crypto_aead_encrypt
 856 !Finclude/linux/crypto.h crypto_aead_decrypt
 857    </sect1>
 858    <sect1><title>Asynchronous AEAD Request Handle</title>
 859 !Pinclude/linux/crypto.h Asynchronous AEAD Request Handle
 860 !Finclude/linux/crypto.h crypto_aead_reqsize
 861 !Finclude/linux/crypto.h aead_request_set_tfm
 862 !Finclude/linux/crypto.h aead_request_alloc
 863 !Finclude/linux/crypto.h aead_request_free
 864 !Finclude/linux/crypto.h aead_request_set_callback
 865 !Finclude/linux/crypto.h aead_request_set_crypt
 866 !Finclude/linux/crypto.h aead_request_set_assoc
 867    </sect1>
 868    <sect1><title>Synchronous Block Cipher API</title>
 869 !Pinclude/linux/crypto.h Synchronous Block Cipher API
 870 !Finclude/linux/crypto.h crypto_alloc_blkcipher
 871 !Finclude/linux/crypto.h crypto_free_blkcipher
 872 !Finclude/linux/crypto.h crypto_has_blkcipher
 873 !Finclude/linux/crypto.h crypto_blkcipher_name
 874 !Finclude/linux/crypto.h crypto_blkcipher_ivsize
 875 !Finclude/linux/crypto.h crypto_blkcipher_blocksize
 876 !Finclude/linux/crypto.h crypto_blkcipher_setkey
 877 !Finclude/linux/crypto.h crypto_blkcipher_encrypt
 878 !Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv
 879 !Finclude/linux/crypto.h crypto_blkcipher_decrypt
 880 !Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv
 881 !Finclude/linux/crypto.h crypto_blkcipher_set_iv
 882 !Finclude/linux/crypto.h crypto_blkcipher_get_iv
 883    </sect1>
 884    <sect1><title>Single Block Cipher API</title>
 885 !Pinclude/linux/crypto.h Single Block Cipher API
 886 !Finclude/linux/crypto.h crypto_alloc_cipher
 887 !Finclude/linux/crypto.h crypto_free_cipher
 888 !Finclude/linux/crypto.h crypto_has_cipher
 889 !Finclude/linux/crypto.h crypto_cipher_blocksize
 890 !Finclude/linux/crypto.h crypto_cipher_setkey
 891 !Finclude/linux/crypto.h crypto_cipher_encrypt_one
 892 !Finclude/linux/crypto.h crypto_cipher_decrypt_one
 893    </sect1>
 894    <sect1><title>Synchronous Message Digest API</title>
 895 !Pinclude/linux/crypto.h Synchronous Message Digest API
 896 !Finclude/linux/crypto.h crypto_alloc_hash
 897 !Finclude/linux/crypto.h crypto_free_hash
 898 !Finclude/linux/crypto.h crypto_has_hash
 899 !Finclude/linux/crypto.h crypto_hash_blocksize
 900 !Finclude/linux/crypto.h crypto_hash_digestsize
 901 !Finclude/linux/crypto.h crypto_hash_init
 902 !Finclude/linux/crypto.h crypto_hash_update
 903 !Finclude/linux/crypto.h crypto_hash_final
 904 !Finclude/linux/crypto.h crypto_hash_digest
 905 !Finclude/linux/crypto.h crypto_hash_setkey
 906    </sect1>
 907    <sect1><title>Message Digest Algorithm Definitions</title>
 908 !Pinclude/crypto/hash.h Message Digest Algorithm Definitions
 909 !Finclude/crypto/hash.h hash_alg_common
 910 !Finclude/crypto/hash.h ahash_alg
 911 !Finclude/crypto/hash.h shash_alg
 912    </sect1>
 913    <sect1><title>Asynchronous Message Digest API</title>
 914 !Pinclude/crypto/hash.h Asynchronous Message Digest API
 915 !Finclude/crypto/hash.h crypto_alloc_ahash
 916 !Finclude/crypto/hash.h crypto_free_ahash
 917 !Finclude/crypto/hash.h crypto_ahash_init
 918 !Finclude/crypto/hash.h crypto_ahash_digestsize
 919 !Finclude/crypto/hash.h crypto_ahash_reqtfm
 920 !Finclude/crypto/hash.h crypto_ahash_reqsize
 921 !Finclude/crypto/hash.h crypto_ahash_setkey
 922 !Finclude/crypto/hash.h crypto_ahash_finup
 923 !Finclude/crypto/hash.h crypto_ahash_final
 924 !Finclude/crypto/hash.h crypto_ahash_digest
 925 !Finclude/crypto/hash.h crypto_ahash_export
 926 !Finclude/crypto/hash.h crypto_ahash_import
 927    </sect1>
 928    <sect1><title>Asynchronous Hash Request Handle</title>
 929 !Pinclude/crypto/hash.h Asynchronous Hash Request Handle
 930 !Finclude/crypto/hash.h ahash_request_set_tfm
 931 !Finclude/crypto/hash.h ahash_request_alloc
 932 !Finclude/crypto/hash.h ahash_request_free
 933 !Finclude/crypto/hash.h ahash_request_set_callback
 934 !Finclude/crypto/hash.h ahash_request_set_crypt
 935    </sect1>
 936    <sect1><title>Synchronous Message Digest API</title>
 937 !Pinclude/crypto/hash.h Synchronous Message Digest API
 938 !Finclude/crypto/hash.h crypto_alloc_shash
 939 !Finclude/crypto/hash.h crypto_free_shash
 940 !Finclude/crypto/hash.h crypto_shash_blocksize
 941 !Finclude/crypto/hash.h crypto_shash_digestsize
 942 !Finclude/crypto/hash.h crypto_shash_descsize
 943 !Finclude/crypto/hash.h crypto_shash_setkey
 944 !Finclude/crypto/hash.h crypto_shash_digest
 945 !Finclude/crypto/hash.h crypto_shash_export
 946 !Finclude/crypto/hash.h crypto_shash_import
 947 !Finclude/crypto/hash.h crypto_shash_init
 948 !Finclude/crypto/hash.h crypto_shash_update
 949 !Finclude/crypto/hash.h crypto_shash_final
 950 !Finclude/crypto/hash.h crypto_shash_finup
 951    </sect1>
 952    <sect1><title>Crypto API Random Number API</title>
 953 !Pinclude/crypto/rng.h Random number generator API
 954 !Finclude/crypto/rng.h crypto_alloc_rng
 955 !Finclude/crypto/rng.h crypto_rng_alg
 956 !Finclude/crypto/rng.h crypto_free_rng
 957 !Finclude/crypto/rng.h crypto_rng_get_bytes
 958 !Finclude/crypto/rng.h crypto_rng_reset
 959 !Finclude/crypto/rng.h crypto_rng_seedsize
 960 !Cinclude/crypto/rng.h
 961    </sect1>
 962   </chapter>
 963
 964   <chapter id="Code"><title>Code Examples</title>
 965    <sect1><title>Code Example For Asynchronous Block Cipher Operation</title>
 966     <programlisting>
 967
 968 struct tcrypt_result {
 969         struct completion completion;
 970         int err;
 971 };
 972
 973 /* tie all data structures together */
 974 struct ablkcipher_def {
 975         struct scatterlist sg;
 976         struct crypto_ablkcipher *tfm;
 977         struct ablkcipher_request *req;
 978         struct tcrypt_result result;
 979 };
 980
 981 /* Callback function */
 982 static void test_ablkcipher_cb(struct crypto_async_request *req, int error)
 983 {
 984         struct tcrypt_result *result = req-&gt;data;
 985
 986         if (error == -EINPROGRESS)
 987                 return;
 988         result-&gt;err = error;
 989         complete(&amp;result-&gt;completion);
 990         pr_info("Encryption finished successfully\n");
 991 }
 992
 993 /* Perform cipher operation */
 994 static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk,
 995                                            int enc)
 996 {
 997         int rc = 0;
 998
 999         if (enc)
1000                 rc = crypto_ablkcipher_encrypt(ablk-&gt;req);
1001         else
1002                 rc = crypto_ablkcipher_decrypt(ablk-&gt;req);
1003
1004         switch (rc) {
1005         case 0:
1006                 break;
1007         case -EINPROGRESS:
1008         case -EBUSY:
1009                 rc = wait_for_completion_interruptible(
1010                         &amp;ablk-&gt;result.completion);
1011                 if (!rc &amp;&amp; !ablk-&gt;result.err) {
1012                         reinit_completion(&amp;ablk-&gt;result.completion);
1013                         break;
1014                 }
1015         default:
1016                 pr_info("ablkcipher encrypt returned with %d result %d\n",
1017                        rc, ablk-&gt;result.err);
1018                 break;
1019         }
1020         init_completion(&amp;ablk-&gt;result.completion);
1021
1022         return rc;
1023 }
1024
1025 /* Initialize and trigger cipher operation */
1026 static int test_ablkcipher(void)
1027 {
1028         struct ablkcipher_def ablk;
1029         struct crypto_ablkcipher *ablkcipher = NULL;
1030         struct ablkcipher_request *req = NULL;
1031         char *scratchpad = NULL;
1032         char *ivdata = NULL;
1033         unsigned char key[32];
1034         int ret = -EFAULT;
1035
1036         ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0);
1037         if (IS_ERR(ablkcipher)) {
1038                 pr_info("could not allocate ablkcipher handle\n");
1039                 return PTR_ERR(ablkcipher);
1040         }
1041
1042         req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL);
1043         if (IS_ERR(req)) {
1044                 pr_info("could not allocate request queue\n");
1045                 ret = PTR_ERR(req);
1046                 goto out;
1047         }
1048
1049         ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG,
1050                                         test_ablkcipher_cb,
1051                                         &amp;ablk.result);
1052
1053         /* AES 256 with random key */
1054         get_random_bytes(&amp;key, 32);
1055         if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) {
1056                 pr_info("key could not be set\n");
1057                 ret = -EAGAIN;
1058                 goto out;
1059         }
1060
1061         /* IV will be random */
1062         ivdata = kmalloc(16, GFP_KERNEL);
1063         if (!ivdata) {
1064                 pr_info("could not allocate ivdata\n");
1065                 goto out;
1066         }
1067         get_random_bytes(ivdata, 16);
1068
1069         /* Input data will be random */
1070         scratchpad = kmalloc(16, GFP_KERNEL);
1071         if (!scratchpad) {
1072                 pr_info("could not allocate scratchpad\n");
1073                 goto out;
1074         }
1075         get_random_bytes(scratchpad, 16);
1076
1077         ablk.tfm = ablkcipher;
1078         ablk.req = req;
1079
1080         /* We encrypt one block */
1081         sg_init_one(&amp;ablk.sg, scratchpad, 16);
1082         ablkcipher_request_set_crypt(req, &amp;ablk.sg, &amp;ablk.sg, 16, ivdata);
1083         init_completion(&amp;ablk.result.completion);
1084
1085         /* encrypt data */
1086         ret = test_ablkcipher_encdec(&amp;ablk, 1);
1087         if (ret)
1088                 goto out;
1089
1090         pr_info("Encryption triggered successfully\n");
1091
1092 out:
1093         if (ablkcipher)
1094                 crypto_free_ablkcipher(ablkcipher);
1095         if (req)
1096                 ablkcipher_request_free(req);
1097         if (ivdata)
1098                 kfree(ivdata);
1099         if (scratchpad)
1100                 kfree(scratchpad);
1101         return ret;
1102 }
1103     </programlisting>
1104    </sect1>
1105
1106    <sect1><title>Code Example For Synchronous Block Cipher Operation</title>
1107     <programlisting>
1108
1109 static int test_blkcipher(void)
1110 {
1111         struct crypto_blkcipher *blkcipher = NULL;
1112         char *cipher = "cbc(aes)";
1113         // AES 128
1114         charkey =
1115 "\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef";
1116         chariv =
1117 "\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef";
1118         unsigned int ivsize = 0;
1119         char *scratchpad = NULL; // holds plaintext and ciphertext
1120         struct scatterlist sg;
1121         struct blkcipher_desc desc;
1122         int ret = -EFAULT;
1123
1124         blkcipher = crypto_alloc_blkcipher(cipher, 0, 0);
1125         if (IS_ERR(blkcipher)) {
1126                 printk("could not allocate blkcipher handle for %s\n", cipher);
1127                 return -PTR_ERR(blkcipher);
1128         }
1129
1130         if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) {
1131                 printk("key could not be set\n");
1132                 ret = -EAGAIN;
1133                 goto out;
1134         }
1135
1136         ivsize = crypto_blkcipher_ivsize(blkcipher);
1137         if (ivsize) {
1138                 if (ivsize != strlen(iv))
1139                         printk("IV length differs from expected length\n");
1140                 crypto_blkcipher_set_iv(blkcipher, iv, ivsize);
1141         }
1142
1143         scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL);
1144         if (!scratchpad) {
1145                 printk("could not allocate scratchpad for %s\n", cipher);
1146                 goto out;
1147         }
1148         /* get some random data that we want to encrypt */
1149         get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher));
1150
1151         desc.flags = 0;
1152         desc.tfm = blkcipher;
1153         sg_init_one(&amp;sg, scratchpad, crypto_blkcipher_blocksize(blkcipher));
1154
1155         /* encrypt data in place */
1156         crypto_blkcipher_encrypt(&amp;desc, &amp;sg, &amp;sg,
1157                                  crypto_blkcipher_blocksize(blkcipher));
1158
1159         /* decrypt data in place
1160          * crypto_blkcipher_decrypt(&amp;desc, &amp;sg, &amp;sg,
1161          */                      crypto_blkcipher_blocksize(blkcipher));
1162
1163
1164         printk("Cipher operation completed\n");
1165         return 0;
1166
1167 out:
1168         if (blkcipher)
1169                 crypto_free_blkcipher(blkcipher);
1170         if (scratchpad)
1171                 kzfree(scratchpad);
1172         return ret;
1173 }
1174     </programlisting>
1175    </sect1>
1176
1177    <sect1><title>Code Example For Use of Operational State Memory With SHASH</title>
1178     <programlisting>
1179
1180 struct sdesc {
1181         struct shash_desc shash;
1182         char ctx[];
1183 };
1184
1185 static struct sdescinit_sdesc(struct crypto_shash *alg)
1186 {
1187         struct sdescsdesc;
1188         int size;
1189
1190         size = sizeof(struct shash_desc) + crypto_shash_descsize(alg);
1191         sdesc = kmalloc(size, GFP_KERNEL);
1192         if (!sdesc)
1193                 return ERR_PTR(-ENOMEM);
1194         sdesc-&gt;shash.tfm = alg;
1195         sdesc-&gt;shash.flags = 0x0;
1196         return sdesc;
1197 }
1198
1199 static int calc_hash(struct crypto_shashalg,
1200                      const unsigned chardata, unsigned int datalen,
1201                      unsigned chardigest) {
1202         struct sdescsdesc;
1203         int ret;
1204
1205         sdesc = init_sdesc(alg);
1206         if (IS_ERR(sdesc)) {
1207                 pr_info("trusted_key: can't alloc %s\n", hash_alg);
1208                 return PTR_ERR(sdesc);
1209         }
1210
1211         ret = crypto_shash_digest(&amp;sdesc-&gt;shash, data, datalen, digest);
1212         kfree(sdesc);
1213         return ret;
1214 }
1215     </programlisting>
1216    </sect1>
1217
1218    <sect1><title>Code Example For Random Number Generator Usage</title>
1219     <programlisting>
1220
1221 static int get_random_numbers(u8 *buf, unsigned int len)
1222 {
1223         struct crypto_rngrng = NULL;
1224         chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */
1225         int ret;
1226
1227         if (!buf || !len) {
1228                 pr_debug("No output buffer provided\n");
1229                 return -EINVAL;
1230         }
1231
1232         rng = crypto_alloc_rng(drbg, 0, 0);
1233         if (IS_ERR(rng)) {
1234                 pr_debug("could not allocate RNG handle for %s\n", drbg);
1235                 return -PTR_ERR(rng);
1236         }
1237
1238         ret = crypto_rng_get_bytes(rng, buf, len);
1239         if (ret &lt; 0)
1240                 pr_debug("generation of random numbers failed\n");
1241         else if (ret == 0)
1242                 pr_debug("RNG returned no data");
1243         else
1244                 pr_debug("RNG returned %d bytes of data\n", ret);
1245
1246 out:
1247         crypto_free_rng(rng);
1248         return ret;
1249 }
1250     </programlisting>
1251    </sect1>
1252   </chapter>
1253  </book>