Loading...
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 - 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
175Key Sizes
176---------
177
178When allocating a cipher handle, the caller only specifies the cipher
179type. Symmetric ciphers, however, typically support multiple key sizes
180(e.g. AES-128 vs. AES-192 vs. AES-256). These key sizes are determined
181with the length of the provided key. Thus, the kernel crypto API does
182not provide a separate way to select the particular symmetric cipher key
183size.
184
185Cipher Allocation Type And Masks
186--------------------------------
187
188The different cipher handle allocation functions allow the specification
189of a type and mask flag. Both parameters have the following meaning (and
190are therefore not covered in the subsequent sections).
191
192The type flag specifies the type of the cipher algorithm. The caller
193usually provides a 0 when the caller wants the default handling.
194Otherwise, the caller may provide the following selections which match
195the 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_SIG Asymmetric signature
218
219- CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of
220 CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression /
221 decompression instead of performing the operation on one segment
222 only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace
223 CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.
224
225The mask flag restricts the type of cipher. The only allowed flag is
226CRYPTO_ALG_ASYNC to restrict the cipher lookup function to
227asynchronous ciphers. Usually, a caller provides a 0 for the mask flag.
228
229When the caller provides a mask and type specification, the caller
230limits the search the kernel crypto API can perform for a suitable
231cipher implementation for the given cipher name. That means, even when a
232caller uses a cipher name that exists during its initialization call,
233the kernel crypto API may not select it due to the used type and mask
234field.
235
236Internal Structure of Kernel Crypto API
237---------------------------------------
238
239The kernel crypto API has an internal structure where a cipher
240implementation may use many layers and indirections. This section shall
241help to clarify how the kernel crypto API uses various components to
242implement the complete cipher.
243
244The following subsections explain the internal structure based on
245existing cipher implementations. The first section addresses the most
246complex scenario where all other scenarios form a logical subset.
247
248Generic AEAD Cipher Structure
249~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
250
251The following ASCII art decomposes the kernel crypto API layers when
252using the AEAD cipher with the automated IV generation. The shown
253example is used by the IPSEC layer.
254
255For other use cases of AEAD ciphers, the ASCII art applies as well, but
256the caller may not use the AEAD cipher with a separate IV generator. In
257this case, the caller must generate the IV.
258
259The depicted example decomposes the AEAD cipher of GCM(AES) based on the
260generic C implementations (gcm.c, aes-generic.c, ctr.c, ghash-generic.c,
261seqiv.c). The generic implementation serves as an example showing the
262complete logic of the kernel crypto API.
263
264It is possible that some streamlined cipher implementations (like
265AES-NI) provide implementations merging aspects which in the view of the
266kernel crypto API cannot be decomposed into layers any more. In case of
267the AES-NI implementation, the CTR mode, the GHASH implementation and
268the AES cipher are all merged into one cipher implementation registered
269with the kernel crypto API. In this case, the concept described by the
270following ASCII art applies too. However, the decomposition of GCM into
271the individual sub-components by the kernel crypto API is not done any
272more.
273
274Each block in the following ASCII art is an independent cipher instance
275obtained from the kernel crypto API. Each block is accessed by the
276caller or by other blocks using the API functions defined by the kernel
277crypto API for the cipher implementation type.
278
279The blocks below indicate the cipher type as well as the specific logic
280implemented in the cipher.
281
282The ASCII art picture also indicates the call structure, i.e. who calls
283which component. The arrows point to the invoked block where the caller
284uses the API applicable to the cipher type specified for the block.
285
286::
287
288
289 kernel crypto API | IPSEC Layer
290 |
291 +-----------+ |
292 | | (1)
293 | aead | <----------------------------------- esp_output
294 | (seqiv) | ---+
295 +-----------+ |
296 | (2)
297 +-----------+ |
298 | | <--+ (2)
299 | aead | <----------------------------------- esp_input
300 | (gcm) | ------------+
301 +-----------+ |
302 | (3) | (5)
303 v v
304 +-----------+ +-----------+
305 | | | |
306 | skcipher | | ahash |
307 | (ctr) | ---+ | (ghash) |
308 +-----------+ | +-----------+
309 |
310 +-----------+ | (4)
311 | | <--+
312 | cipher |
313 | (aes) |
314 +-----------+
315
316
317
318The following call sequence is applicable when the IPSEC layer triggers
319an encryption operation with the esp_output function. During
320configuration, the administrator set up the use of seqiv(rfc4106(gcm(aes)))
321as the cipher for ESP. The following call sequence is now depicted in
322the ASCII art above:
323
3241. esp_output() invokes crypto_aead_encrypt() to trigger an
325 encryption operation of the AEAD cipher with IV generator.
326
327 The SEQIV generates the IV.
328
3292. Now, SEQIV uses the AEAD API function calls to invoke the associated
330 AEAD cipher. In our case, during the instantiation of SEQIV, the
331 cipher handle for GCM is provided to SEQIV. This means that SEQIV
332 invokes AEAD cipher operations with the GCM cipher handle.
333
334 During instantiation of the GCM handle, the CTR(AES) and GHASH
335 ciphers are instantiated. The cipher handles for CTR(AES) and GHASH
336 are retained for later use.
337
338 The GCM implementation is responsible to invoke the CTR mode AES and
339 the GHASH cipher in the right manner to implement the GCM
340 specification.
341
3423. The GCM AEAD cipher type implementation now invokes the SKCIPHER API
343 with the instantiated CTR(AES) cipher handle.
344
345 During instantiation of the CTR(AES) cipher, the CIPHER type
346 implementation of AES is instantiated. The cipher handle for AES is
347 retained.
348
349 That means that the SKCIPHER implementation of CTR(AES) only
350 implements the CTR block chaining mode. After performing the block
351 chaining operation, the CIPHER implementation of AES is invoked.
352
3534. The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES
354 cipher handle to encrypt one block.
355
3565. The GCM AEAD implementation also invokes the GHASH cipher
357 implementation via the AHASH API.
358
359When the IPSEC layer triggers the esp_input() function, the same call
360sequence is followed with the only difference that the operation starts
361with step (2).
362
363Generic Block Cipher Structure
364~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
365
366Generic block ciphers follow the same concept as depicted with the ASCII
367art picture above.
368
369For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The
370ASCII art picture above applies as well with the difference that only
371step (4) is used and the SKCIPHER block chaining mode is CBC.
372
373Generic Keyed Message Digest Structure
374~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
375
376Keyed message digest implementations again follow the same concept as
377depicted in the ASCII art picture above.
378
379For example, HMAC(SHA256) is implemented with hmac.c and
380sha256_generic.c. The following ASCII art illustrates the
381implementation:
382
383::
384
385
386 kernel crypto API | Caller
387 |
388 +-----------+ (1) |
389 | | <------------------ some_function
390 | ahash |
391 | (hmac) | ---+
392 +-----------+ |
393 | (2)
394 +-----------+ |
395 | | <--+
396 | shash |
397 | (sha256) |
398 +-----------+
399
400
401
402The following call sequence is applicable when a caller triggers an HMAC
403operation:
404
4051. The AHASH API functions are invoked by the caller. The HMAC
406 implementation performs its operation as needed.
407
408 During initialization of the HMAC cipher, the SHASH cipher type of
409 SHA256 is instantiated. The cipher handle for the SHA256 instance is
410 retained.
411
412 At one time, the HMAC implementation requires a SHA256 operation
413 where the SHA256 cipher handle is used.
414
4152. The HMAC instance now invokes the SHASH API with the SHA256 cipher
416 handle to calculate the message digest.
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.