blob: 15201be0b8114e8030e0614418666decb2054eb0 [file] [log] [blame]
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +02001.. SPDX-License-Identifier: GPL-2.0
Linus Torvalds1da177e2005-04-16 15:20:36 -07002
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +02003=============================
4Scatterlist Cryptographic API
5=============================
6
7Introduction
8============
Linus Torvalds1da177e2005-04-16 15:20:36 -07009
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
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020020Details
21=======
Linus Torvalds1da177e2005-04-16 15:20:36 -070022
23At the lowest level are algorithms, which register dynamically with the
24API.
25
26'Transforms' are user-instantiated objects, which maintain state, handle all
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020027of the implementation logic (e.g. manipulating page vectors) and provide an
28abstraction to the underlying algorithms. However, at the user
Linus Torvalds1da177e2005-04-16 15:20:36 -070029level they are very simple.
30
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020031Conceptually, the API layering looks like this::
Linus Torvalds1da177e2005-04-16 15:20:36 -070032
33 [transform api] (user interface)
Herbert Xu878b9012006-08-20 15:17:04 +100034 [transform ops] (per-type logic glue e.g. cipher.c, compress.c)
Linus Torvalds1da177e2005-04-16 15:20:36 -070035 [algorithm api] (for registering algorithms)
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020036
Linus Torvalds1da177e2005-04-16 15:20:36 -070037The 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
Herbert Xu86f578d2007-11-15 19:00:06 +080041The 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).
Linus Torvalds1da177e2005-04-16 15:20:36 -070051
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020052Here's an example of how to use the API::
Linus Torvalds1da177e2005-04-16 15:20:36 -070053
Baruch Siach450a6c32016-11-30 15:16:09 +020054 #include <crypto/hash.h>
Herbert Xu878b9012006-08-20 15:17:04 +100055 #include <linux/err.h>
56 #include <linux/scatterlist.h>
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020057
Linus Torvalds1da177e2005-04-16 15:20:36 -070058 struct scatterlist sg[2];
59 char result[128];
Herbert Xu8bc618d2016-02-01 21:36:50 +080060 struct crypto_ahash *tfm;
61 struct ahash_request *req;
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020062
Herbert Xu8bc618d2016-02-01 21:36:50 +080063 tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
Herbert Xu878b9012006-08-20 15:17:04 +100064 if (IS_ERR(tfm))
Linus Torvalds1da177e2005-04-16 15:20:36 -070065 fail();
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020066
Linus Torvalds1da177e2005-04-16 15:20:36 -070067 /* ... set up the scatterlists ... */
Herbert Xu878b9012006-08-20 15:17:04 +100068
Herbert Xu8bc618d2016-02-01 21:36:50 +080069 req = ahash_request_alloc(tfm, GFP_ATOMIC);
70 if (!req)
Herbert Xu878b9012006-08-20 15:17:04 +100071 fail();
Herbert Xu8bc618d2016-02-01 21:36:50 +080072
73 ahash_request_set_callback(req, 0, NULL, NULL);
74 ahash_request_set_crypt(req, sg, result, 2);
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020075
Herbert Xu8bc618d2016-02-01 21:36:50 +080076 if (crypto_ahash_digest(req))
77 fail();
78
79 ahash_request_free(req);
80 crypto_free_ahash(tfm);
Linus Torvalds1da177e2005-04-16 15:20:36 -070081
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020082
Linus Torvalds1da177e2005-04-16 15:20:36 -070083Many real examples are available in the regression test module (tcrypt.c).
84
85
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +020086Developer Notes
87===============
Linus Torvalds1da177e2005-04-16 15:20:36 -070088
89Transforms may only be allocated in user context, and cryptographic
Herbert Xu86f578d2007-11-15 19:00:06 +080090methods may only be called from softirq and user contexts. For
91transforms with a setkey method it too should only be called from
92user context.
Linus Torvalds1da177e2005-04-16 15:20:36 -070093
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
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200100Adding New Algorithms
101=====================
Linus Torvalds1da177e2005-04-16 15:20:36 -0700102
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
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200129Bugs
130====
Linus Torvalds1da177e2005-04-16 15:20:36 -0700131
132Send bug reports to:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200133 linux-crypto@vger.kernel.org
134
135Cc:
136 Herbert Xu <herbert@gondor.apana.org.au>,
Herbert Xu86f578d2007-11-15 19:00:06 +0800137 David S. Miller <davem@redhat.com>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700138
139
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200140Further Information
141===================
Linus Torvalds1da177e2005-04-16 15:20:36 -0700142
143For further patches and various updates, including the current TODO
144list, see:
Herbert Xu878b9012006-08-20 15:17:04 +1000145http://gondor.apana.org.au/~herbert/crypto/
Linus Torvalds1da177e2005-04-16 15:20:36 -0700146
147
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200148Authors
149=======
Linus Torvalds1da177e2005-04-16 15:20:36 -0700150
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200151- James Morris
152- David S. Miller
153- Herbert Xu
Linus Torvalds1da177e2005-04-16 15:20:36 -0700154
155
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200156Credits
157=======
Linus Torvalds1da177e2005-04-16 15:20:36 -0700158
159The following people provided invaluable feedback during the development
160of the API:
161
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200162 - Alexey Kuznetzov
163 - Rusty Russell
164 - Herbert Valerio Riedel
165 - Jeff Garzik
166 - Michael Richardson
167 - Andrew Morton
168 - Ingo Oeser
169 - Christoph Hellwig
Linus Torvalds1da177e2005-04-16 15:20:36 -0700170
171Portions of this API were derived from the following projects:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200172
Linus Torvalds1da177e2005-04-16 15:20:36 -0700173 Kerneli Cryptoapi (http://www.kerneli.org/)
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200174 - 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
Linus Torvalds1da177e2005-04-16 15:20:36 -0700182
183and;
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200184
Alexander A. Klimov9332a9e2020-07-19 18:49:59 +0200185 Nettle (https://www.lysator.liu.se/~nisse/nettle/)
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200186 - Niels Möller
Linus Torvalds1da177e2005-04-16 15:20:36 -0700187
188Original developers of the crypto algorithms:
189
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200190 - 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)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700203
204SHA1 algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200205 - Jean-Francois Dive
206
Linus Torvalds1da177e2005-04-16 15:20:36 -0700207DES algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200208 - Raimar Falke
209 - Gisle Sælensminde
210 - Niels Möller
Linus Torvalds1da177e2005-04-16 15:20:36 -0700211
212Blowfish algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200213 - Herbert Valerio Riedel
214 - Kyle McMartin
Linus Torvalds1da177e2005-04-16 15:20:36 -0700215
216Twofish algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200217 - Werner Koch
218 - Marc Mutz
Linus Torvalds1da177e2005-04-16 15:20:36 -0700219
220SHA256/384/512 algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200221 - Andrew McDonald
222 - Kyle McMartin
223 - Herbert Valerio Riedel
224
Linus Torvalds1da177e2005-04-16 15:20:36 -0700225AES algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200226 - Alexander Kjeldaas
227 - Herbert Valerio Riedel
228 - Kyle McMartin
229 - Adam J. Richter
230 - Fruhwirth Clemens (i586)
231 - Linus Torvalds (i586)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700232
233CAST5 algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200234 - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700235
236TEA/XTEA algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200237 - Aaron Grothe
238 - Michael Ringe
Linus Torvalds1da177e2005-04-16 15:20:36 -0700239
240Khazad algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200241 - Aaron Grothe
Linus Torvalds1da177e2005-04-16 15:20:36 -0700242
243Whirlpool algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200244 - Aaron Grothe
245 - Jean-Luc Cooke
Linus Torvalds1da177e2005-04-16 15:20:36 -0700246
247Anubis algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200248 - Aaron Grothe
Linus Torvalds1da177e2005-04-16 15:20:36 -0700249
250Tiger algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200251 - Aaron Grothe
Linus Torvalds1da177e2005-04-16 15:20:36 -0700252
Herbert Xu878b9012006-08-20 15:17:04 +1000253VIA PadLock contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200254 - Michal Ludvig
Herbert Xu878b9012006-08-20 15:17:04 +1000255
Noriaki TAKAMIYAdc2e2f32006-10-22 15:06:46 +1000256Camellia algorithm contributors:
Mauro Carvalho Chehab58465512020-06-15 08:50:09 +0200257 - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
Noriaki TAKAMIYAdc2e2f32006-10-22 15:06:46 +1000258
Linus Torvalds1da177e2005-04-16 15:20:36 -0700259Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
260
261Please send any credits updates or corrections to:
Herbert Xu878b9012006-08-20 15:17:04 +1000262Herbert Xu <herbert@gondor.apana.org.au>