api-intro.rst 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262
  1. .. SPDX-License-Identifier: GPL-2.0
  2. =============================
  3. Scatterlist Cryptographic API
  4. =============================
  5. Introduction
  6. ============
  7. The Scatterlist Crypto API takes page vectors (scatterlists) as
  8. arguments, and works directly on pages. In some cases (e.g. ECB
  9. mode ciphers), this will allow for pages to be encrypted in-place
  10. with no copying.
  11. One of the initial goals of this design was to readily support IPsec,
  12. so that processing can be applied to paged skb's without the need
  13. for linearization.
  14. Details
  15. =======
  16. At the lowest level are algorithms, which register dynamically with the
  17. API.
  18. 'Transforms' are user-instantiated objects, which maintain state, handle all
  19. of the implementation logic (e.g. manipulating page vectors) and provide an
  20. abstraction to the underlying algorithms. However, at the user
  21. level they are very simple.
  22. Conceptually, the API layering looks like this::
  23. [transform api] (user interface)
  24. [transform ops] (per-type logic glue e.g. cipher.c, compress.c)
  25. [algorithm api] (for registering algorithms)
  26. The idea is to make the user interface and algorithm registration API
  27. very simple, while hiding the core logic from both. Many good ideas
  28. from existing APIs such as Cryptoapi and Nettle have been adapted for this.
  29. The API currently supports five main types of transforms: AEAD (Authenticated
  30. Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
  31. Hashes.
  32. Please note that Block Ciphers is somewhat of a misnomer. It is in fact
  33. meant to support all ciphers including stream ciphers. The difference
  34. between Block Ciphers and Ciphers is that the latter operates on exactly
  35. one block while the former can operate on an arbitrary amount of data,
  36. subject to block size requirements (i.e., non-stream ciphers can only
  37. process multiples of blocks).
  38. Here's an example of how to use the API::
  39. #include <crypto/hash.h>
  40. #include <linux/err.h>
  41. #include <linux/scatterlist.h>
  42. struct scatterlist sg[2];
  43. char result[128];
  44. struct crypto_ahash *tfm;
  45. struct ahash_request *req;
  46. tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
  47. if (IS_ERR(tfm))
  48. fail();
  49. /* ... set up the scatterlists ... */
  50. req = ahash_request_alloc(tfm, GFP_ATOMIC);
  51. if (!req)
  52. fail();
  53. ahash_request_set_callback(req, 0, NULL, NULL);
  54. ahash_request_set_crypt(req, sg, result, 2);
  55. if (crypto_ahash_digest(req))
  56. fail();
  57. ahash_request_free(req);
  58. crypto_free_ahash(tfm);
  59. Many real examples are available in the regression test module (tcrypt.c).
  60. Developer Notes
  61. ===============
  62. Transforms may only be allocated in user context, and cryptographic
  63. methods may only be called from softirq and user contexts. For
  64. transforms with a setkey method it too should only be called from
  65. user context.
  66. When using the API for ciphers, performance will be optimal if each
  67. scatterlist contains data which is a multiple of the cipher's block
  68. size (typically 8 bytes). This prevents having to do any copying
  69. across non-aligned page fragment boundaries.
  70. Adding New Algorithms
  71. =====================
  72. When submitting a new algorithm for inclusion, a mandatory requirement
  73. is that at least a few test vectors from known sources (preferably
  74. standards) be included.
  75. Converting existing well known code is preferred, as it is more likely
  76. to have been reviewed and widely tested. If submitting code from LGPL
  77. sources, please consider changing the license to GPL (see section 3 of
  78. the LGPL).
  79. Algorithms submitted must also be generally patent-free (e.g. IDEA
  80. will not be included in the mainline until around 2011), and be based
  81. on a recognized standard and/or have been subjected to appropriate
  82. peer review.
  83. Also check for any RFCs which may relate to the use of specific algorithms,
  84. as well as general application notes such as RFC2451 ("The ESP CBC-Mode
  85. Cipher Algorithms").
  86. It's a good idea to avoid using lots of macros and use inlined functions
  87. instead, as gcc does a good job with inlining, while excessive use of
  88. macros can cause compilation problems on some platforms.
  89. Also check the TODO list at the web site listed below to see what people
  90. might already be working on.
  91. Bugs
  92. ====
  93. Send bug reports to:
  94. linux-crypto@vger.kernel.org
  95. Cc:
  96. Herbert Xu <herbert@gondor.apana.org.au>,
  97. David S. Miller <davem@redhat.com>
  98. Further Information
  99. ===================
  100. For further patches and various updates, including the current TODO
  101. list, see:
  102. http://gondor.apana.org.au/~herbert/crypto/
  103. Authors
  104. =======
  105. - James Morris
  106. - David S. Miller
  107. - Herbert Xu
  108. Credits
  109. =======
  110. The following people provided invaluable feedback during the development
  111. of the API:
  112. - Alexey Kuznetzov
  113. - Rusty Russell
  114. - Herbert Valerio Riedel
  115. - Jeff Garzik
  116. - Michael Richardson
  117. - Andrew Morton
  118. - Ingo Oeser
  119. - Christoph Hellwig
  120. Portions of this API were derived from the following projects:
  121. Kerneli Cryptoapi (http://www.kerneli.org/)
  122. - Alexander Kjeldaas
  123. - Herbert Valerio Riedel
  124. - Kyle McMartin
  125. - Jean-Luc Cooke
  126. - David Bryson
  127. - Clemens Fruhwirth
  128. - Tobias Ringstrom
  129. - Harald Welte
  130. and;
  131. Nettle (https://www.lysator.liu.se/~nisse/nettle/)
  132. - Niels Möller
  133. Original developers of the crypto algorithms:
  134. - Dana L. How (DES)
  135. - Andrew Tridgell and Steve French (MD4)
  136. - Colin Plumb (MD5)
  137. - Steve Reid (SHA1)
  138. - Jean-Luc Cooke (SHA256, SHA384, SHA512)
  139. - Kazunori Miyazawa / USAGI (HMAC)
  140. - Matthew Skala (Twofish)
  141. - Dag Arne Osvik (Serpent)
  142. - Brian Gladman (AES)
  143. - Kartikey Mahendra Bhatt (CAST6)
  144. - Jon Oberheide (ARC4)
  145. - Jouni Malinen (Michael MIC)
  146. - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
  147. SHA1 algorithm contributors:
  148. - Jean-Francois Dive
  149. DES algorithm contributors:
  150. - Raimar Falke
  151. - Gisle Sælensminde
  152. - Niels Möller
  153. Blowfish algorithm contributors:
  154. - Herbert Valerio Riedel
  155. - Kyle McMartin
  156. Twofish algorithm contributors:
  157. - Werner Koch
  158. - Marc Mutz
  159. SHA256/384/512 algorithm contributors:
  160. - Andrew McDonald
  161. - Kyle McMartin
  162. - Herbert Valerio Riedel
  163. AES algorithm contributors:
  164. - Alexander Kjeldaas
  165. - Herbert Valerio Riedel
  166. - Kyle McMartin
  167. - Adam J. Richter
  168. - Fruhwirth Clemens (i586)
  169. - Linus Torvalds (i586)
  170. CAST5 algorithm contributors:
  171. - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
  172. TEA/XTEA algorithm contributors:
  173. - Aaron Grothe
  174. - Michael Ringe
  175. Khazad algorithm contributors:
  176. - Aaron Grothe
  177. Whirlpool algorithm contributors:
  178. - Aaron Grothe
  179. - Jean-Luc Cooke
  180. Anubis algorithm contributors:
  181. - Aaron Grothe
  182. Tiger algorithm contributors:
  183. - Aaron Grothe
  184. VIA PadLock contributors:
  185. - Michal Ludvig
  186. Camellia algorithm contributors:
  187. - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
  188. Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
  189. Please send any credits updates or corrections to:
  190. Herbert Xu <herbert@gondor.apana.org.au>