Lines Matching refs:the
7 The kernel crypto API provides different API calls for the following
24 and message digests. In addition, the kernel crypto API provides
25 numerous "templates" that can be used in conjunction with the single
27 chaining mode, the HMAC mechanism, etc.
54 In these examples, "aes" and "sha1" are the ciphers and all others are
55 the templates.
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
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
78 perform any special serialization operation to protect the caller's data
84 A cipher is referenced by the caller with a string. That string has the
92 where "template" and "single block cipher" is the aforementioned
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
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
117 sure to refer to the intended cipher implementation.
121 ciphers. Each block listed in /proc/crypto may contain the following
122 information -- if one of the components listed as follows are not
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
130 - driver: the unique name of the cipher -- this name can be used by the
133 - module: the kernel module providing the cipher implementation (or
136 - priority: the priority value of the cipher implementation
138 - refcnt: the reference count of the respective cipher (i.e. the number
141 - selftest: specification whether the self test for the cipher passed
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)
175 - digestsize: output size of the message digest
185 - <builtin> is a marker that the cipher implements IV generation and
186 handling as it is specific to the given cipher
191 When allocating a cipher handle, the caller only specifies the cipher
194 with the length of the provided key. Thus, the kernel crypto API does
195 not provide a separate way to select the particular symmetric cipher key
201 The different cipher handle allocation functions allow the specification
202 of a type and mask flag. Both parameters have the following meaning (and
203 are therefore not covered in the subsequent sections).
205 The type flag specifies the type of the cipher algorithm. The caller
206 usually provides a 0 when the caller wants the default handling.
207 Otherwise, the caller may provide the following selections which match
208 the aforementioned cipher types:
222 together with an IV generator (see geniv field in the /proc/crypto
223 listing for the known IV generators)
242 decompression instead of performing the operation on one segment
246 The mask flag restricts the type of cipher. The only allowed flag is
247 CRYPTO_ALG_ASYNC to restrict the cipher lookup function to
248 asynchronous ciphers. Usually, a caller provides a 0 for the mask flag.
250 When the caller provides a mask and type specification, the caller
251 limits the search the kernel crypto API can perform for a suitable
252 cipher implementation for the given cipher name. That means, even when a
254 the kernel crypto API may not select it due to the used type and mask
262 help to clarify how the kernel crypto API uses various components to
263 implement the complete cipher.
265 The following subsections explain the internal structure based on
266 existing cipher implementations. The first section addresses the most
272 The following ASCII art decomposes the kernel crypto API layers when
273 using the AEAD cipher with the automated IV generation. The shown
274 example is used by the IPSEC layer.
276 For other use cases of AEAD ciphers, the ASCII art applies as well, but
277 the caller may not use the AEAD cipher with a separate IV generator. In
278 this case, the caller must generate the IV.
280 The depicted example decomposes the AEAD cipher of GCM(AES) based on the
282 seqiv.c). The generic implementation serves as an example showing the
283 complete logic of the kernel crypto API.
286 AES-NI) provide implementations merging aspects which in the view of the
288 the AES-NI implementation, the CTR mode, the GHASH implementation and
289 the AES cipher are all merged into one cipher implementation registered
290 with the kernel crypto API. In this case, the concept described by the
291 following ASCII art applies too. However, the decomposition of GCM into
292 the individual sub-components by the kernel crypto API is not done any
295 Each block in the following ASCII art is an independent cipher instance
296 obtained from the kernel crypto API. Each block is accessed by the
297 caller or by other blocks using the API functions defined by the kernel
298 crypto API for the cipher implementation type.
300 The blocks below indicate the cipher type as well as the specific logic
301 implemented in the cipher.
303 The ASCII art picture also indicates the call structure, i.e. who calls
304 which component. The arrows point to the invoked block where the caller
305 uses the API applicable to the cipher type specified for the block.
339 The following call sequence is applicable when the IPSEC layer triggers
340 an encryption operation with the esp_output function. During
341 configuration, the administrator set up the use of rfc4106(gcm(aes)) as
342 the cipher for ESP. The following call sequence is now depicted in the
346 encryption operation of the AEAD cipher with IV generator.
348 In case of GCM, the SEQIV implementation is registered as GIVCIPHER
351 The SEQIV performs its operation to generate an IV where the core
354 2. Now, SEQIV uses the AEAD API function calls to invoke the associated
355 AEAD cipher. In our case, during the instantiation of SEQIV, the
357 invokes AEAD cipher operations with the GCM cipher handle.
359 During instantiation of the GCM handle, the CTR(AES) and GHASH
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
367 3. The GCM AEAD cipher type implementation now invokes the SKCIPHER API
368 with the instantiated CTR(AES) cipher handle.
370 During instantiation of the CTR(AES) cipher, the CIPHER type
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.
378 4. The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES
381 5. The GCM AEAD implementation also invokes the GHASH cipher
382 implementation via the AHASH API.
384 When the IPSEC layer triggers the esp_input() function, the same call
385 sequence is followed with the only difference that the operation starts
391 Generic block ciphers follow the same concept as depicted with the ASCII
395 ASCII art picture above applies as well with the difference that only
396 step (4) is used and the SKCIPHER block chaining mode is CBC.
401 Keyed message digest implementations again follow the same concept as
402 depicted in the ASCII art picture above.
405 sha256_generic.c. The following ASCII art illustrates the
430 1. The AHASH API functions are invoked by the caller. The HMAC
433 During initialization of the HMAC cipher, the SHASH cipher type of
434 SHA256 is instantiated. The cipher handle for the SHA256 instance is
437 At one time, the HMAC implementation requires a SHA256 operation
438 where the SHA256 cipher handle is used.
440 2. The HMAC instance now invokes the SHASH API with the SHA256 cipher
441 handle to calculate the message digest.