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