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