^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) Kernel Crypto API Architecture
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Cipher algorithm types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) The kernel crypto API provides different API calls for the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) cipher types:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) - Symmetric ciphers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) - AEAD ciphers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) - Message digest, including keyed message digest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) - Random number generation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) - User space interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) Ciphers And Templates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) The kernel crypto API provides implementations of single block ciphers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) and message digests. In addition, the kernel crypto API provides
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) numerous "templates" that can be used in conjunction with the single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) block ciphers and message digests. Templates include all types of block
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) chaining mode, the HMAC mechanism, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Single block ciphers and message digests can either be directly used by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) a caller or invoked together with a template to form multi-block ciphers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) or keyed message digests.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) A single block cipher may even be called with multiple templates.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) However, templates cannot be used without a single cipher.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) See /proc/crypto and search for "name". For example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) - aes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) - ecb(aes)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) - cmac(aes)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) - ccm(aes)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) - rfc4106(gcm(aes))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) - sha1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) - hmac(sha1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) - authenc(hmac(sha1),cbc(aes))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) In these examples, "aes" and "sha1" are the ciphers and all others are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) the templates.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) Synchronous And Asynchronous Operation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) The kernel crypto API provides synchronous and asynchronous API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) When using the synchronous API operation, the caller invokes a cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) operation which is performed synchronously by the kernel crypto API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) That means, the caller waits until the cipher operation completes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) Therefore, the kernel crypto API calls work like regular function calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) For synchronous operation, the set of API calls is small and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) conceptually similar to any other crypto library.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) Asynchronous operation is provided by the kernel crypto API which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) implies that the invocation of a cipher operation will complete almost
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) instantly. That invocation triggers the cipher operation but it does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) signal its completion. Before invoking a cipher operation, the caller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) must provide a callback function the kernel crypto API can invoke to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) signal the completion of the cipher operation. Furthermore, the caller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) must ensure it can handle such asynchronous events by applying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) appropriate locking around its data. The kernel crypto API does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) perform any special serialization operation to protect the caller's data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) integrity.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) Crypto API Cipher References And Priority
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) -----------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) A cipher is referenced by the caller with a string. That string has the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) following semantics:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) template(single block cipher)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) where "template" and "single block cipher" is the aforementioned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) template and single block cipher, respectively. If applicable,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) additional templates may enclose other templates, such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) template1(template2(single block cipher)))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) The kernel crypto API may provide multiple implementations of a template
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) or a single block cipher. For example, AES on newer Intel hardware has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) the following implementations: AES-NI, assembler implementation, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) straight C. Now, when using the string "aes" with the kernel crypto API,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) which cipher implementation is used? The answer to that question is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) priority number assigned to each cipher implementation by the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) crypto API. When a caller uses the string to refer to a cipher during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) initialization of a cipher handle, the kernel crypto API looks up all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) implementations providing an implementation with that name and selects
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) the implementation with the highest priority.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) Now, a caller may have the need to refer to a specific cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) implementation and thus does not want to rely on the priority-based
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) selection. To accommodate this scenario, the kernel crypto API allows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) the cipher implementation to register a unique name in addition to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) common names. When using that unique name, a caller is therefore always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) sure to refer to the intended cipher implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) The list of available ciphers is given in /proc/crypto. However, that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) list does not specify all possible permutations of templates and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) ciphers. Each block listed in /proc/crypto may contain the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) information -- if one of the components listed as follows are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) applicable to a cipher, it is not displayed:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) - name: the generic name of the cipher that is subject to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) priority-based selection -- this name can be used by the cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) allocation API calls (all names listed above are examples for such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) generic names)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - driver: the unique name of the cipher -- this name can be used by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) cipher allocation API calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) - module: the kernel module providing the cipher implementation (or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) "kernel" for statically linked ciphers)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) - priority: the priority value of the cipher implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) - refcnt: the reference count of the respective cipher (i.e. the number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) of current consumers of this cipher)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) - selftest: specification whether the self test for the cipher passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) - type:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) - skcipher for symmetric key ciphers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) - cipher for single block ciphers that may be used with an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) additional template
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) - shash for synchronous message digest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) - ahash for asynchronous message digest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) - aead for AEAD cipher type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) - compression for compression type transformations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) - rng for random number generator
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) - kpp for a Key-agreement Protocol Primitive (KPP) cipher such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) an ECDH or DH implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) - blocksize: blocksize of cipher in bytes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) - keysize: key size in bytes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) - ivsize: IV size in bytes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) - seedsize: required size of seed data for random number generator
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) - digestsize: output size of the message digest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) - geniv: IV generator (obsolete)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) Key Sizes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) When allocating a cipher handle, the caller only specifies the cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) type. Symmetric ciphers, however, typically support multiple key sizes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) (e.g. AES-128 vs. AES-192 vs. AES-256). These key sizes are determined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) with the length of the provided key. Thus, the kernel crypto API does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) not provide a separate way to select the particular symmetric cipher key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) size.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) Cipher Allocation Type And Masks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) The different cipher handle allocation functions allow the specification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) of a type and mask flag. Both parameters have the following meaning (and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) are therefore not covered in the subsequent sections).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) The type flag specifies the type of the cipher algorithm. The caller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) usually provides a 0 when the caller wants the default handling.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) Otherwise, the caller may provide the following selections which match
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) the aforementioned cipher types:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) - CRYPTO_ALG_TYPE_CIPHER Single block cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) - CRYPTO_ALG_TYPE_COMPRESS Compression
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) - CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with Associated Data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) (MAC)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) - CRYPTO_ALG_TYPE_KPP Key-agreement Protocol Primitive (KPP) such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) an ECDH or DH implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) - CRYPTO_ALG_TYPE_HASH Raw message digest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) - CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) - CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) - CRYPTO_ALG_TYPE_RNG Random Number Generation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) - CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) - CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression /
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) decompression instead of performing the operation on one segment
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) The mask flag restricts the type of cipher. The only allowed flag is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) CRYPTO_ALG_ASYNC to restrict the cipher lookup function to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) asynchronous ciphers. Usually, a caller provides a 0 for the mask flag.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) When the caller provides a mask and type specification, the caller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) limits the search the kernel crypto API can perform for a suitable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) cipher implementation for the given cipher name. That means, even when a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) caller uses a cipher name that exists during its initialization call,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) the kernel crypto API may not select it due to the used type and mask
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) field.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) Internal Structure of Kernel Crypto API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) ---------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) The kernel crypto API has an internal structure where a cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) implementation may use many layers and indirections. This section shall
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) help to clarify how the kernel crypto API uses various components to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) implement the complete cipher.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) The following subsections explain the internal structure based on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) existing cipher implementations. The first section addresses the most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) complex scenario where all other scenarios form a logical subset.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) Generic AEAD Cipher Structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) The following ASCII art decomposes the kernel crypto API layers when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) using the AEAD cipher with the automated IV generation. The shown
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) example is used by the IPSEC layer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) For other use cases of AEAD ciphers, the ASCII art applies as well, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) the caller may not use the AEAD cipher with a separate IV generator. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) this case, the caller must generate the IV.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) The depicted example decomposes the AEAD cipher of GCM(AES) based on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) generic C implementations (gcm.c, aes-generic.c, ctr.c, ghash-generic.c,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) seqiv.c). The generic implementation serves as an example showing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) complete logic of the kernel crypto API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) It is possible that some streamlined cipher implementations (like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) AES-NI) provide implementations merging aspects which in the view of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) kernel crypto API cannot be decomposed into layers any more. In case of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) the AES-NI implementation, the CTR mode, the GHASH implementation and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) the AES cipher are all merged into one cipher implementation registered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) with the kernel crypto API. In this case, the concept described by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) following ASCII art applies too. However, the decomposition of GCM into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) the individual sub-components by the kernel crypto API is not done any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) more.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) Each block in the following ASCII art is an independent cipher instance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) obtained from the kernel crypto API. Each block is accessed by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) caller or by other blocks using the API functions defined by the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) crypto API for the cipher implementation type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) The blocks below indicate the cipher type as well as the specific logic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) implemented in the cipher.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) The ASCII art picture also indicates the call structure, i.e. who calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) which component. The arrows point to the invoked block where the caller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) uses the API applicable to the cipher type specified for the block.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) kernel crypto API | IPSEC Layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) +-----------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) | | (1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) | aead | <----------------------------------- esp_output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) | (seqiv) | ---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) +-----------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) | (2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) +-----------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) | | <--+ (2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) | aead | <----------------------------------- esp_input
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) | (gcm) | ------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) +-----------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) | (3) | (5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) v v
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) +-----------+ +-----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) | | | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) | skcipher | | ahash |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) | (ctr) | ---+ | (ghash) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) +-----------+ | +-----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) +-----------+ | (4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) | | <--+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) | cipher |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) | (aes) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) +-----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) The following call sequence is applicable when the IPSEC layer triggers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) an encryption operation with the esp_output function. During
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) configuration, the administrator set up the use of seqiv(rfc4106(gcm(aes)))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) as the cipher for ESP. The following call sequence is now depicted in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) the ASCII art above:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) 1. esp_output() invokes crypto_aead_encrypt() to trigger an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) encryption operation of the AEAD cipher with IV generator.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) The SEQIV generates the IV.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) 2. Now, SEQIV uses the AEAD API function calls to invoke the associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) AEAD cipher. In our case, during the instantiation of SEQIV, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) cipher handle for GCM is provided to SEQIV. This means that SEQIV
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) invokes AEAD cipher operations with the GCM cipher handle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) During instantiation of the GCM handle, the CTR(AES) and GHASH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) ciphers are instantiated. The cipher handles for CTR(AES) and GHASH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) are retained for later use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) The GCM implementation is responsible to invoke the CTR mode AES and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) the GHASH cipher in the right manner to implement the GCM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) specification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) 3. The GCM AEAD cipher type implementation now invokes the SKCIPHER API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) with the instantiated CTR(AES) cipher handle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) During instantiation of the CTR(AES) cipher, the CIPHER type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) implementation of AES is instantiated. The cipher handle for AES is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) retained.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) That means that the SKCIPHER implementation of CTR(AES) only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) implements the CTR block chaining mode. After performing the block
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) chaining operation, the CIPHER implementation of AES is invoked.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) 4. The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) cipher handle to encrypt one block.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) 5. The GCM AEAD implementation also invokes the GHASH cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) implementation via the AHASH API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) When the IPSEC layer triggers the esp_input() function, the same call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) sequence is followed with the only difference that the operation starts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) with step (2).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) Generic Block Cipher Structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) Generic block ciphers follow the same concept as depicted with the ASCII
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) art picture above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) ASCII art picture above applies as well with the difference that only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) step (4) is used and the SKCIPHER block chaining mode is CBC.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) Generic Keyed Message Digest Structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) Keyed message digest implementations again follow the same concept as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) depicted in the ASCII art picture above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) For example, HMAC(SHA256) is implemented with hmac.c and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) sha256_generic.c. The following ASCII art illustrates the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) implementation:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) kernel crypto API | Caller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) +-----------+ (1) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) | | <------------------ some_function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) | ahash |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) | (hmac) | ---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) +-----------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) | (2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) +-----------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) | | <--+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) | shash |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) | (sha256) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) +-----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) The following call sequence is applicable when a caller triggers an HMAC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) operation:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) 1. The AHASH API functions are invoked by the caller. The HMAC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) implementation performs its operation as needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) During initialization of the HMAC cipher, the SHASH cipher type of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) SHA256 is instantiated. The cipher handle for the SHA256 instance is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) retained.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) At one time, the HMAC implementation requires a SHA256 operation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) where the SHA256 cipher handle is used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) 2. The HMAC instance now invokes the SHASH API with the SHA256 cipher
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) handle to calculate the message digest.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags