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