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 five main types of transforms: AEAD (Authenticated
37Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
38Hashes.
39
40Please note that Block Ciphers is somewhat of a misnomer.  It is in fact
41meant to support all ciphers including stream ciphers.  The difference
42between Block Ciphers and Ciphers is that the latter operates on exactly
43one block while the former can operate on an arbitrary amount of data,
44subject to block size requirements (i.e., non-stream ciphers can only
45process multiples of blocks).
46
47Support for hardware crypto devices via an asynchronous interface is
48under development.
49
50Here'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    
76Many real examples are available in the regression test module (tcrypt.c).
77
78
79DEVELOPER NOTES
80
81Transforms may only be allocated in user context, and cryptographic
82methods may only be called from softirq and user contexts.  For
83transforms with a setkey method it too should only be called from
84user context.
85
86When using the API for ciphers, performance will be optimal if each
87scatterlist contains data which is a multiple of the cipher's block
88size (typically 8 bytes).  This prevents having to do any copying
89across non-aligned page fragment boundaries.
90
91
92ADDING NEW ALGORITHMS
93
94When submitting a new algorithm for inclusion, a mandatory requirement
95is that at least a few test vectors from known sources (preferably
96standards) be included.
97
98Converting existing well known code is preferred, as it is more likely
99to have been reviewed and widely tested.  If submitting code from LGPL
100sources, please consider changing the license to GPL (see section 3 of
101the LGPL).
102
103Algorithms submitted must also be generally patent-free (e.g. IDEA
104will not be included in the mainline until around 2011), and be based
105on a recognized standard and/or have been subjected to appropriate
106peer review.
107
108Also check for any RFCs which may relate to the use of specific algorithms,
109as well as general application notes such as RFC2451 ("The ESP CBC-Mode
110Cipher Algorithms").
111
112It's a good idea to avoid using lots of macros and use inlined functions
113instead, as gcc does a good job with inlining, while excessive use of
114macros can cause compilation problems on some platforms.
115
116Also check the TODO list at the web site listed below to see what people
117might already be working on.
118
119
120BUGS
121
122Send bug reports to:
123linux-crypto@vger.kernel.org
124Cc: Herbert Xu <herbert@gondor.apana.org.au>,
125    David S. Miller <davem@redhat.com>
126
127
128FURTHER INFORMATION
129
130For further patches and various updates, including the current TODO
131list, see:
132http://gondor.apana.org.au/~herbert/crypto/
133
134
135AUTHORS
136
137James Morris
138David S. Miller
139Herbert Xu
140
141
142CREDITS
143
144The following people provided invaluable feedback during the development
145of 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
156Portions 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
168and;
169  
170  Nettle (http://www.lysator.liu.se/~nisse/nettle/)
171    Niels Möller
172
173Original 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
189SHA1 algorithm contributors:
190  Jean-Francois Dive
191  
192DES algorithm contributors:
193  Raimar Falke
194  Gisle Sælensminde
195  Niels Möller
196
197Blowfish algorithm contributors:
198  Herbert Valerio Riedel
199  Kyle McMartin
200
201Twofish algorithm contributors:
202  Werner Koch
203  Marc Mutz
204
205SHA256/384/512 algorithm contributors:
206  Andrew McDonald
207  Kyle McMartin
208  Herbert Valerio Riedel
209  
210AES 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
218CAST5 algorithm contributors:
219  Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
220
221TEA/XTEA algorithm contributors:
222  Aaron Grothe
223  Michael Ringe
224
225Khazad algorithm contributors:
226  Aaron Grothe
227
228Whirlpool algorithm contributors:
229  Aaron Grothe
230  Jean-Luc Cooke
231
232Anubis algorithm contributors:
233  Aaron Grothe
234
235Tiger algorithm contributors:
236  Aaron Grothe
237
238VIA PadLock contributors:
239  Michal Ludvig
240
241Camellia algorithm contributors:
242  NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
243
244Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
245
246Please send any credits updates or corrections to:
247Herbert Xu <herbert@gondor.apana.org.au>
248
249