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