263 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=============================4Scatterlist Cryptographic API5=============================6 7Introduction8============9 10The Scatterlist Crypto API takes page vectors (scatterlists) as11arguments, and works directly on pages. In some cases (e.g. ECB12mode ciphers), this will allow for pages to be encrypted in-place13with 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 need17for linearization.18 19 20Details21=======22 23At the lowest level are algorithms, which register dynamically with the24API.25 26'Transforms' are user-instantiated objects, which maintain state, handle all27of the implementation logic (e.g. manipulating page vectors) and provide an28abstraction to the underlying algorithms. However, at the user29level 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 API38very simple, while hiding the core logic from both. Many good ideas39from existing APIs such as Cryptoapi and Nettle have been adapted for this.40 41The API currently supports five main types of transforms: AEAD (Authenticated42Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and43Hashes.44 45Please note that Block Ciphers is somewhat of a misnomer. It is in fact46meant to support all ciphers including stream ciphers. The difference47between Block Ciphers and Ciphers is that the latter operates on exactly48one block while the former can operate on an arbitrary amount of data,49subject to block size requirements (i.e., non-stream ciphers can only50process 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 Notes87===============88 89Transforms may only be allocated in user context, and cryptographic90methods may only be called from softirq and user contexts. For91transforms with a setkey method it too should only be called from92user context.93 94When using the API for ciphers, performance will be optimal if each95scatterlist contains data which is a multiple of the cipher's block96size (typically 8 bytes). This prevents having to do any copying97across non-aligned page fragment boundaries.98 99 100Adding New Algorithms101=====================102 103When submitting a new algorithm for inclusion, a mandatory requirement104is that at least a few test vectors from known sources (preferably105standards) be included.106 107Converting existing well known code is preferred, as it is more likely108to have been reviewed and widely tested. If submitting code from LGPL109sources, please consider changing the license to GPL (see section 3 of110the LGPL).111 112Algorithms submitted must also be generally patent-free (e.g. IDEA113will not be included in the mainline until around 2011), and be based114on a recognized standard and/or have been subjected to appropriate115peer 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-Mode119Cipher Algorithms").120 121It's a good idea to avoid using lots of macros and use inlined functions122instead, as gcc does a good job with inlining, while excessive use of123macros can cause compilation problems on some platforms.124 125Also check the TODO list at the web site listed below to see what people126might already be working on.127 128 129Bugs130====131 132Send bug reports to:133 linux-crypto@vger.kernel.org134 135Cc:136 Herbert Xu <herbert@gondor.apana.org.au>,137 David S. Miller <davem@redhat.com>138 139 140Further Information141===================142 143For further patches and various updates, including the current TODO144list, see:145http://gondor.apana.org.au/~herbert/crypto/146 147 148Authors149=======150 151- James Morris152- David S. Miller153- Herbert Xu154 155 156Credits157=======158 159The following people provided invaluable feedback during the development160of the API:161 162 - Alexey Kuznetzov163 - Rusty Russell164 - Herbert Valerio Riedel165 - Jeff Garzik166 - Michael Richardson167 - Andrew Morton168 - Ingo Oeser169 - Christoph Hellwig170 171Portions of this API were derived from the following projects:172 173 Kerneli Cryptoapi (http://www.kerneli.org/)174 - Alexander Kjeldaas175 - Herbert Valerio Riedel176 - Kyle McMartin177 - Jean-Luc Cooke178 - David Bryson179 - Clemens Fruhwirth180 - Tobias Ringstrom181 - Harald Welte182 183and;184 185 Nettle (https://www.lysator.liu.se/~nisse/nettle/)186 - Niels Möller187 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 Dive206 207DES algorithm contributors:208 - Raimar Falke209 - Gisle Sælensminde210 - Niels Möller211 212Blowfish algorithm contributors:213 - Herbert Valerio Riedel214 - Kyle McMartin215 216Twofish algorithm contributors:217 - Werner Koch218 - Marc Mutz219 220SHA256/384/512 algorithm contributors:221 - Andrew McDonald222 - Kyle McMartin223 - Herbert Valerio Riedel224 225AES algorithm contributors:226 - Alexander Kjeldaas227 - Herbert Valerio Riedel228 - Kyle McMartin229 - Adam J. Richter230 - 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 Grothe238 - Michael Ringe239 240Khazad algorithm contributors:241 - Aaron Grothe242 243Whirlpool algorithm contributors:244 - Aaron Grothe245 - Jean-Luc Cooke246 247Anubis algorithm contributors:248 - Aaron Grothe249 250Tiger algorithm contributors:251 - Aaron Grothe252 253VIA PadLock contributors:254 - Michal Ludvig255 256Camellia algorithm contributors:257 - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)258 259Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>260 261Please send any credits updates or corrections to:262Herbert Xu <herbert@gondor.apana.org.au>263