Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | Scatterlist Cryptographic API | |
3 | ||
4 | INTRODUCTION | |
5 | ||
6 | The Scatterlist Crypto API takes page vectors (scatterlists) as | |
7 | arguments, and works directly on pages. In some cases (e.g. ECB | |
8 | mode ciphers), this will allow for pages to be encrypted in-place | |
9 | with no copying. | |
10 | ||
11 | One of the initial goals of this design was to readily support IPsec, | |
12 | so that processing can be applied to paged skb's without the need | |
13 | for linearization. | |
14 | ||
15 | ||
16 | DETAILS | |
17 | ||
18 | At the lowest level are algorithms, which register dynamically with the | |
19 | API. | |
20 | ||
21 | 'Transforms' are user-instantiated objects, which maintain state, handle all | |
878b9014 HX |
22 | of the implementation logic (e.g. manipulating page vectors) and provide an |
23 | abstraction to the underlying algorithms. However, at the user | |
1da177e4 LT |
24 | level they are very simple. |
25 | ||
26 | Conceptually, the API layering looks like this: | |
27 | ||
28 | [transform api] (user interface) | |
878b9014 | 29 | [transform ops] (per-type logic glue e.g. cipher.c, compress.c) |
1da177e4 LT |
30 | [algorithm api] (for registering algorithms) |
31 | ||
32 | The idea is to make the user interface and algorithm registration API | |
33 | very simple, while hiding the core logic from both. Many good ideas | |
34 | from existing APIs such as Cryptoapi and Nettle have been adapted for this. | |
35 | ||
86f578de HX |
36 | The API currently supports five main types of transforms: AEAD (Authenticated |
37 | Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and | |
38 | Hashes. | |
39 | ||
40 | Please note that Block Ciphers is somewhat of a misnomer. It is in fact | |
41 | meant to support all ciphers including stream ciphers. The difference | |
42 | between Block Ciphers and Ciphers is that the latter operates on exactly | |
43 | one block while the former can operate on an arbitrary amount of data, | |
44 | subject to block size requirements (i.e., non-stream ciphers can only | |
45 | process multiples of blocks). | |
1da177e4 LT |
46 | |
47 | Support for hardware crypto devices via an asynchronous interface is | |
48 | under development. | |
49 | ||
50 | Here's an example of how to use the API: | |
51 | ||
8bc618d6 | 52 | #include <crypto/ahash.h> |
878b9014 HX |
53 | #include <linux/err.h> |
54 | #include <linux/scatterlist.h> | |
1da177e4 LT |
55 | |
56 | struct scatterlist sg[2]; | |
57 | char result[128]; | |
8bc618d6 HX |
58 | struct crypto_ahash *tfm; |
59 | struct ahash_request *req; | |
1da177e4 | 60 | |
8bc618d6 | 61 | tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC); |
878b9014 | 62 | if (IS_ERR(tfm)) |
1da177e4 LT |
63 | fail(); |
64 | ||
65 | /* ... set up the scatterlists ... */ | |
878b9014 | 66 | |
8bc618d6 HX |
67 | req = ahash_request_alloc(tfm, GFP_ATOMIC); |
68 | if (!req) | |
878b9014 | 69 | fail(); |
8bc618d6 HX |
70 | |
71 | ahash_request_set_callback(req, 0, NULL, NULL); | |
72 | ahash_request_set_crypt(req, sg, result, 2); | |
1da177e4 | 73 | |
8bc618d6 HX |
74 | if (crypto_ahash_digest(req)) |
75 | fail(); | |
76 | ||
77 | ahash_request_free(req); | |
78 | crypto_free_ahash(tfm); | |
1da177e4 LT |
79 | |
80 | ||
81 | Many real examples are available in the regression test module (tcrypt.c). | |
82 | ||
83 | ||
1da177e4 LT |
84 | DEVELOPER NOTES |
85 | ||
86 | Transforms may only be allocated in user context, and cryptographic | |
86f578de HX |
87 | methods may only be called from softirq and user contexts. For |
88 | transforms with a setkey method it too should only be called from | |
89 | user context. | |
1da177e4 LT |
90 | |
91 | When using the API for ciphers, performance will be optimal if each | |
92 | scatterlist contains data which is a multiple of the cipher's block | |
93 | size (typically 8 bytes). This prevents having to do any copying | |
94 | across non-aligned page fragment boundaries. | |
95 | ||
96 | ||
97 | ADDING NEW ALGORITHMS | |
98 | ||
99 | When submitting a new algorithm for inclusion, a mandatory requirement | |
100 | is that at least a few test vectors from known sources (preferably | |
101 | standards) be included. | |
102 | ||
103 | Converting existing well known code is preferred, as it is more likely | |
104 | to have been reviewed and widely tested. If submitting code from LGPL | |
105 | sources, please consider changing the license to GPL (see section 3 of | |
106 | the LGPL). | |
107 | ||
108 | Algorithms submitted must also be generally patent-free (e.g. IDEA | |
109 | will not be included in the mainline until around 2011), and be based | |
110 | on a recognized standard and/or have been subjected to appropriate | |
111 | peer review. | |
112 | ||
113 | Also check for any RFCs which may relate to the use of specific algorithms, | |
114 | as well as general application notes such as RFC2451 ("The ESP CBC-Mode | |
115 | Cipher Algorithms"). | |
116 | ||
117 | It's a good idea to avoid using lots of macros and use inlined functions | |
118 | instead, as gcc does a good job with inlining, while excessive use of | |
119 | macros can cause compilation problems on some platforms. | |
120 | ||
121 | Also check the TODO list at the web site listed below to see what people | |
122 | might already be working on. | |
123 | ||
124 | ||
125 | BUGS | |
126 | ||
127 | Send bug reports to: | |
86f578de HX |
128 | linux-crypto@vger.kernel.org |
129 | Cc: Herbert Xu <herbert@gondor.apana.org.au>, | |
130 | David S. Miller <davem@redhat.com> | |
1da177e4 LT |
131 | |
132 | ||
133 | FURTHER INFORMATION | |
134 | ||
135 | For further patches and various updates, including the current TODO | |
136 | list, see: | |
878b9014 | 137 | http://gondor.apana.org.au/~herbert/crypto/ |
1da177e4 LT |
138 | |
139 | ||
140 | AUTHORS | |
141 | ||
142 | James Morris | |
143 | David S. Miller | |
878b9014 | 144 | Herbert Xu |
1da177e4 LT |
145 | |
146 | ||
147 | CREDITS | |
148 | ||
149 | The following people provided invaluable feedback during the development | |
150 | of 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 | ||
161 | Portions 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 | ||
173 | and; | |
174 | ||
175 | Nettle (http://www.lysator.liu.se/~nisse/nettle/) | |
be2a608b | 176 | Niels Möller |
1da177e4 LT |
177 | |
178 | Original 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) | |
dc2e2f33 | 192 | NTT(Nippon Telegraph and Telephone Corporation) (Camellia) |
1da177e4 LT |
193 | |
194 | SHA1 algorithm contributors: | |
195 | Jean-Francois Dive | |
196 | ||
197 | DES algorithm contributors: | |
198 | Raimar Falke | |
be2a608b JAKJ |
199 | Gisle Sælensminde |
200 | Niels Möller | |
1da177e4 LT |
201 | |
202 | Blowfish algorithm contributors: | |
203 | Herbert Valerio Riedel | |
204 | Kyle McMartin | |
205 | ||
206 | Twofish algorithm contributors: | |
207 | Werner Koch | |
208 | Marc Mutz | |
209 | ||
210 | SHA256/384/512 algorithm contributors: | |
211 | Andrew McDonald | |
212 | Kyle McMartin | |
213 | Herbert Valerio Riedel | |
214 | ||
215 | AES 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 | ||
223 | CAST5 algorithm contributors: | |
224 | Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). | |
225 | ||
226 | TEA/XTEA algorithm contributors: | |
227 | Aaron Grothe | |
fb4f10ed | 228 | Michael Ringe |
1da177e4 LT |
229 | |
230 | Khazad algorithm contributors: | |
231 | Aaron Grothe | |
232 | ||
233 | Whirlpool algorithm contributors: | |
234 | Aaron Grothe | |
235 | Jean-Luc Cooke | |
236 | ||
237 | Anubis algorithm contributors: | |
238 | Aaron Grothe | |
239 | ||
240 | Tiger algorithm contributors: | |
241 | Aaron Grothe | |
242 | ||
878b9014 HX |
243 | VIA PadLock contributors: |
244 | Michal Ludvig | |
245 | ||
dc2e2f33 NT |
246 | Camellia algorithm contributors: |
247 | NTT(Nippon Telegraph and Telephone Corporation) (Camellia) | |
248 | ||
1da177e4 LT |
249 | Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> |
250 | ||
251 | Please send any credits updates or corrections to: | |
878b9014 | 252 | Herbert Xu <herbert@gondor.apana.org.au> |
1da177e4 | 253 |