Documentation/crypto/architecture.rst

8 cipher types:
33 A single block cipher may even be called with multiple templates.
34 However, templates cannot be used without a single cipher.
63 When using the synchronous API operation, the caller invokes a cipher
65 That means, the caller waits until the cipher operation completes.
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
75 signal the completion of the cipher operation. Furthermore, the caller
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,
98         template1(template2(single block cipher)))
102 or a single block cipher. For example, AES on newer Intel hardware has
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
112 Now, a caller may have the need to refer to a specific cipher
115 the cipher implementation to register a unique name in addition to
117 sure to refer to the intended cipher implementation.
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
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
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
147    -  cipher for single block ciphers that may be used with an
154    -  aead for AEAD cipher type
160    -  kpp for a Key-agreement Protocol Primitive (KPP) cipher such as
163 -  blocksize: blocksize of cipher in bytes
178 When allocating a cipher handle, the caller only specifies the cipher
182 not provide a separate way to select the particular symmetric cipher key
188 The different cipher handle allocation functions allow the specification
192 The type flag specifies the type of the cipher algorithm. The caller
195 the aforementioned cipher types:
197 -  CRYPTO_ALG_TYPE_CIPHER Single block cipher
215 -  CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher
223 The mask flag restricts the type of cipher. The only allowed flag is
224 CRYPTO_ALG_ASYNC to restrict the cipher lookup function to
229 cipher implementation for the given cipher name. That means, even when a
230 caller uses a cipher name that exists during its initialization call,
237 The kernel crypto API has an internal structure where a cipher
240 implement the complete cipher.
243 existing cipher implementations. The first section addresses the most
250 using the AEAD cipher with the automated IV generation. The shown
254 the caller may not use the AEAD cipher with a separate IV generator. In
257 The depicted example decomposes the AEAD cipher of GCM(AES) based on the
262 It is possible that some streamlined cipher implementations (like
266 the AES cipher are all merged into one cipher implementation registered
272 Each block in the following ASCII art is an independent cipher instance
275 crypto API for the cipher implementation type.
277 The blocks below indicate the cipher type as well as the specific logic
278 implemented in the cipher.
282 uses the API applicable to the cipher type specified for the block.
310     |   cipher  |
319 as the cipher for ESP. The following call sequence is now depicted in
323    encryption operation of the AEAD cipher with IV generator.
328    AEAD cipher. In our case, during the instantiation of SEQIV, the
329    cipher handle for GCM is provided to SEQIV. This means that SEQIV
330    invokes AEAD cipher operations with the GCM cipher handle.
333    ciphers are instantiated. The cipher handles for CTR(AES) and GHASH
337    the GHASH cipher in the right manner to implement the GCM
340 3. The GCM AEAD cipher type implementation now invokes the SKCIPHER API
341    with the instantiated CTR(AES) cipher handle.
343    During instantiation of the CTR(AES) cipher, the CIPHER type
344    implementation of AES is instantiated. The cipher handle for AES is
352    cipher handle to encrypt one block.
354 5. The GCM AEAD implementation also invokes the GHASH cipher
406    During initialization of the HMAC cipher, the SHASH cipher type of
407    SHA256 is instantiated. The cipher handle for the SHA256 instance is
411    where the SHA256 cipher handle is used.
413 2. The HMAC instance now invokes the SHASH API with the SHA256 cipher