1
2                    Scatterlist Cryptographic API
3                   
4INTRODUCTION
5
6The Scatterlist Crypto API takes page vectors (scatterlists) as
7arguments, and works directly on pages.  In some cases (e.g. ECB
8mode ciphers), this will allow for pages to be encrypted in-place
9with no copying.
10
11One of the initial goals of this design was to readily support IPsec,
12so that processing can be applied to paged skb's without the need
13for linearization.
14
15
16DETAILS
17
18At the lowest level are algorithms, which register dynamically with the
19API.
20
21'Transforms' are user-instantiated objects, which maintain state, handle all
22of the implementation logic (e.g. manipulating page vectors) and provide an 
23abstraction to the underlying algorithms.  However, at the user 
24level they are very simple.
25
26Conceptually, 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  
32The idea is to make the user interface and algorithm registration API
33very simple, while hiding the core logic from both.  Many good ideas
34from existing APIs such as Cryptoapi and Nettle have been adapted for this.
35
36The API currently supports three types of transforms: Ciphers, Digests and
37Compressors.  The compression algorithms especially seem to be performing
38very well so far.
39
40Support for hardware crypto devices via an asynchronous interface is
41under development.
42
43Here's an example of how to use the API:
44
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 ... */
59
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);
67
68    
69Many real examples are available in the regression test module (tcrypt.c).
70
71
72CONFIGURATION NOTES
73
74As Triple DES is part of the DES module, for those using modular builds,
75add the following line to /etc/modprobe.conf:
76
77  alias des3_ede des
78
79The Null algorithms reside in the crypto_null module, so these lines
80should also be added:
81
82  alias cipher_null crypto_null
83  alias digest_null crypto_null
84  alias compress_null crypto_null
85
86The SHA384 algorithm shares code within the SHA512 module, so you'll
87also need:
88  alias sha384 sha512
89
90
91DEVELOPER NOTES
92
93Transforms may only be allocated in user context, and cryptographic
94methods may only be called from softirq and user contexts.
95
96When using the API for ciphers, performance will be optimal if each
97scatterlist contains data which is a multiple of the cipher's block
98size (typically 8 bytes).  This prevents having to do any copying
99across non-aligned page fragment boundaries.
100
101
102ADDING NEW ALGORITHMS
103
104When submitting a new algorithm for inclusion, a mandatory requirement
105is that at least a few test vectors from known sources (preferably
106standards) be included.
107
108Converting existing well known code is preferred, as it is more likely
109to have been reviewed and widely tested.  If submitting code from LGPL
110sources, please consider changing the license to GPL (see section 3 of
111the LGPL).
112
113Algorithms submitted must also be generally patent-free (e.g. IDEA
114will not be included in the mainline until around 2011), and be based
115on a recognized standard and/or have been subjected to appropriate
116peer review.
117
118Also check for any RFCs which may relate to the use of specific algorithms,
119as well as general application notes such as RFC2451 ("The ESP CBC-Mode
120Cipher Algorithms").
121
122It's a good idea to avoid using lots of macros and use inlined functions
123instead, as gcc does a good job with inlining, while excessive use of
124macros can cause compilation problems on some platforms.
125
126Also check the TODO list at the web site listed below to see what people
127might already be working on.
128
129
130BUGS
131
132Send bug reports to:
133Herbert Xu <herbert@gondor.apana.org.au>
134Cc: David S. Miller <davem@redhat.com>
135
136
137FURTHER INFORMATION
138
139For further patches and various updates, including the current TODO
140list, see:
141http://gondor.apana.org.au/~herbert/crypto/
142
143
144AUTHORS
145
146James Morris
147David S. Miller
148Herbert Xu
149
150
151CREDITS
152
153The following people provided invaluable feedback during the development
154of the API:
155
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
164
165Portions 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
176
177and;
178  
179  Nettle (http://www.lysator.liu.se/~nisse/nettle/)
180    Niels M��ller
181
182Original developers of the crypto algorithms:
183
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)
197
198SHA1 algorithm contributors:
199  Jean-Francois Dive
200  
201DES algorithm contributors:
202  Raimar Falke
203  Gisle S��lensminde
204  Niels M��ller
205
206Blowfish algorithm contributors:
207  Herbert Valerio Riedel
208  Kyle McMartin
209
210Twofish algorithm contributors:
211  Werner Koch
212  Marc Mutz
213
214SHA256/384/512 algorithm contributors:
215  Andrew McDonald
216  Kyle McMartin
217  Herbert Valerio Riedel
218  
219AES algorithm contributors:
220  Alexander Kjeldaas
221  Herbert Valerio Riedel
222  Kyle McMartin
223  Adam J. Richter
224  Fruhwirth Clemens (i586)
225  Linus Torvalds (i586)
226
227CAST5 algorithm contributors:
228  Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
229
230TEA/XTEA algorithm contributors:
231  Aaron Grothe
232  Michael Ringe
233
234Khazad algorithm contributors:
235  Aaron Grothe
236
237Whirlpool algorithm contributors:
238  Aaron Grothe
239  Jean-Luc Cooke
240
241Anubis algorithm contributors:
242  Aaron Grothe
243
244Tiger algorithm contributors:
245  Aaron Grothe
246
247VIA PadLock contributors:
248  Michal Ludvig
249
250Camellia algorithm contributors:
251  NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
252
253Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
254
255Please send any credits updates or corrections to:
256Herbert Xu <herbert@gondor.apana.org.au>
257