blob: 74dffc68ff9f79f9c25409c791f8aaaf7f3188f3 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001
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), provide an
23abstraction to the underlying algorithms, and handle common logical
24operations (e.g. cipher modes, HMAC for digests). However, at the user
25level they are very simple.
26
27Conceptually, the API layering looks like this:
28
29 [transform api] (user interface)
30 [transform ops] (per-type logic glue e.g. cipher.c, digest.c)
31 [algorithm api] (for registering algorithms)
32
33The idea is to make the user interface and algorithm registration API
34very simple, while hiding the core logic from both. Many good ideas
35from existing APIs such as Cryptoapi and Nettle have been adapted for this.
36
37The API currently supports three types of transforms: Ciphers, Digests and
38Compressors. The compression algorithms especially seem to be performing
39very well so far.
40
41Support for hardware crypto devices via an asynchronous interface is
42under development.
43
44Here's an example of how to use the API:
45
46 #include <linux/crypto.h>
47
48 struct scatterlist sg[2];
49 char result[128];
50 struct crypto_tfm *tfm;
51
52 tfm = crypto_alloc_tfm("md5", 0);
53 if (tfm == NULL)
54 fail();
55
56 /* ... set up the scatterlists ... */
57
58 crypto_digest_init(tfm);
59 crypto_digest_update(tfm, &sg, 2);
60 crypto_digest_final(tfm, result);
61
62 crypto_free_tfm(tfm);
63
64
65Many real examples are available in the regression test module (tcrypt.c).
66
67
68CONFIGURATION NOTES
69
70As Triple DES is part of the DES module, for those using modular builds,
71add the following line to /etc/modprobe.conf:
72
73 alias des3_ede des
74
75The Null algorithms reside in the crypto_null module, so these lines
76should also be added:
77
78 alias cipher_null crypto_null
79 alias digest_null crypto_null
80 alias compress_null crypto_null
81
82The SHA384 algorithm shares code within the SHA512 module, so you'll
83also need:
84 alias sha384 sha512
85
86
87DEVELOPER NOTES
88
89Transforms may only be allocated in user context, and cryptographic
90methods may only be called from softirq and user contexts.
91
92When using the API for ciphers, performance will be optimal if each
93scatterlist contains data which is a multiple of the cipher's block
94size (typically 8 bytes). This prevents having to do any copying
95across non-aligned page fragment boundaries.
96
97
98ADDING NEW ALGORITHMS
99
100When submitting a new algorithm for inclusion, a mandatory requirement
101is that at least a few test vectors from known sources (preferably
102standards) be included.
103
104Converting existing well known code is preferred, as it is more likely
105to have been reviewed and widely tested. If submitting code from LGPL
106sources, please consider changing the license to GPL (see section 3 of
107the LGPL).
108
109Algorithms submitted must also be generally patent-free (e.g. IDEA
110will not be included in the mainline until around 2011), and be based
111on a recognized standard and/or have been subjected to appropriate
112peer review.
113
114Also check for any RFCs which may relate to the use of specific algorithms,
115as well as general application notes such as RFC2451 ("The ESP CBC-Mode
116Cipher Algorithms").
117
118It's a good idea to avoid using lots of macros and use inlined functions
119instead, as gcc does a good job with inlining, while excessive use of
120macros can cause compilation problems on some platforms.
121
122Also check the TODO list at the web site listed below to see what people
123might already be working on.
124
125
126BUGS
127
128Send bug reports to:
129James Morris <jmorris@redhat.com>
130Cc: David S. Miller <davem@redhat.com>
131
132
133FURTHER INFORMATION
134
135For further patches and various updates, including the current TODO
136list, see:
137http://samba.org/~jamesm/crypto/
138
139
140AUTHORS
141
142James Morris
143David S. Miller
144
145
146CREDITS
147
148The following people provided invaluable feedback during the development
149of the API:
150
151 Alexey Kuznetzov
152 Rusty Russell
153 Herbert Valerio Riedel
154 Jeff Garzik
155 Michael Richardson
156 Andrew Morton
157 Ingo Oeser
158 Christoph Hellwig
159
160Portions of this API were derived from the following projects:
161
162 Kerneli Cryptoapi (http://www.kerneli.org/)
163 Alexander Kjeldaas
164 Herbert Valerio Riedel
165 Kyle McMartin
166 Jean-Luc Cooke
167 David Bryson
168 Clemens Fruhwirth
169 Tobias Ringstrom
170 Harald Welte
171
172and;
173
174 Nettle (http://www.lysator.liu.se/~nisse/nettle/)
175 Niels Möller
176
177Original developers of the crypto algorithms:
178
179 Dana L. How (DES)
180 Andrew Tridgell and Steve French (MD4)
181 Colin Plumb (MD5)
182 Steve Reid (SHA1)
183 Jean-Luc Cooke (SHA256, SHA384, SHA512)
184 Kazunori Miyazawa / USAGI (HMAC)
185 Matthew Skala (Twofish)
186 Dag Arne Osvik (Serpent)
187 Brian Gladman (AES)
188 Kartikey Mahendra Bhatt (CAST6)
189 Jon Oberheide (ARC4)
190 Jouni Malinen (Michael MIC)
191
192SHA1 algorithm contributors:
193 Jean-Francois Dive
194
195DES algorithm contributors:
196 Raimar Falke
197 Gisle Sælensminde
198 Niels Möller
199
200Blowfish algorithm contributors:
201 Herbert Valerio Riedel
202 Kyle McMartin
203
204Twofish algorithm contributors:
205 Werner Koch
206 Marc Mutz
207
208SHA256/384/512 algorithm contributors:
209 Andrew McDonald
210 Kyle McMartin
211 Herbert Valerio Riedel
212
213AES algorithm contributors:
214 Alexander Kjeldaas
215 Herbert Valerio Riedel
216 Kyle McMartin
217 Adam J. Richter
218 Fruhwirth Clemens (i586)
219 Linus Torvalds (i586)
220
221CAST5 algorithm contributors:
222 Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
223
224TEA/XTEA algorithm contributors:
225 Aaron Grothe
Aaron Grothefb4f10e2005-09-01 17:42:46 -0700226 Michael Ringe
Linus Torvalds1da177e2005-04-16 15:20:36 -0700227
228Khazad algorithm contributors:
229 Aaron Grothe
230
231Whirlpool algorithm contributors:
232 Aaron Grothe
233 Jean-Luc Cooke
234
235Anubis algorithm contributors:
236 Aaron Grothe
237
238Tiger algorithm contributors:
239 Aaron Grothe
240
241Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
242
243Please send any credits updates or corrections to:
244James Morris <jmorris@redhat.com>
245