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