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