Documentation/crypto/api-intro.rst

   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     linux-crypto@vger.kernel.org
 134
 135 Cc:
 136     Herbert Xu <herbert@gondor.apana.org.au>,
 137     David S. Miller <davem@redhat.com>
 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 <adam@yggdrasil.com>
 260
 261 Please send any credits updates or corrections to:
 262 Herbert Xu <herbert@gondor.apana.org.au>