devel-algos.rst 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240
  1. Developing Cipher Algorithms
  2. ============================
  3. Registering And Unregistering Transformation
  4. --------------------------------------------
  5. There are three distinct types of registration functions in the Crypto
  6. API. One is used to register a generic cryptographic transformation,
  7. while the other two are specific to HASH transformations and
  8. COMPRESSion. We will discuss the latter two in a separate chapter, here
  9. we will only look at the generic ones.
  10. Before discussing the register functions, the data structure to be
  11. filled with each, struct crypto_alg, must be considered -- see below
  12. for a description of this data structure.
  13. The generic registration functions can be found in
  14. include/linux/crypto.h and their definition can be seen below. The
  15. former function registers a single transformation, while the latter
  16. works on an array of transformation descriptions. The latter is useful
  17. when registering transformations in bulk, for example when a driver
  18. implements multiple transformations.
  19. ::
  20. int crypto_register_alg(struct crypto_alg *alg);
  21. int crypto_register_algs(struct crypto_alg *algs, int count);
  22. The counterparts to those functions are listed below.
  23. ::
  24. void crypto_unregister_alg(struct crypto_alg *alg);
  25. void crypto_unregister_algs(struct crypto_alg *algs, int count);
  26. The registration functions return 0 on success, or a negative errno
  27. value on failure. crypto_register_algs() succeeds only if it
  28. successfully registered all the given algorithms; if it fails partway
  29. through, then any changes are rolled back.
  30. The unregistration functions always succeed, so they don't have a
  31. return value. Don't try to unregister algorithms that aren't
  32. currently registered.
  33. Single-Block Symmetric Ciphers [CIPHER]
  34. ---------------------------------------
  35. Example of transformations: aes, serpent, ...
  36. This section describes the simplest of all transformation
  37. implementations, that being the CIPHER type used for symmetric ciphers.
  38. The CIPHER type is used for transformations which operate on exactly one
  39. block at a time and there are no dependencies between blocks at all.
  40. Registration specifics
  41. ~~~~~~~~~~~~~~~~~~~~~~
  42. The registration of [CIPHER] algorithm is specific in that struct
  43. crypto_alg field .cra_type is empty. The .cra_u.cipher has to be
  44. filled in with proper callbacks to implement this transformation.
  45. See struct cipher_alg below.
  46. Cipher Definition With struct cipher_alg
  47. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  48. Struct cipher_alg defines a single block cipher.
  49. Here are schematics of how these functions are called when operated from
  50. other part of the kernel. Note that the .cia_setkey() call might happen
  51. before or after any of these schematics happen, but must not happen
  52. during any of these are in-flight.
  53. ::
  54. KEY ---. PLAINTEXT ---.
  55. v v
  56. .cia_setkey() -> .cia_encrypt()
  57. |
  58. '-----> CIPHERTEXT
  59. Please note that a pattern where .cia_setkey() is called multiple times
  60. is also valid:
  61. ::
  62. KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --.
  63. v v v v
  64. .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt()
  65. | |
  66. '---> CIPHERTEXT1 '---> CIPHERTEXT2
  67. Multi-Block Ciphers
  68. -------------------
  69. Example of transformations: cbc(aes), chacha20, ...
  70. This section describes the multi-block cipher transformation
  71. implementations. The multi-block ciphers are used for transformations
  72. which operate on scatterlists of data supplied to the transformation
  73. functions. They output the result into a scatterlist of data as well.
  74. Registration Specifics
  75. ~~~~~~~~~~~~~~~~~~~~~~
  76. The registration of multi-block cipher algorithms is one of the most
  77. standard procedures throughout the crypto API.
  78. Note, if a cipher implementation requires a proper alignment of data,
  79. the caller should use the functions of crypto_skcipher_alignmask() to
  80. identify a memory alignment mask. The kernel crypto API is able to
  81. process requests that are unaligned. This implies, however, additional
  82. overhead as the kernel crypto API needs to perform the realignment of
  83. the data which may imply moving of data.
  84. Cipher Definition With struct skcipher_alg
  85. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  86. Struct skcipher_alg defines a multi-block cipher, or more generally, a
  87. length-preserving symmetric cipher algorithm.
  88. Scatterlist handling
  89. ~~~~~~~~~~~~~~~~~~~~
  90. Some drivers will want to use the Generic ScatterWalk in case the
  91. hardware needs to be fed separate chunks of the scatterlist which
  92. contains the plaintext and will contain the ciphertext. Please refer
  93. to the ScatterWalk interface offered by the Linux kernel scatter /
  94. gather list implementation.
  95. Hashing [HASH]
  96. --------------
  97. Example of transformations: crc32, md5, sha1, sha256,...
  98. Registering And Unregistering The Transformation
  99. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  100. There are multiple ways to register a HASH transformation, depending on
  101. whether the transformation is synchronous [SHASH] or asynchronous
  102. [AHASH] and the amount of HASH transformations we are registering. You
  103. can find the prototypes defined in include/crypto/internal/hash.h:
  104. ::
  105. int crypto_register_ahash(struct ahash_alg *alg);
  106. int crypto_register_shash(struct shash_alg *alg);
  107. int crypto_register_shashes(struct shash_alg *algs, int count);
  108. The respective counterparts for unregistering the HASH transformation
  109. are as follows:
  110. ::
  111. void crypto_unregister_ahash(struct ahash_alg *alg);
  112. void crypto_unregister_shash(struct shash_alg *alg);
  113. void crypto_unregister_shashes(struct shash_alg *algs, int count);
  114. Cipher Definition With struct shash_alg and ahash_alg
  115. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  116. Here are schematics of how these functions are called when operated from
  117. other part of the kernel. Note that the .setkey() call might happen
  118. before or after any of these schematics happen, but must not happen
  119. during any of these are in-flight. Please note that calling .init()
  120. followed immediately by .finish() is also a perfectly valid
  121. transformation.
  122. ::
  123. I) DATA -----------.
  124. v
  125. .init() -> .update() -> .final() ! .update() might not be called
  126. ^ | | at all in this scenario.
  127. '----' '---> HASH
  128. II) DATA -----------.-----------.
  129. v v
  130. .init() -> .update() -> .finup() ! .update() may not be called
  131. ^ | | at all in this scenario.
  132. '----' '---> HASH
  133. III) DATA -----------.
  134. v
  135. .digest() ! The entire process is handled
  136. | by the .digest() call.
  137. '---------------> HASH
  138. Here is a schematic of how the .export()/.import() functions are called
  139. when used from another part of the kernel.
  140. ::
  141. KEY--. DATA--.
  142. v v ! .update() may not be called
  143. .setkey() -> .init() -> .update() -> .export() at all in this scenario.
  144. ^ | |
  145. '-----' '--> PARTIAL_HASH
  146. ----------- other transformations happen here -----------
  147. PARTIAL_HASH--. DATA1--.
  148. v v
  149. .import -> .update() -> .final() ! .update() may not be called
  150. ^ | | at all in this scenario.
  151. '----' '--> HASH1
  152. PARTIAL_HASH--. DATA2-.
  153. v v
  154. .import -> .finup()
  155. |
  156. '---------------> HASH2
  157. Note that it is perfectly legal to "abandon" a request object:
  158. - call .init() and then (as many times) .update()
  159. - _not_ call any of .final(), .finup() or .export() at any point in future
  160. In other words implementations should mind the resource allocation and clean-up.
  161. No resources related to request objects should remain allocated after a call
  162. to .init() or .update(), since there might be no chance to free them.
  163. Specifics Of Asynchronous HASH Transformation
  164. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  165. Some of the drivers will want to use the Generic ScatterWalk in case the
  166. implementation needs to be fed separate chunks of the scatterlist which
  167. contains the input data. The buffer containing the resulting hash will
  168. always be properly aligned to .cra_alignmask so there is no need to
  169. worry about this.