api-intro.txt 6.5 KB

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