| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
============================= |
| 4 |
Scatterlist Cryptographic API |
| 5 |
============================= |
| 6 |
|
| 7 |
Introduction |
| 8 |
============ |
| 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 |
|
| 20 |
Details |
| 21 |
======= |
| 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 |
| 27 |
of the implementation logic (e.g. manipulating page vectors) and provide an |
| 28 |
abstraction to the underlying algorithms. However, at the user |
| 29 |
level they are very simple. |
| 30 |
|
| 31 |
Conceptually, 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 |
|
| 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 |
|
| 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). |
| 51 |
|
| 52 |
Here'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 |
|
| 83 |
Many real examples are available in the regression test module (tcrypt.c). |
| 84 |
|
| 85 |
|
| 86 |
Developer Notes |
| 87 |
=============== |
| 88 |
|
| 89 |
Transforms may only be allocated in user context, and cryptographic |
| 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. |
| 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 |
|
| 100 |
Adding New Algorithms |
| 101 |
===================== |
| 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 |
|
| 129 |
Bugs |
| 130 |
==== |
| 131 |
|
| 132 |
Send bug reports to: |
| 133 |
[email protected] |
| 134 |
|
| 135 |
Cc: |
| 136 |
Herbert Xu <[email protected]>, |
| 137 |
David S. Miller <[email protected]> |
| 138 |
|
| 139 |
|
| 140 |
Further Information |
| 141 |
=================== |
| 142 |
|
| 143 |
For further patches and various updates, including the current TODO |
| 144 |
list, see: |
| 145 |
http://gondor.apana.org.au/~herbert/crypto/ |
| 146 |
|
| 147 |
|
| 148 |
Authors |
| 149 |
======= |
| 150 |
|
| 151 |
- James Morris |
| 152 |
- David S. Miller |
| 153 |
- Herbert Xu |
| 154 |
|
| 155 |
|
| 156 |
Credits |
| 157 |
======= |
| 158 |
|
| 159 |
The following people provided invaluable feedback during the development |
| 160 |
of 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 |
|
| 171 |
Portions 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 |
|
| 183 |
and; |
| 184 |
|
| 185 |
Nettle (https://www.lysator.liu.se/~nisse/nettle/) |
| 186 |
- Niels Möller |
| 187 |
|
| 188 |
Original 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 |
|
| 204 |
SHA1 algorithm contributors: |
| 205 |
- Jean-Francois Dive |
| 206 |
|
| 207 |
DES algorithm contributors: |
| 208 |
- Raimar Falke |
| 209 |
- Gisle Sælensminde |
| 210 |
- Niels Möller |
| 211 |
|
| 212 |
Blowfish algorithm contributors: |
| 213 |
- Herbert Valerio Riedel |
| 214 |
- Kyle McMartin |
| 215 |
|
| 216 |
Twofish algorithm contributors: |
| 217 |
- Werner Koch |
| 218 |
- Marc Mutz |
| 219 |
|
| 220 |
SHA256/384/512 algorithm contributors: |
| 221 |
- Andrew McDonald |
| 222 |
- Kyle McMartin |
| 223 |
- Herbert Valerio Riedel |
| 224 |
|
| 225 |
AES 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 |
|
| 233 |
CAST5 algorithm contributors: |
| 234 |
- Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). |
| 235 |
|
| 236 |
TEA/XTEA algorithm contributors: |
| 237 |
- Aaron Grothe |
| 238 |
- Michael Ringe |
| 239 |
|
| 240 |
Khazad algorithm contributors: |
| 241 |
- Aaron Grothe |
| 242 |
|
| 243 |
Whirlpool algorithm contributors: |
| 244 |
- Aaron Grothe |
| 245 |
- Jean-Luc Cooke |
| 246 |
|
| 247 |
Anubis algorithm contributors: |
| 248 |
- Aaron Grothe |
| 249 |
|
| 250 |
Tiger algorithm contributors: |
| 251 |
- Aaron Grothe |
| 252 |
|
| 253 |
VIA PadLock contributors: |
| 254 |
- Michal Ludvig |
| 255 |
|
| 256 |
Camellia algorithm contributors: |
| 257 |
- NTT(Nippon Telegraph and Telephone Corporation) (Camellia) |
| 258 |
|
| 259 |
Generic scatterwalk code by Adam J. Richter <[email protected]> |
| 260 |
|
| 261 |
Please send any credits updates or corrections to: |
| 262 |
Herbert Xu <[email protected]> |