415 lines · plain
1Kernel Crypto API Architecture2==============================3 4Cipher algorithm types5----------------------6 7The kernel crypto API provides different API calls for the following8cipher types:9 10- Symmetric ciphers11 12- AEAD ciphers13 14- Message digest, including keyed message digest15 16- Random number generation17 18- User space interface19 20Ciphers And Templates21---------------------22 23The kernel crypto API provides implementations of single block ciphers24and message digests. In addition, the kernel crypto API provides25numerous "templates" that can be used in conjunction with the single26block ciphers and message digests. Templates include all types of block27chaining mode, the HMAC mechanism, etc.28 29Single block ciphers and message digests can either be directly used by30a caller or invoked together with a template to form multi-block ciphers31or 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- aes39 40- ecb(aes)41 42- cmac(aes)43 44- ccm(aes)45 46- rfc4106(gcm(aes))47 48- sha149 50- hmac(sha1)51 52- authenc(hmac(sha1),cbc(aes))53 54In these examples, "aes" and "sha1" are the ciphers and all others are55the templates.56 57Synchronous And Asynchronous Operation58--------------------------------------59 60The kernel crypto API provides synchronous and asynchronous API61operations.62 63When using the synchronous API operation, the caller invokes a cipher64operation 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 and68conceptually similar to any other crypto library.69 70Asynchronous operation is provided by the kernel crypto API which71implies that the invocation of a cipher operation will complete almost72instantly. That invocation triggers the cipher operation but it does not73signal its completion. Before invoking a cipher operation, the caller74must provide a callback function the kernel crypto API can invoke to75signal the completion of the cipher operation. Furthermore, the caller76must ensure it can handle such asynchronous events by applying77appropriate locking around its data. The kernel crypto API does not78perform any special serialization operation to protect the caller's data79integrity.80 81Crypto API Cipher References And Priority82-----------------------------------------83 84A cipher is referenced by the caller with a string. That string has the85following semantics:86 87::88 89 template(single block cipher)90 91 92where "template" and "single block cipher" is the aforementioned93template and single block cipher, respectively. If applicable,94additional templates may enclose other templates, such as95 96::97 98 template1(template2(single block cipher)))99 100 101The kernel crypto API may provide multiple implementations of a template102or a single block cipher. For example, AES on newer Intel hardware has103the following implementations: AES-NI, assembler implementation, or104straight C. Now, when using the string "aes" with the kernel crypto API,105which cipher implementation is used? The answer to that question is the106priority number assigned to each cipher implementation by the kernel107crypto API. When a caller uses the string to refer to a cipher during108initialization of a cipher handle, the kernel crypto API looks up all109implementations providing an implementation with that name and selects110the implementation with the highest priority.111 112Now, a caller may have the need to refer to a specific cipher113implementation and thus does not want to rely on the priority-based114selection. To accommodate this scenario, the kernel crypto API allows115the cipher implementation to register a unique name in addition to116common names. When using that unique name, a caller is therefore always117sure to refer to the intended cipher implementation.118 119The list of available ciphers is given in /proc/crypto. However, that120list does not specify all possible permutations of templates and121ciphers. Each block listed in /proc/crypto may contain the following122information -- if one of the components listed as follows are not123applicable to a cipher, it is not displayed:124 125- name: the generic name of the cipher that is subject to the126 priority-based selection -- this name can be used by the cipher127 allocation API calls (all names listed above are examples for such128 generic names)129 130- driver: the unique name of the cipher -- this name can be used by the131 cipher allocation API calls132 133- module: the kernel module providing the cipher implementation (or134 "kernel" for statically linked ciphers)135 136- priority: the priority value of the cipher implementation137 138- refcnt: the reference count of the respective cipher (i.e. the number139 of current consumers of this cipher)140 141- selftest: specification whether the self test for the cipher passed142 143- type:144 145 - skcipher for symmetric key ciphers146 147 - cipher for single block ciphers that may be used with an148 additional template149 150 - shash for synchronous message digest151 152 - ahash for asynchronous message digest153 154 - aead for AEAD cipher type155 156 - compression for compression type transformations157 158 - rng for random number generator159 160 - kpp for a Key-agreement Protocol Primitive (KPP) cipher such as161 an ECDH or DH implementation162 163- blocksize: blocksize of cipher in bytes164 165- keysize: key size in bytes166 167- ivsize: IV size in bytes168 169- seedsize: required size of seed data for random number generator170 171- digestsize: output size of the message digest172 173- geniv: IV generator (obsolete)174 175Key Sizes176---------177 178When allocating a cipher handle, the caller only specifies the cipher179type. Symmetric ciphers, however, typically support multiple key sizes180(e.g. AES-128 vs. AES-192 vs. AES-256). These key sizes are determined181with the length of the provided key. Thus, the kernel crypto API does182not provide a separate way to select the particular symmetric cipher key183size.184 185Cipher Allocation Type And Masks186--------------------------------187 188The different cipher handle allocation functions allow the specification189of a type and mask flag. Both parameters have the following meaning (and190are therefore not covered in the subsequent sections).191 192The type flag specifies the type of the cipher algorithm. The caller193usually provides a 0 when the caller wants the default handling.194Otherwise, the caller may provide the following selections which match195the aforementioned cipher types:196 197- CRYPTO_ALG_TYPE_CIPHER Single block cipher198 199- CRYPTO_ALG_TYPE_COMPRESS Compression200 201- CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with Associated Data202 (MAC)203 204- CRYPTO_ALG_TYPE_KPP Key-agreement Protocol Primitive (KPP) such as205 an ECDH or DH implementation206 207- CRYPTO_ALG_TYPE_HASH Raw message digest208 209- CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash210 211- CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash212 213- CRYPTO_ALG_TYPE_RNG Random Number Generation214 215- CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher216 217- CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of218 CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression /219 decompression instead of performing the operation on one segment220 only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace221 CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.222 223The mask flag restricts the type of cipher. The only allowed flag is224CRYPTO_ALG_ASYNC to restrict the cipher lookup function to225asynchronous ciphers. Usually, a caller provides a 0 for the mask flag.226 227When the caller provides a mask and type specification, the caller228limits the search the kernel crypto API can perform for a suitable229cipher implementation for the given cipher name. That means, even when a230caller uses a cipher name that exists during its initialization call,231the kernel crypto API may not select it due to the used type and mask232field.233 234Internal Structure of Kernel Crypto API235---------------------------------------236 237The kernel crypto API has an internal structure where a cipher238implementation may use many layers and indirections. This section shall239help to clarify how the kernel crypto API uses various components to240implement the complete cipher.241 242The following subsections explain the internal structure based on243existing cipher implementations. The first section addresses the most244complex scenario where all other scenarios form a logical subset.245 246Generic AEAD Cipher Structure247~~~~~~~~~~~~~~~~~~~~~~~~~~~~~248 249The following ASCII art decomposes the kernel crypto API layers when250using the AEAD cipher with the automated IV generation. The shown251example is used by the IPSEC layer.252 253For other use cases of AEAD ciphers, the ASCII art applies as well, but254the caller may not use the AEAD cipher with a separate IV generator. In255this case, the caller must generate the IV.256 257The depicted example decomposes the AEAD cipher of GCM(AES) based on the258generic C implementations (gcm.c, aes-generic.c, ctr.c, ghash-generic.c,259seqiv.c). The generic implementation serves as an example showing the260complete logic of the kernel crypto API.261 262It is possible that some streamlined cipher implementations (like263AES-NI) provide implementations merging aspects which in the view of the264kernel crypto API cannot be decomposed into layers any more. In case of265the AES-NI implementation, the CTR mode, the GHASH implementation and266the AES cipher are all merged into one cipher implementation registered267with the kernel crypto API. In this case, the concept described by the268following ASCII art applies too. However, the decomposition of GCM into269the individual sub-components by the kernel crypto API is not done any270more.271 272Each block in the following ASCII art is an independent cipher instance273obtained from the kernel crypto API. Each block is accessed by the274caller or by other blocks using the API functions defined by the kernel275crypto API for the cipher implementation type.276 277The blocks below indicate the cipher type as well as the specific logic278implemented in the cipher.279 280The ASCII art picture also indicates the call structure, i.e. who calls281which component. The arrows point to the invoked block where the caller282uses the API applicable to the cipher type specified for the block.283 284::285 286 287 kernel crypto API | IPSEC Layer288 |289 +-----------+ |290 | | (1)291 | aead | <----------------------------------- esp_output292 | (seqiv) | ---+293 +-----------+ |294 | (2)295 +-----------+ |296 | | <--+ (2)297 | aead | <----------------------------------- esp_input298 | (gcm) | ------------+299 +-----------+ |300 | (3) | (5)301 v v302 +-----------+ +-----------+303 | | | |304 | skcipher | | ahash |305 | (ctr) | ---+ | (ghash) |306 +-----------+ | +-----------+307 |308 +-----------+ | (4)309 | | <--+310 | cipher |311 | (aes) |312 +-----------+313 314 315 316The following call sequence is applicable when the IPSEC layer triggers317an encryption operation with the esp_output function. During318configuration, the administrator set up the use of seqiv(rfc4106(gcm(aes)))319as the cipher for ESP. The following call sequence is now depicted in320the ASCII art above:321 3221. esp_output() invokes crypto_aead_encrypt() to trigger an323 encryption operation of the AEAD cipher with IV generator.324 325 The SEQIV generates the IV.326 3272. Now, SEQIV uses the AEAD API function calls to invoke the associated328 AEAD cipher. In our case, during the instantiation of SEQIV, the329 cipher handle for GCM is provided to SEQIV. This means that SEQIV330 invokes AEAD cipher operations with the GCM cipher handle.331 332 During instantiation of the GCM handle, the CTR(AES) and GHASH333 ciphers are instantiated. The cipher handles for CTR(AES) and GHASH334 are retained for later use.335 336 The GCM implementation is responsible to invoke the CTR mode AES and337 the GHASH cipher in the right manner to implement the GCM338 specification.339 3403. The GCM AEAD cipher type implementation now invokes the SKCIPHER API341 with the instantiated CTR(AES) cipher handle.342 343 During instantiation of the CTR(AES) cipher, the CIPHER type344 implementation of AES is instantiated. The cipher handle for AES is345 retained.346 347 That means that the SKCIPHER implementation of CTR(AES) only348 implements the CTR block chaining mode. After performing the block349 chaining operation, the CIPHER implementation of AES is invoked.350 3514. The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES352 cipher handle to encrypt one block.353 3545. The GCM AEAD implementation also invokes the GHASH cipher355 implementation via the AHASH API.356 357When the IPSEC layer triggers the esp_input() function, the same call358sequence is followed with the only difference that the operation starts359with step (2).360 361Generic Block Cipher Structure362~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~363 364Generic block ciphers follow the same concept as depicted with the ASCII365art picture above.366 367For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The368ASCII art picture above applies as well with the difference that only369step (4) is used and the SKCIPHER block chaining mode is CBC.370 371Generic Keyed Message Digest Structure372~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~373 374Keyed message digest implementations again follow the same concept as375depicted in the ASCII art picture above.376 377For example, HMAC(SHA256) is implemented with hmac.c and378sha256_generic.c. The following ASCII art illustrates the379implementation:380 381::382 383 384 kernel crypto API | Caller385 |386 +-----------+ (1) |387 | | <------------------ some_function388 | ahash |389 | (hmac) | ---+390 +-----------+ |391 | (2)392 +-----------+ |393 | | <--+394 | shash |395 | (sha256) |396 +-----------+397 398 399 400The following call sequence is applicable when a caller triggers an HMAC401operation:402 4031. The AHASH API functions are invoked by the caller. The HMAC404 implementation performs its operation as needed.405 406 During initialization of the HMAC cipher, the SHASH cipher type of407 SHA256 is instantiated. The cipher handle for the SHA256 instance is408 retained.409 410 At one time, the HMAC implementation requires a SHA256 operation411 where the SHA256 cipher handle is used.412 4132. The HMAC instance now invokes the SHASH API with the SHA256 cipher414 handle to calculate the message digest.415