api-intro.txt 6.4 KB

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