projects/linux·blob master · refs

262 lines · 6.7 KiB

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