0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =============================
0004 Scatterlist Cryptographic API
0005 =============================
0006
0007 Introduction
0008 ============
0009
0010 The Scatterlist Crypto API takes page vectors (scatterlists) as
0011 arguments, and works directly on pages. In some cases (e.g. ECB
0012 mode ciphers), this will allow for pages to be encrypted in-place
0013 with no copying.
0014
0015 One of the initial goals of this design was to readily support IPsec,
0016 so that processing can be applied to paged skb's without the need
0017 for linearization.
0018
0019
0020 Details
0021 =======
0022
0023 At the lowest level are algorithms, which register dynamically with the
0024 API.
0025
0026 'Transforms' are user-instantiated objects, which maintain state, handle all
0027 of the implementation logic (e.g. manipulating page vectors) and provide an
0028 abstraction to the underlying algorithms. However, at the user
0029 level they are very simple.
0030
0031 Conceptually, the API layering looks like this::
0032
0033 [transform api] (user interface)
0034 [transform ops] (per-type logic glue e.g. cipher.c, compress.c)
0035 [algorithm api] (for registering algorithms)
0036
0037 The idea is to make the user interface and algorithm registration API
0038 very simple, while hiding the core logic from both. Many good ideas
0039 from existing APIs such as Cryptoapi and Nettle have been adapted for this.
0040
0041 The API currently supports five main types of transforms: AEAD (Authenticated
0042 Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
0043 Hashes.
0044
0045 Please note that Block Ciphers is somewhat of a misnomer. It is in fact
0046 meant to support all ciphers including stream ciphers. The difference
0047 between Block Ciphers and Ciphers is that the latter operates on exactly
0048 one block while the former can operate on an arbitrary amount of data,
0049 subject to block size requirements (i.e., non-stream ciphers can only
0050 process multiples of blocks).
0051
0052 Here's an example of how to use the API::
0053
0054 #include <crypto/hash.h>
0055 #include <linux/err.h>
0056 #include <linux/scatterlist.h>
0057
0058 struct scatterlist sg[2];
0059 char result[128];
0060 struct crypto_ahash *tfm;
0061 struct ahash_request *req;
0062
0063 tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
0064 if (IS_ERR(tfm))
0065 fail();
0066
0067 /* ... set up the scatterlists ... */
0068
0069 req = ahash_request_alloc(tfm, GFP_ATOMIC);
0070 if (!req)
0071 fail();
0072
0073 ahash_request_set_callback(req, 0, NULL, NULL);
0074 ahash_request_set_crypt(req, sg, result, 2);
0075
0076 if (crypto_ahash_digest(req))
0077 fail();
0078
0079 ahash_request_free(req);
0080 crypto_free_ahash(tfm);
0081
0082
0083 Many real examples are available in the regression test module (tcrypt.c).
0084
0085
0086 Developer Notes
0087 ===============
0088
0089 Transforms may only be allocated in user context, and cryptographic
0090 methods may only be called from softirq and user contexts. For
0091 transforms with a setkey method it too should only be called from
0092 user context.
0093
0094 When using the API for ciphers, performance will be optimal if each
0095 scatterlist contains data which is a multiple of the cipher's block
0096 size (typically 8 bytes). This prevents having to do any copying
0097 across non-aligned page fragment boundaries.
0098
0099
0100 Adding New Algorithms
0101 =====================
0102
0103 When submitting a new algorithm for inclusion, a mandatory requirement
0104 is that at least a few test vectors from known sources (preferably
0105 standards) be included.
0106
0107 Converting existing well known code is preferred, as it is more likely
0108 to have been reviewed and widely tested. If submitting code from LGPL
0109 sources, please consider changing the license to GPL (see section 3 of
0110 the LGPL).
0111
0112 Algorithms submitted must also be generally patent-free (e.g. IDEA
0113 will not be included in the mainline until around 2011), and be based
0114 on a recognized standard and/or have been subjected to appropriate
0115 peer review.
0116
0117 Also check for any RFCs which may relate to the use of specific algorithms,
0118 as well as general application notes such as RFC2451 ("The ESP CBC-Mode
0119 Cipher Algorithms").
0120
0121 It's a good idea to avoid using lots of macros and use inlined functions
0122 instead, as gcc does a good job with inlining, while excessive use of
0123 macros can cause compilation problems on some platforms.
0124
0125 Also check the TODO list at the web site listed below to see what people
0126 might already be working on.
0127
0128
0129 Bugs
0130 ====
0131
0132 Send bug reports to:
0133 linux-crypto@vger.kernel.org
0134
0135 Cc:
0136 Herbert Xu <herbert@gondor.apana.org.au>,
0137 David S. Miller <davem@redhat.com>
0138
0139
0140 Further Information
0141 ===================
0142
0143 For further patches and various updates, including the current TODO
0144 list, see:
0145 http://gondor.apana.org.au/~herbert/crypto/
0146
0147
0148 Authors
0149 =======
0150
0151 - James Morris
0152 - David S. Miller
0153 - Herbert Xu
0154
0155
0156 Credits
0157 =======
0158
0159 The following people provided invaluable feedback during the development
0160 of the API:
0161
0162 - Alexey Kuznetzov
0163 - Rusty Russell
0164 - Herbert Valerio Riedel
0165 - Jeff Garzik
0166 - Michael Richardson
0167 - Andrew Morton
0168 - Ingo Oeser
0169 - Christoph Hellwig
0170
0171 Portions of this API were derived from the following projects:
0172
0173 Kerneli Cryptoapi (http://www.kerneli.org/)
0174 - Alexander Kjeldaas
0175 - Herbert Valerio Riedel
0176 - Kyle McMartin
0177 - Jean-Luc Cooke
0178 - David Bryson
0179 - Clemens Fruhwirth
0180 - Tobias Ringstrom
0181 - Harald Welte
0182
0183 and;
0184
0185 Nettle (https://www.lysator.liu.se/~nisse/nettle/)
0186 - Niels Möller
0187
0188 Original developers of the crypto algorithms:
0189
0190 - Dana L. How (DES)
0191 - Andrew Tridgell and Steve French (MD4)
0192 - Colin Plumb (MD5)
0193 - Steve Reid (SHA1)
0194 - Jean-Luc Cooke (SHA256, SHA384, SHA512)
0195 - Kazunori Miyazawa / USAGI (HMAC)
0196 - Matthew Skala (Twofish)
0197 - Dag Arne Osvik (Serpent)
0198 - Brian Gladman (AES)
0199 - Kartikey Mahendra Bhatt (CAST6)
0200 - Jon Oberheide (ARC4)
0201 - Jouni Malinen (Michael MIC)
0202 - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
0203
0204 SHA1 algorithm contributors:
0205 - Jean-Francois Dive
0206
0207 DES algorithm contributors:
0208 - Raimar Falke
0209 - Gisle Sælensminde
0210 - Niels Möller
0211
0212 Blowfish algorithm contributors:
0213 - Herbert Valerio Riedel
0214 - Kyle McMartin
0215
0216 Twofish algorithm contributors:
0217 - Werner Koch
0218 - Marc Mutz
0219
0220 SHA256/384/512 algorithm contributors:
0221 - Andrew McDonald
0222 - Kyle McMartin
0223 - Herbert Valerio Riedel
0224
0225 AES algorithm contributors:
0226 - Alexander Kjeldaas
0227 - Herbert Valerio Riedel
0228 - Kyle McMartin
0229 - Adam J. Richter
0230 - Fruhwirth Clemens (i586)
0231 - Linus Torvalds (i586)
0232
0233 CAST5 algorithm contributors:
0234 - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
0235
0236 TEA/XTEA algorithm contributors:
0237 - Aaron Grothe
0238 - Michael Ringe
0239
0240 Khazad algorithm contributors:
0241 - Aaron Grothe
0242
0243 Whirlpool algorithm contributors:
0244 - Aaron Grothe
0245 - Jean-Luc Cooke
0246
0247 Anubis algorithm contributors:
0248 - Aaron Grothe
0249
0250 Tiger algorithm contributors:
0251 - Aaron Grothe
0252
0253 VIA PadLock contributors:
0254 - Michal Ludvig
0255
0256 Camellia algorithm contributors:
0257 - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
0258
0259 Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
0260
0261 Please send any credits updates or corrections to:
0262 Herbert Xu <herbert@gondor.apana.org.au>
