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