api-intro.rst (6881B)
1.. SPDX-License-Identifier: GPL-2.0 2 3============================= 4Scatterlist Cryptographic API 5============================= 6 7Introduction 8============ 9 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 20Details 21======= 22 23At the lowest level are algorithms, which register dynamically with the 24API. 25 26'Transforms' are user-instantiated objects, which maintain state, handle all 27of the implementation logic (e.g. manipulating page vectors) and provide an 28abstraction to the underlying algorithms. However, at the user 29level 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 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 41The 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). 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 Notes 87=============== 88 89Transforms may only be allocated in user context, and cryptographic 90methods may only be called from softirq and user contexts. For 91transforms with a setkey method it too should only be called from 92user context. 93 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 100Adding New Algorithms 101===================== 102 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 129Bugs 130==== 131 132Send bug reports to: 133 linux-crypto@vger.kernel.org 134 135Cc: 136 Herbert Xu <herbert@gondor.apana.org.au>, 137 David S. Miller <davem@redhat.com> 138 139 140Further Information 141=================== 142 143For further patches and various updates, including the current TODO 144list, see: 145http://gondor.apana.org.au/~herbert/crypto/ 146 147 148Authors 149======= 150 151- James Morris 152- David S. Miller 153- Herbert Xu 154 155 156Credits 157======= 158 159The following people provided invaluable feedback during the development 160of 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 171Portions 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 183and; 184 185 Nettle (https://www.lysator.liu.se/~nisse/nettle/) 186 - Niels Möller 187 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 Dive 206 207DES algorithm contributors: 208 - Raimar Falke 209 - Gisle Sælensminde 210 - Niels Möller 211 212Blowfish algorithm contributors: 213 - Herbert Valerio Riedel 214 - Kyle McMartin 215 216Twofish algorithm contributors: 217 - Werner Koch 218 - Marc Mutz 219 220SHA256/384/512 algorithm contributors: 221 - Andrew McDonald 222 - Kyle McMartin 223 - Herbert Valerio Riedel 224 225AES 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 233CAST5 algorithm contributors: 234 - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). 235 236TEA/XTEA algorithm contributors: 237 - Aaron Grothe 238 - Michael Ringe 239 240Khazad algorithm contributors: 241 - Aaron Grothe 242 243Whirlpool algorithm contributors: 244 - Aaron Grothe 245 - Jean-Luc Cooke 246 247Anubis algorithm contributors: 248 - Aaron Grothe 249 250Tiger algorithm contributors: 251 - Aaron Grothe 252 253VIA PadLock contributors: 254 - Michal Ludvig 255 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>