Documentation/crypto/architecture.rst

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