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