1 .. SPDX-License-Identifier: GPL-2.0
2
3 =============================
4 Scatterlist Cryptographic API
5 =============================
6
7 Introduction
8 ============
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
20 Details
21 =======
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
27 of the implementation logic (e.g. manipulating page vectors) and provide an
28 abstraction to the underlying algorithms. However, at the user
29 level they are very simple.
30
31 Conceptually, 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
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
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).
51
52 Here'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
83 Many real examples are available in the regression test module (tcrypt.c).
84
85
86 Developer Notes
87 ===============
88
89 Transforms may only be allocated in user context, and cryptographic
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.
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
100 Adding New Algorithms
101 =====================
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
129 Bugs
130 ====
131
132 Send bug reports to:
133 linux-crypto@vger.kernel.org
134
135 Cc:
136 Herbert Xu <herbert@gondor.apana.org.au>,
137 David S. Miller <davem@redhat.com>
138
139
140 Further Information
141 ===================
142
143 For further patches and various updates, including the current TODO
144 list, see:
145 http://gondor.apana.org.au/~herbert/crypto/
146
147
148 Authors
149 =======
150
151 - James Morris
152 - David S. Miller
153 - Herbert Xu
154
155
156 Credits
157 =======
158
159 The following people provided invaluable feedback during the development
160 of 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
171 Portions 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
183 and;
184
185 Nettle (https://www.lysator.liu.se/~nisse/nettle/)
186 - Niels Möller
187
188 Original 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
204 SHA1 algorithm contributors:
205 - Jean-Francois Dive
206
207 DES algorithm contributors:
208 - Raimar Falke
209 - Gisle Sælensminde
210 - Niels Möller
211
212 Blowfish algorithm contributors:
213 - Herbert Valerio Riedel
214 - Kyle McMartin
215
216 Twofish algorithm contributors:
217 - Werner Koch
218 - Marc Mutz
219
220 SHA256/384/512 algorithm contributors:
221 - Andrew McDonald
222 - Kyle McMartin
223 - Herbert Valerio Riedel
224
225 AES 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
233 CAST5 algorithm contributors:
234 - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
235
236 TEA/XTEA algorithm contributors:
237 - Aaron Grothe
238 - Michael Ringe
239
240 Khazad algorithm contributors:
241 - Aaron Grothe
242
243 Whirlpool algorithm contributors:
244 - Aaron Grothe
245 - Jean-Luc Cooke
246
247 Anubis algorithm contributors:
248 - Aaron Grothe
249
250 Tiger algorithm contributors:
251 - Aaron Grothe
252
253 VIA PadLock contributors:
254 - Michal Ludvig
255
256 Camellia algorithm contributors:
257 - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
258
259 Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
260
261 Please send any credits updates or corrections to:
262 Herbert Xu <herbert@gondor.apana.org.au>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.