architecture.rst 14 KB

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