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 three types of transforms: Ciphers, Digests and 37Compressors. The compression algorithms especially seem to be performing 38very well so far. 39 40Support for hardware crypto devices via an asynchronous interface is 41under development. 42 43Here's an example of how to use the API: 44 45 #include <linux/crypto.h> 46 #include <linux/err.h> 47 #include <linux/scatterlist.h> 48 49 struct scatterlist sg[2]; 50 char result[128]; 51 struct crypto_hash *tfm; 52 struct hash_desc desc; 53 54 tfm = crypto_alloc_hash("md5", 0, CRYPTO_ALG_ASYNC); 55 if (IS_ERR(tfm)) 56 fail(); 57 58 /* ... set up the scatterlists ... */ 59 60 desc.tfm = tfm; 61 desc.flags = 0; 62 63 if (crypto_hash_digest(&desc, sg, 2, result)) 64 fail(); 65 66 crypto_free_hash(tfm); 67 68 69Many real examples are available in the regression test module (tcrypt.c). 70 71 72CONFIGURATION NOTES 73 74As Triple DES is part of the DES module, for those using modular builds, 75add the following line to /etc/modprobe.conf: 76 77 alias des3_ede des 78 79The Null algorithms reside in the crypto_null module, so these lines 80should also be added: 81 82 alias cipher_null crypto_null 83 alias digest_null crypto_null 84 alias compress_null crypto_null 85 86The SHA384 algorithm shares code within the SHA512 module, so you'll 87also need: 88 alias sha384 sha512 89 90 91DEVELOPER NOTES 92 93Transforms may only be allocated in user context, and cryptographic 94methods may only be called from softirq and user contexts. 95 96When using the API for ciphers, performance will be optimal if each 97scatterlist contains data which is a multiple of the cipher's block 98size (typically 8 bytes). This prevents having to do any copying 99across non-aligned page fragment boundaries. 100 101 102ADDING NEW ALGORITHMS 103 104When submitting a new algorithm for inclusion, a mandatory requirement 105is that at least a few test vectors from known sources (preferably 106standards) be included. 107 108Converting existing well known code is preferred, as it is more likely 109to have been reviewed and widely tested. If submitting code from LGPL 110sources, please consider changing the license to GPL (see section 3 of 111the LGPL). 112 113Algorithms submitted must also be generally patent-free (e.g. IDEA 114will not be included in the mainline until around 2011), and be based 115on a recognized standard and/or have been subjected to appropriate 116peer review. 117 118Also check for any RFCs which may relate to the use of specific algorithms, 119as well as general application notes such as RFC2451 ("The ESP CBC-Mode 120Cipher Algorithms"). 121 122It's a good idea to avoid using lots of macros and use inlined functions 123instead, as gcc does a good job with inlining, while excessive use of 124macros can cause compilation problems on some platforms. 125 126Also check the TODO list at the web site listed below to see what people 127might already be working on. 128 129 130BUGS 131 132Send bug reports to: 133Herbert Xu <herbert@gondor.apana.org.au> 134Cc: David S. Miller <davem@redhat.com> 135 136 137FURTHER INFORMATION 138 139For further patches and various updates, including the current TODO 140list, see: 141http://gondor.apana.org.au/~herbert/crypto/ 142 143 144AUTHORS 145 146James Morris 147David S. Miller 148Herbert Xu 149 150 151CREDITS 152 153The following people provided invaluable feedback during the development 154of the API: 155 156 Alexey Kuznetzov 157 Rusty Russell 158 Herbert Valerio Riedel 159 Jeff Garzik 160 Michael Richardson 161 Andrew Morton 162 Ingo Oeser 163 Christoph Hellwig 164 165Portions of this API were derived from the following projects: 166 167 Kerneli Cryptoapi (http://www.kerneli.org/) 168 Alexander Kjeldaas 169 Herbert Valerio Riedel 170 Kyle McMartin 171 Jean-Luc Cooke 172 David Bryson 173 Clemens Fruhwirth 174 Tobias Ringstrom 175 Harald Welte 176 177and; 178 179 Nettle (http://www.lysator.liu.se/~nisse/nettle/) 180 Niels M��ller 181 182Original developers of the crypto algorithms: 183 184 Dana L. How (DES) 185 Andrew Tridgell and Steve French (MD4) 186 Colin Plumb (MD5) 187 Steve Reid (SHA1) 188 Jean-Luc Cooke (SHA256, SHA384, SHA512) 189 Kazunori Miyazawa / USAGI (HMAC) 190 Matthew Skala (Twofish) 191 Dag Arne Osvik (Serpent) 192 Brian Gladman (AES) 193 Kartikey Mahendra Bhatt (CAST6) 194 Jon Oberheide (ARC4) 195 Jouni Malinen (Michael MIC) 196 NTT(Nippon Telegraph and Telephone Corporation) (Camellia) 197 198SHA1 algorithm contributors: 199 Jean-Francois Dive 200 201DES algorithm contributors: 202 Raimar Falke 203 Gisle S��lensminde 204 Niels M��ller 205 206Blowfish algorithm contributors: 207 Herbert Valerio Riedel 208 Kyle McMartin 209 210Twofish algorithm contributors: 211 Werner Koch 212 Marc Mutz 213 214SHA256/384/512 algorithm contributors: 215 Andrew McDonald 216 Kyle McMartin 217 Herbert Valerio Riedel 218 219AES algorithm contributors: 220 Alexander Kjeldaas 221 Herbert Valerio Riedel 222 Kyle McMartin 223 Adam J. Richter 224 Fruhwirth Clemens (i586) 225 Linus Torvalds (i586) 226 227CAST5 algorithm contributors: 228 Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). 229 230TEA/XTEA algorithm contributors: 231 Aaron Grothe 232 Michael Ringe 233 234Khazad algorithm contributors: 235 Aaron Grothe 236 237Whirlpool algorithm contributors: 238 Aaron Grothe 239 Jean-Luc Cooke 240 241Anubis algorithm contributors: 242 Aaron Grothe 243 244Tiger algorithm contributors: 245 Aaron Grothe 246 247VIA PadLock contributors: 248 Michal Ludvig 249 250Camellia algorithm contributors: 251 NTT(Nippon Telegraph and Telephone Corporation) (Camellia) 252 253Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> 254 255Please send any credits updates or corrections to: 256Herbert Xu <herbert@gondor.apana.org.au> 257