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