1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Crypto API Cipher References And Priority</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Linux Kernel Crypto API"><link rel="up" href="Architecture.html" title="Chapter 2. Kernel Crypto API Architecture"><link rel="prev" href="ch02s03.html" title="Synchronous And Asynchronous Operation"><link rel="next" href="ch02s05.html" title="Key Sizes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Crypto API Cipher References And Priority</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s03.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Kernel Crypto API Architecture</th><td width="20%" align="right"> <a accesskey="n" href="ch02s05.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1094739612"></a>Crypto API Cipher References And Priority</h2></div></div></div><p> 2 A cipher is referenced by the caller with a string. That string 3 has the following semantics: 4 5 </p><pre class="programlisting"> 6 template(single block cipher) 7 </pre><p> 8 9 where "template" and "single block cipher" is the aforementioned 10 template and single block cipher, respectively. If applicable, 11 additional templates may enclose other templates, such as 12 13 </p><pre class="programlisting"> 14 template1(template2(single block cipher))) 15 </pre><p> 16 </p><p> 17 The kernel crypto API may provide multiple implementations of a 18 template or a single block cipher. For example, AES on newer 19 Intel hardware has the following implementations: AES-NI, 20 assembler implementation, or straight C. Now, when using the 21 string "aes" with the kernel crypto API, which cipher 22 implementation is used? The answer to that question is the 23 priority number assigned to each cipher implementation by the 24 kernel crypto API. When a caller uses the string to refer to a 25 cipher during initialization of a cipher handle, the kernel 26 crypto API looks up all implementations providing an 27 implementation with that name and selects the implementation 28 with the highest priority. 29 </p><p> 30 Now, a caller may have the need to refer to a specific cipher 31 implementation and thus does not want to rely on the 32 priority-based selection. To accommodate this scenario, the 33 kernel crypto API allows the cipher implementation to register 34 a unique name in addition to common names. When using that 35 unique name, a caller is therefore always sure to refer to 36 the intended cipher implementation. 37 </p><p> 38 The list of available ciphers is given in /proc/crypto. However, 39 that list does not specify all possible permutations of 40 templates and ciphers. Each block listed in /proc/crypto may 41 contain the following information -- if one of the components 42 listed as follows are not applicable to a cipher, it is not 43 displayed: 44 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>name: the generic name of the cipher that is subject 45 to the priority-based selection -- this name can be used by 46 the cipher allocation API calls (all names listed above are 47 examples for such generic names)</p></li><li class="listitem"><p>driver: the unique name of the cipher -- this name can 48 be used by the cipher allocation API calls</p></li><li class="listitem"><p>module: the kernel module providing the cipher 49 implementation (or "kernel" for statically linked ciphers)</p></li><li class="listitem"><p>priority: the priority value of the cipher implementation</p></li><li class="listitem"><p>refcnt: the reference count of the respective cipher 50 (i.e. the number of current consumers of this cipher)</p></li><li class="listitem"><p>selftest: specification whether the self test for the 51 cipher passed</p></li><li class="listitem"><p>type: 52 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>blkcipher for synchronous block ciphers</p></li><li class="listitem"><p>ablkcipher for asynchronous block ciphers</p></li><li class="listitem"><p>cipher for single block ciphers that may be used with 53 an additional template</p></li><li class="listitem"><p>shash for synchronous message digest</p></li><li class="listitem"><p>ahash for asynchronous message digest</p></li><li class="listitem"><p>aead for AEAD cipher type</p></li><li class="listitem"><p>compression for compression type transformations</p></li><li class="listitem"><p>rng for random number generator</p></li><li class="listitem"><p>givcipher for cipher with associated IV generator 54 (see the geniv entry below for the specification of the 55 IV generator type used by the cipher implementation)</p></li></ul></div><p> 56 </p></li><li class="listitem"><p>blocksize: blocksize of cipher in bytes</p></li><li class="listitem"><p>keysize: key size in bytes</p></li><li class="listitem"><p>ivsize: IV size in bytes</p></li><li class="listitem"><p>seedsize: required size of seed data for random number 57 generator</p></li><li class="listitem"><p>digestsize: output size of the message digest</p></li><li class="listitem"><p>geniv: IV generation type: 58 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>eseqiv for encrypted sequence number based IV 59 generation</p></li><li class="listitem"><p>seqiv for sequence number based IV generation</p></li><li class="listitem"><p>chainiv for chain iv generation</p></li><li class="listitem"><p><builtin> is a marker that the cipher implements 60 IV generation and handling as it is specific to the given 61 cipher</p></li></ul></div><p> 62 </p></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Architecture.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Synchronous And Asynchronous Operation </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Key Sizes</td></tr></table></div></body></html> 63