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