1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Internal Structure of Kernel Crypto API</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="ch02s06.html" title="Cipher Allocation Type And Masks"><link rel="next" href="Development.html" title="Chapter 3. Developing Cipher Algorithms"></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">Internal Structure of Kernel Crypto API</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s06.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="Development.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1094419548"></a>Internal Structure of Kernel Crypto API</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ch02s07.html#idp1094420740">Generic AEAD Cipher Structure</a></span></dt><dt><span class="sect2"><a href="ch02s07.html#idp1094433436">Generic Block Cipher Structure</a></span></dt><dt><span class="sect2"><a href="ch02s07.html#idp1094434500">Generic Keyed Message Digest Structure</a></span></dt></dl></div><p> 2 The kernel crypto API has an internal structure where a cipher 3 implementation may use many layers and indirections. This section 4 shall help to clarify how the kernel crypto API uses 5 various components to implement the complete cipher. 6 </p><p> 7 The following subsections explain the internal structure based 8 on existing cipher implementations. The first section addresses 9 the most complex scenario where all other scenarios form a logical 10 subset. 11 </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1094420740"></a>Generic AEAD Cipher Structure</h3></div></div></div><p> 12 The following ASCII art decomposes the kernel crypto API layers 13 when using the AEAD cipher with the automated IV generation. The 14 shown example is used by the IPSEC layer. 15 </p><p> 16 For other use cases of AEAD ciphers, the ASCII art applies as 17 well, but the caller may not use the GIVCIPHER interface. In 18 this case, the caller must generate the IV. 19 </p><p> 20 The depicted example decomposes the AEAD cipher of GCM(AES) based 21 on the generic C implementations (gcm.c, aes-generic.c, ctr.c, 22 ghash-generic.c, seqiv.c). The generic implementation serves as an 23 example showing the complete logic of the kernel crypto API. 24 </p><p> 25 It is possible that some streamlined cipher implementations (like 26 AES-NI) provide implementations merging aspects which in the view 27 of the kernel crypto API cannot be decomposed into layers any more. 28 In case of the AES-NI implementation, the CTR mode, the GHASH 29 implementation and the AES cipher are all merged into one cipher 30 implementation registered with the kernel crypto API. In this case, 31 the concept described by the following ASCII art applies too. However, 32 the decomposition of GCM into the individual sub-components 33 by the kernel crypto API is not done any more. 34 </p><p> 35 Each block in the following ASCII art is an independent cipher 36 instance obtained from the kernel crypto API. Each block 37 is accessed by the caller or by other blocks using the API functions 38 defined by the kernel crypto API for the cipher implementation type. 39 </p><p> 40 The blocks below indicate the cipher type as well as the specific 41 logic implemented in the cipher. 42 </p><p> 43 The ASCII art picture also indicates the call structure, i.e. who 44 calls which component. The arrows point to the invoked block 45 where the caller uses the API applicable to the cipher type 46 specified for the block. 47 </p><pre class="programlisting"> 48 49kernel crypto API | IPSEC Layer 50 | 51+-----------+ | 52| | (1) 53| givcipher | <----------------------------------- esp_output 54| (seqiv) | ---+ 55+-----------+ | 56 | (2) 57+-----------+ | 58| | <--+ (2) 59| aead | <----------------------------------- esp_input 60| (gcm) | ------------+ 61+-----------+ | 62 | (3) | (5) 63 v v 64+-----------+ +-----------+ 65| | | | 66| ablkcipher| | ahash | 67| (ctr) | ---+ | (ghash) | 68+-----------+ | +-----------+ 69 | 70+-----------+ | (4) 71| | <--+ 72| cipher | 73| (aes) | 74+-----------+ 75 76 </pre><p> 77 The following call sequence is applicable when the IPSEC layer 78 triggers an encryption operation with the esp_output function. During 79 configuration, the administrator set up the use of rfc4106(gcm(aes)) as 80 the cipher for ESP. The following call sequence is now depicted in the 81 ASCII art above: 82 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> 83 esp_output() invokes crypto_aead_givencrypt() to trigger an encryption 84 operation of the GIVCIPHER implementation. 85 </p><p> 86 In case of GCM, the SEQIV implementation is registered as GIVCIPHER 87 in crypto_rfc4106_alloc(). 88 </p><p> 89 The SEQIV performs its operation to generate an IV where the core 90 function is seqiv_geniv(). 91 </p></li><li class="listitem"><p> 92 Now, SEQIV uses the AEAD API function calls to invoke the associated 93 AEAD cipher. In our case, during the instantiation of SEQIV, the 94 cipher handle for GCM is provided to SEQIV. This means that SEQIV 95 invokes AEAD cipher operations with the GCM cipher handle. 96 </p><p> 97 During instantiation of the GCM handle, the CTR(AES) and GHASH 98 ciphers are instantiated. The cipher handles for CTR(AES) and GHASH 99 are retained for later use. 100 </p><p> 101 The GCM implementation is responsible to invoke the CTR mode AES and 102 the GHASH cipher in the right manner to implement the GCM 103 specification. 104 </p></li><li class="listitem"><p> 105 The GCM AEAD cipher type implementation now invokes the ABLKCIPHER API 106 with the instantiated CTR(AES) cipher handle. 107 </p><p> 108 During instantiation of the CTR(AES) cipher, the CIPHER type 109 implementation of AES is instantiated. The cipher handle for AES is 110 retained. 111 </p><p> 112 That means that the ABLKCIPHER implementation of CTR(AES) only 113 implements the CTR block chaining mode. After performing the block 114 chaining operation, the CIPHER implementation of AES is invoked. 115 </p></li><li class="listitem"><p> 116 The ABLKCIPHER of CTR(AES) now invokes the CIPHER API with the AES 117 cipher handle to encrypt one block. 118 </p></li><li class="listitem"><p> 119 The GCM AEAD implementation also invokes the GHASH cipher 120 implementation via the AHASH API. 121 </p></li></ol></div><p> 122 When the IPSEC layer triggers the esp_input() function, the same call 123 sequence is followed with the only difference that the operation starts 124 with step (2). 125 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1094433436"></a>Generic Block Cipher Structure</h3></div></div></div><p> 126 Generic block ciphers follow the same concept as depicted with the ASCII 127 art picture above. 128 </p><p> 129 For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The 130 ASCII art picture above applies as well with the difference that only 131 step (4) is used and the ABLKCIPHER block chaining mode is CBC. 132 </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1094434500"></a>Generic Keyed Message Digest Structure</h3></div></div></div><p> 133 Keyed message digest implementations again follow the same concept as 134 depicted in the ASCII art picture above. 135 </p><p> 136 For example, HMAC(SHA256) is implemented with hmac.c and 137 sha256_generic.c. The following ASCII art illustrates the 138 implementation: 139 </p><pre class="programlisting"> 140 141kernel crypto API | Caller 142 | 143+-----------+ (1) | 144| | <------------------ some_function 145| ahash | 146| (hmac) | ---+ 147+-----------+ | 148 | (2) 149+-----------+ | 150| | <--+ 151| shash | 152| (sha256) | 153+-----------+ 154 155 </pre><p> 156 The following call sequence is applicable when a caller triggers 157 an HMAC operation: 158 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> 159 The AHASH API functions are invoked by the caller. The HMAC 160 implementation performs its operation as needed. 161 </p><p> 162 During initialization of the HMAC cipher, the SHASH cipher type of 163 SHA256 is instantiated. The cipher handle for the SHA256 instance is 164 retained. 165 </p><p> 166 At one time, the HMAC implementation requires a SHA256 operation 167 where the SHA256 cipher handle is used. 168 </p></li><li class="listitem"><p> 169 The HMAC instance now invokes the SHASH API with the SHA256 170 cipher handle to calculate the message digest. 171 </p></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s06.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="Development.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Cipher Allocation Type And Masks </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Developing Cipher Algorithms</td></tr></table></div></body></html> 172