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
11 arguments, and works directly on pages. In so
12 mode ciphers), this will allow for pages to be
13 with no copying.
14
15 One of the initial goals of this design was to
16 so that processing can be applied to paged skb
17 for linearization.
18
19
20 Details
21 =======
22
23 At the lowest level are algorithms, which regi
24 API.
25
26 'Transforms' are user-instantiated objects, wh
27 of the implementation logic (e.g. manipulating
28 abstraction to the underlying algorithms. How
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. c
35 [algorithm api] (for registering algorithms
36
37 The idea is to make the user interface and alg
38 very simple, while hiding the core logic from
39 from existing APIs such as Cryptoapi and Nettl
40
41 The API currently supports five main types of
42 Encryption with Associated Data), Block Cipher
43 Hashes.
44
45 Please note that Block Ciphers is somewhat of
46 meant to support all ciphers including stream
47 between Block Ciphers and Ciphers is that the
48 one block while the former can operate on an a
49 subject to block size requirements (i.e., non-
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, CRY
64 if (IS_ERR(tfm))
65 fail();
66
67 /* ... set up the scatterlists ... */
68
69 req = ahash_request_alloc(tfm, GFP_ATO
70 if (!req)
71 fail();
72
73 ahash_request_set_callback(req, 0, NUL
74 ahash_request_set_crypt(req, sg, resul
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 regres
84
85
86 Developer Notes
87 ===============
88
89 Transforms may only be allocated in user conte
90 methods may only be called from softirq and us
91 transforms with a setkey method it too should
92 user context.
93
94 When using the API for ciphers, performance wi
95 scatterlist contains data which is a multiple
96 size (typically 8 bytes). This prevents havin
97 across non-aligned page fragment boundaries.
98
99
100 Adding New Algorithms
101 =====================
102
103 When submitting a new algorithm for inclusion,
104 is that at least a few test vectors from known
105 standards) be included.
106
107 Converting existing well known code is preferr
108 to have been reviewed and widely tested. If s
109 sources, please consider changing the license
110 the LGPL).
111
112 Algorithms submitted must also be generally pa
113 will not be included in the mainline until aro
114 on a recognized standard and/or have been subj
115 peer review.
116
117 Also check for any RFCs which may relate to th
118 as well as general application notes such as R
119 Cipher Algorithms").
120
121 It's a good idea to avoid using lots of macros
122 instead, as gcc does a good job with inlining,
123 macros can cause compilation problems on some
124
125 Also check the TODO list at the web site liste
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, inclu
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 feedb
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 fol
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/ne
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 Corpora
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 develope
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 Corpora
258
259 Generic scatterwalk code by Adam J. Richter <ad
260
261 Please send any credits updates or corrections
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.