1 Kernel Crypto API Architecture
2 ==============================
7 The kernel crypto API provides different API calls for the following
14 - Message digest, including keyed message digest
16 - Random number generation
18 - User space interface
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.
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.
33 A single block cipher may even be called with multiple templates.
34 However, templates cannot be used without a single cipher.
36 See /proc/crypto and search for "name". For example:
52 - authenc(hmac(sha1),cbc(aes))
54 In these examples, "aes" and "sha1" are the ciphers and all others are
57 Synchronous And Asynchronous Operation
58 --------------------------------------
60 The kernel crypto API provides synchronous and asynchronous API
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.
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
81 Crypto API Cipher References And Priority
82 -----------------------------------------
84 A cipher is referenced by the caller with a string. That string has the
89 template(single block cipher)
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
98 template1(template2(single block cipher)))
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.
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.
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:
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
130 - driver: the unique name of the cipher -- this name can be used by the
131 cipher allocation API calls
133 - module: the kernel module providing the cipher implementation (or
134 "kernel" for statically linked ciphers)
136 - priority: the priority value of the cipher implementation
138 - refcnt: the reference count of the respective cipher (i.e. the number
139 of current consumers of this cipher)
141 - selftest: specification whether the self test for the cipher passed
145 - skcipher for symmetric key ciphers
147 - cipher for single block ciphers that may be used with an
150 - shash for synchronous message digest
152 - ahash for asynchronous message digest
154 - aead for AEAD cipher type
156 - compression for compression type transformations
158 - rng for random number generator
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)
164 - blocksize: blocksize of cipher in bytes
166 - keysize: key size in bytes
168 - ivsize: IV size in bytes
170 - seedsize: required size of seed data for random number generator
172 - digestsize: output size of the message digest
174 - geniv: IV generation type:
176 - eseqiv for encrypted sequence number based IV generation
178 - seqiv for sequence number based IV generation
180 - chainiv for chain iv generation
182 - <builtin> is a marker that the cipher implements IV generation and
183 handling as it is specific to the given cipher
188 When allocating a cipher handle, the caller only specifies the cipher
189 type. Symmetric ciphers, however, typically support multiple key sizes
190 (e.g. AES-128 vs. AES-192 vs. AES-256). These key sizes are determined
191 with the length of the provided key. Thus, the kernel crypto API does
192 not provide a separate way to select the particular symmetric cipher key
195 Cipher Allocation Type And Masks
196 --------------------------------
198 The different cipher handle allocation functions allow the specification
199 of a type and mask flag. Both parameters have the following meaning (and
200 are therefore not covered in the subsequent sections).
202 The type flag specifies the type of the cipher algorithm. The caller
203 usually provides a 0 when the caller wants the default handling.
204 Otherwise, the caller may provide the following selections which match
205 the aforementioned cipher types:
207 - CRYPTO_ALG_TYPE_CIPHER Single block cipher
209 - CRYPTO_ALG_TYPE_COMPRESS Compression
211 - CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with Associated Data
214 - CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher
216 - CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher
218 - CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block cipher packed
219 together with an IV generator (see geniv field in the /proc/crypto
220 listing for the known IV generators)
222 - CRYPTO_ALG_TYPE_DIGEST Raw message digest
224 - CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST
226 - CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash
228 - CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash
230 - CRYPTO_ALG_TYPE_RNG Random Number Generation
232 - CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher
234 - CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of
235 CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression /
236 decompression instead of performing the operation on one segment
237 only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace
238 CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.
240 The mask flag restricts the type of cipher. The only allowed flag is
241 CRYPTO_ALG_ASYNC to restrict the cipher lookup function to
242 asynchronous ciphers. Usually, a caller provides a 0 for the mask flag.
244 When the caller provides a mask and type specification, the caller
245 limits the search the kernel crypto API can perform for a suitable
246 cipher implementation for the given cipher name. That means, even when a
247 caller uses a cipher name that exists during its initialization call,
248 the kernel crypto API may not select it due to the used type and mask
251 Internal Structure of Kernel Crypto API
252 ---------------------------------------
254 The kernel crypto API has an internal structure where a cipher
255 implementation may use many layers and indirections. This section shall
256 help to clarify how the kernel crypto API uses various components to
257 implement the complete cipher.
259 The following subsections explain the internal structure based on
260 existing cipher implementations. The first section addresses the most
261 complex scenario where all other scenarios form a logical subset.
263 Generic AEAD Cipher Structure
264 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
266 The following ASCII art decomposes the kernel crypto API layers when
267 using the AEAD cipher with the automated IV generation. The shown
268 example is used by the IPSEC layer.
270 For other use cases of AEAD ciphers, the ASCII art applies as well, but
271 the caller may not use the AEAD cipher with a separate IV generator. In
272 this case, the caller must generate the IV.
274 The depicted example decomposes the AEAD cipher of GCM(AES) based on the
275 generic C implementations (gcm.c, aes-generic.c, ctr.c, ghash-generic.c,
276 seqiv.c). The generic implementation serves as an example showing the
277 complete logic of the kernel crypto API.
279 It is possible that some streamlined cipher implementations (like
280 AES-NI) provide implementations merging aspects which in the view of the
281 kernel crypto API cannot be decomposed into layers any more. In case of
282 the AES-NI implementation, the CTR mode, the GHASH implementation and
283 the AES cipher are all merged into one cipher implementation registered
284 with the kernel crypto API. In this case, the concept described by the
285 following ASCII art applies too. However, the decomposition of GCM into
286 the individual sub-components by the kernel crypto API is not done any
289 Each block in the following ASCII art is an independent cipher instance
290 obtained from the kernel crypto API. Each block is accessed by the
291 caller or by other blocks using the API functions defined by the kernel
292 crypto API for the cipher implementation type.
294 The blocks below indicate the cipher type as well as the specific logic
295 implemented in the cipher.
297 The ASCII art picture also indicates the call structure, i.e. who calls
298 which component. The arrows point to the invoked block where the caller
299 uses the API applicable to the cipher type specified for the block.
304 kernel crypto API | IPSEC Layer
308 | aead | <----------------------------------- esp_output
314 | aead | <----------------------------------- esp_input
315 | (gcm) | ------------+
319 +-----------+ +-----------+
321 | skcipher | | ahash |
322 | (ctr) | ---+ | (ghash) |
323 +-----------+ | +-----------+
333 The following call sequence is applicable when the IPSEC layer triggers
334 an encryption operation with the esp_output function. During
335 configuration, the administrator set up the use of rfc4106(gcm(aes)) as
336 the cipher for ESP. The following call sequence is now depicted in the
339 1. esp_output() invokes crypto_aead_encrypt() to trigger an
340 encryption operation of the AEAD cipher with IV generator.
342 In case of GCM, the SEQIV implementation is registered as GIVCIPHER
343 in crypto_rfc4106_alloc().
345 The SEQIV performs its operation to generate an IV where the core
346 function is seqiv_geniv().
348 2. Now, SEQIV uses the AEAD API function calls to invoke the associated
349 AEAD cipher. In our case, during the instantiation of SEQIV, the
350 cipher handle for GCM is provided to SEQIV. This means that SEQIV
351 invokes AEAD cipher operations with the GCM cipher handle.
353 During instantiation of the GCM handle, the CTR(AES) and GHASH
354 ciphers are instantiated. The cipher handles for CTR(AES) and GHASH
355 are retained for later use.
357 The GCM implementation is responsible to invoke the CTR mode AES and
358 the GHASH cipher in the right manner to implement the GCM
361 3. The GCM AEAD cipher type implementation now invokes the SKCIPHER API
362 with the instantiated CTR(AES) cipher handle.
364 During instantiation of the CTR(AES) cipher, the CIPHER type
365 implementation of AES is instantiated. The cipher handle for AES is
368 That means that the SKCIPHER implementation of CTR(AES) only
369 implements the CTR block chaining mode. After performing the block
370 chaining operation, the CIPHER implementation of AES is invoked.
372 4. The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES
373 cipher handle to encrypt one block.
375 5. The GCM AEAD implementation also invokes the GHASH cipher
376 implementation via the AHASH API.
378 When the IPSEC layer triggers the esp_input() function, the same call
379 sequence is followed with the only difference that the operation starts
382 Generic Block Cipher Structure
383 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
385 Generic block ciphers follow the same concept as depicted with the ASCII
388 For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The
389 ASCII art picture above applies as well with the difference that only
390 step (4) is used and the SKCIPHER block chaining mode is CBC.
392 Generic Keyed Message Digest Structure
393 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
395 Keyed message digest implementations again follow the same concept as
396 depicted in the ASCII art picture above.
398 For example, HMAC(SHA256) is implemented with hmac.c and
399 sha256_generic.c. The following ASCII art illustrates the
405 kernel crypto API | Caller
408 | | <------------------ some_function
421 The following call sequence is applicable when a caller triggers an HMAC
424 1. The AHASH API functions are invoked by the caller. The HMAC
425 implementation performs its operation as needed.
427 During initialization of the HMAC cipher, the SHASH cipher type of
428 SHA256 is instantiated. The cipher handle for the SHA256 instance is
431 At one time, the HMAC implementation requires a SHA256 operation
432 where the SHA256 cipher handle is used.
434 2. The HMAC instance now invokes the SHASH API with the SHA256 cipher
435 handle to calculate the message digest.