1 Kernel Crypto API Architecture 2 ============================== 3 4 Cipher algorithm types 5 ---------------------- 6 7 The kernel crypto API provides different API calls for the following 8 cipher types: 9 10 - Symmetric ciphers 11 12 - AEAD ciphers 13 14 - Message digest, including keyed message digest 15 16 - Random number generation 17 18 - User space interface 19 20 Ciphers And Templates 21 --------------------- 22 23 The kernel crypto API provides implementations of single block ciphers 24 and message digests. In addition, the kernel crypto API provides 25 numerous "templates" that can be used in conjunction with the single 26 block ciphers and message digests. Templates include all types of block 27 chaining mode, the HMAC mechanism, etc. 28 29 Single block ciphers and message digests can either be directly used by 30 a caller or invoked together with a template to form multi-block ciphers 31 or keyed message digests. 32 33 A single block cipher may even be called with multiple templates. 34 However, templates cannot be used without a single cipher. 35 36 See /proc/crypto and search for "name". For example: 37 38 - aes 39 40 - ecb(aes) 41 42 - cmac(aes) 43 44 - ccm(aes) 45 46 - rfc4106(gcm(aes)) 47 48 - sha1 49 50 - hmac(sha1) 51 52 - authenc(hmac(sha1),cbc(aes)) 53 54 In these examples, "aes" and "sha1" are the ciphers and all others are 55 the templates. 56 57 Synchronous And Asynchronous Operation 58 -------------------------------------- 59 60 The kernel crypto API provides synchronous and asynchronous API 61 operations. 62 63 When using the synchronous API operation, the caller invokes a cipher 64 operation which is performed synchronously by the kernel crypto API. 65 That means, the caller waits until the cipher operation completes. 66 Therefore, the kernel crypto API calls work like regular function calls. 67 For synchronous operation, the set of API calls is small and 68 conceptually similar to any other crypto library. 69 70 Asynchronous operation is provided by the kernel crypto API which 71 implies that the invocation of a cipher operation will complete almost 72 instantly. That invocation triggers the cipher operation but it does not 73 signal its completion. Before invoking a cipher operation, the caller 74 must provide a callback function the kernel crypto API can invoke to 75 signal the completion of the cipher operation. Furthermore, the caller 76 must ensure it can handle such asynchronous events by applying 77 appropriate locking around its data. The kernel crypto API does not 78 perform any special serialization operation to protect the caller's data 79 integrity. 80 81 Crypto API Cipher References And Priority 82 ----------------------------------------- 83 84 A cipher is referenced by the caller with a string. That string has the 85 following semantics: 86 87 :: 88 89 template(single block cipher) 90 91 92 where "template" and "single block cipher" is the aforementioned 93 template and single block cipher, respectively. If applicable, 94 additional templates may enclose other templates, such as 95 96 :: 97 98 template1(template2(single block cipher))) 99 100 101 The kernel crypto API may provide multiple implementations of a template 102 or a single block cipher. For example, AES on newer Intel hardware has 103 the following implementations: AES-NI, assembler implementation, or 104 straight C. Now, when using the string "aes" with the kernel crypto API, 105 which cipher implementation is used? The answer to that question is the 106 priority number assigned to each cipher implementation by the kernel 107 crypto API. When a caller uses the string to refer to a cipher during 108 initialization of a cipher handle, the kernel crypto API looks up all 109 implementations providing an implementation with that name and selects 110 the implementation with the highest priority. 111 112 Now, a caller may have the need to refer to a specific cipher 113 implementation and thus does not want to rely on the priority-based 114 selection. To accommodate this scenario, the kernel crypto API allows 115 the cipher implementation to register a unique name in addition to 116 common names. When using that unique name, a caller is therefore always 117 sure to refer to the intended cipher implementation. 118 119 The list of available ciphers is given in /proc/crypto. However, that 120 list does not specify all possible permutations of templates and 121 ciphers. Each block listed in /proc/crypto may contain the following 122 information -- if one of the components listed as follows are not 123 applicable to a cipher, it is not displayed: 124 125 - name: the generic name of the cipher that is subject to the 126 priority-based selection -- this name can be used by the cipher 127 allocation API calls (all names listed above are examples for such 128 generic names) 129 130 - driver: the unique name of the cipher -- this name can be used by the 131 cipher allocation API calls 132 133 - module: the kernel module providing the cipher implementation (or 134 "kernel" for statically linked ciphers) 135 136 - priority: the priority value of the cipher implementation 137 138 - refcnt: the reference count of the respective cipher (i.e. the number 139 of current consumers of this cipher) 140 141 - selftest: specification whether the self test for the cipher passed 142 143 - type: 144 145 - skcipher for symmetric key ciphers 146 147 - cipher for single block ciphers that may be used with an 148 additional template 149 150 - shash for synchronous message digest 151 152 - ahash for asynchronous message digest 153 154 - aead for AEAD cipher type 155 156 - compression for compression type transformations 157 158 - rng for random number generator 159 160 - kpp for a Key-agreement Protocol Primitive (KPP) cipher such as 161 an ECDH or DH implementation 162 163 - blocksize: blocksize of cipher in bytes 164 165 - keysize: key size in bytes 166 167 - ivsize: IV size in bytes 168 169 - seedsize: required size of seed data for random number generator 170 171 - digestsize: output size of the message digest 172 173 - geniv: IV generator (obsolete) 174 175 Key Sizes 176 --------- 177 178 When allocating a cipher handle, the caller only specifies the cipher 179 type. Symmetric ciphers, however, typically support multiple key sizes 180 (e.g. AES-128 vs. AES-192 vs. AES-256). These key sizes are determined 181 with the length of the provided key. Thus, the kernel crypto API does 182 not provide a separate way to select the particular symmetric cipher key 183 size. 184 185 Cipher Allocation Type And Masks 186 -------------------------------- 187 188 The different cipher handle allocation functions allow the specification 189 of a type and mask flag. Both parameters have the following meaning (and 190 are therefore not covered in the subsequent sections). 191 192 The type flag specifies the type of the cipher algorithm. The caller 193 usually provides a 0 when the caller wants the default handling. 194 Otherwise, the caller may provide the following selections which match 195 the aforementioned cipher types: 196 197 - CRYPTO_ALG_TYPE_CIPHER Single block cipher 198 199 - CRYPTO_ALG_TYPE_COMPRESS Compression 200 201 - CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with Associated Data 202 (MAC) 203 204 - CRYPTO_ALG_TYPE_KPP Key-agreement Protocol Primitive (KPP) such as 205 an ECDH or DH implementation 206 207 - CRYPTO_ALG_TYPE_HASH Raw message digest 208 209 - CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash 210 211 - CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash 212 213 - CRYPTO_ALG_TYPE_RNG Random Number Generation 214 215 - CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher 216 217 - CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of 218 CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / 219 decompression instead of performing the operation on one segment 220 only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace 221 CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted. 222 223 The mask flag restricts the type of cipher. The only allowed flag is 224 CRYPTO_ALG_ASYNC to restrict the cipher lookup function to 225 asynchronous ciphers. Usually, a caller provides a 0 for the mask flag. 226 227 When the caller provides a mask and type specification, the caller 228 limits the search the kernel crypto API can perform for a suitable 229 cipher implementation for the given cipher name. That means, even when a 230 caller uses a cipher name that exists during its initialization call, 231 the kernel crypto API may not select it due to the used type and mask 232 field. 233 234 Internal Structure of Kernel Crypto API 235 --------------------------------------- 236 237 The kernel crypto API has an internal structure where a cipher 238 implementation may use many layers and indirections. This section shall 239 help to clarify how the kernel crypto API uses various components to 240 implement the complete cipher. 241 242 The following subsections explain the internal structure based on 243 existing cipher implementations. The first section addresses the most 244 complex scenario where all other scenarios form a logical subset. 245 246 Generic AEAD Cipher Structure 247 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 248 249 The following ASCII art decomposes the kernel crypto API layers when 250 using the AEAD cipher with the automated IV generation. The shown 251 example is used by the IPSEC layer. 252 253 For other use cases of AEAD ciphers, the ASCII art applies as well, but 254 the caller may not use the AEAD cipher with a separate IV generator. In 255 this case, the caller must generate the IV. 256 257 The depicted example decomposes the AEAD cipher of GCM(AES) based on the 258 generic C implementations (gcm.c, aes-generic.c, ctr.c, ghash-generic.c, 259 seqiv.c). The generic implementation serves as an example showing the 260 complete logic of the kernel crypto API. 261 262 It is possible that some streamlined cipher implementations (like 263 AES-NI) provide implementations merging aspects which in the view of the 264 kernel crypto API cannot be decomposed into layers any more. In case of 265 the AES-NI implementation, the CTR mode, the GHASH implementation and 266 the AES cipher are all merged into one cipher implementation registered 267 with the kernel crypto API. In this case, the concept described by the 268 following ASCII art applies too. However, the decomposition of GCM into 269 the individual sub-components by the kernel crypto API is not done any 270 more. 271 272 Each block in the following ASCII art is an independent cipher instance 273 obtained from the kernel crypto API. Each block is accessed by the 274 caller or by other blocks using the API functions defined by the kernel 275 crypto API for the cipher implementation type. 276 277 The blocks below indicate the cipher type as well as the specific logic 278 implemented in the cipher. 279 280 The ASCII art picture also indicates the call structure, i.e. who calls 281 which component. The arrows point to the invoked block where the caller 282 uses the API applicable to the cipher type specified for the block. 283 284 :: 285 286 287 kernel crypto API | IPSEC Layer 288 | 289 +-----------+ | 290 | | (1) 291 | aead | <----------------------------------- esp_output 292 | (seqiv) | ---+ 293 +-----------+ | 294 | (2) 295 +-----------+ | 296 | | <--+ (2) 297 | aead | <----------------------------------- esp_input 298 | (gcm) | ------------+ 299 +-----------+ | 300 | (3) | (5) 301 v v 302 +-----------+ +-----------+ 303 | | | | 304 | skcipher | | ahash | 305 | (ctr) | ---+ | (ghash) | 306 +-----------+ | +-----------+ 307 | 308 +-----------+ | (4) 309 | | <--+ 310 | cipher | 311 | (aes) | 312 +-----------+ 313 314 315 316 The following call sequence is applicable when the IPSEC layer triggers 317 an encryption operation with the esp_output function. During 318 configuration, the administrator set up the use of seqiv(rfc4106(gcm(aes))) 319 as the cipher for ESP. The following call sequence is now depicted in 320 the ASCII art above: 321 322 1. esp_output() invokes crypto_aead_encrypt() to trigger an 323 encryption operation of the AEAD cipher with IV generator. 324 325 The SEQIV generates the IV. 326 327 2. Now, SEQIV uses the AEAD API function calls to invoke the associated 328 AEAD cipher. In our case, during the instantiation of SEQIV, the 329 cipher handle for GCM is provided to SEQIV. This means that SEQIV 330 invokes AEAD cipher operations with the GCM cipher handle. 331 332 During instantiation of the GCM handle, the CTR(AES) and GHASH 333 ciphers are instantiated. The cipher handles for CTR(AES) and GHASH 334 are retained for later use. 335 336 The GCM implementation is responsible to invoke the CTR mode AES and 337 the GHASH cipher in the right manner to implement the GCM 338 specification. 339 340 3. The GCM AEAD cipher type implementation now invokes the SKCIPHER API 341 with the instantiated CTR(AES) cipher handle. 342 343 During instantiation of the CTR(AES) cipher, the CIPHER type 344 implementation of AES is instantiated. The cipher handle for AES is 345 retained. 346 347 That means that the SKCIPHER implementation of CTR(AES) only 348 implements the CTR block chaining mode. After performing the block 349 chaining operation, the CIPHER implementation of AES is invoked. 350 351 4. The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES 352 cipher handle to encrypt one block. 353 354 5. The GCM AEAD implementation also invokes the GHASH cipher 355 implementation via the AHASH API. 356 357 When the IPSEC layer triggers the esp_input() function, the same call 358 sequence is followed with the only difference that the operation starts 359 with step (2). 360 361 Generic Block Cipher Structure 362 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 363 364 Generic block ciphers follow the same concept as depicted with the ASCII 365 art picture above. 366 367 For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The 368 ASCII art picture above applies as well with the difference that only 369 step (4) is used and the SKCIPHER block chaining mode is CBC. 370 371 Generic Keyed Message Digest Structure 372 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 373 374 Keyed message digest implementations again follow the same concept as 375 depicted in the ASCII art picture above. 376 377 For example, HMAC(SHA256) is implemented with hmac.c and 378 sha256_generic.c. The following ASCII art illustrates the 379 implementation: 380 381 :: 382 383 384 kernel crypto API | Caller 385 | 386 +-----------+ (1) | 387 | | <------------------ some_function 388 | ahash | 389 | (hmac) | ---+ 390 +-----------+ | 391 | (2) 392 +-----------+ | 393 | | <--+ 394 | shash | 395 | (sha256) | 396 +-----------+ 397 398 399 400 The following call sequence is applicable when a caller triggers an HMAC 401 operation: 402 403 1. The AHASH API functions are invoked by the caller. The HMAC 404 implementation performs its operation as needed. 405 406 During initialization of the HMAC cipher, the SHASH cipher type of 407 SHA256 is instantiated. The cipher handle for the SHA256 instance is 408 retained. 409 410 At one time, the HMAC implementation requires a SHA256 operation 411 where the SHA256 cipher handle is used. 412 413 2. The HMAC instance now invokes the SHASH API with the SHA256 cipher 414 handle to calculate the message digest.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.