Documentation/crypto/api-intro.txt

   1
   2                     Scatterlist Cryptographic API
   3
   4 INTRODUCTION
   5
   6 The Scatterlist Crypto API takes page vectors (scatterlists) as
   7 arguments, and works directly on pages.  In some cases (e.g. ECB
   8 mode ciphers), this will allow for pages to be encrypted in-place
   9 with no copying.
  10
  11 One of the initial goals of this design was to readily support IPsec,
  12 so that processing can be applied to paged skb's without the need
  13 for linearization.
  14
  15
  16 DETAILS
  17
  18 At the lowest level are algorithms, which register dynamically with the
  19 API.
  20
  21 'Transforms' are user-instantiated objects, which maintain state, handle all
  22 of the implementation logic (e.g. manipulating page vectors) and provide an
  23 abstraction to the underlying algorithms.  However, at the user
  24 level they are very simple.
  25
  26 Conceptually, 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
  32 The idea is to make the user interface and algorithm registration API
  33 very simple, while hiding the core logic from both.  Many good ideas
  34 from existing APIs such as Cryptoapi and Nettle have been adapted for this.
  35
  36 The API currently supports five main types of transforms: AEAD (Authenticated
  37 Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
  38 Hashes.
  39
  40 Please note that Block Ciphers is somewhat of a misnomer.  It is in fact
  41 meant to support all ciphers including stream ciphers.  The difference
  42 between Block Ciphers and Ciphers is that the latter operates on exactly
  43 one block while the former can operate on an arbitrary amount of data,
  44 subject to block size requirements (i.e., non-stream ciphers can only
  45 process multiples of blocks).
  46
  47 Here's an example of how to use the API:
  48
  49         #include <crypto/hash.h>
  50         #include <linux/err.h>
  51         #include <linux/scatterlist.h>
  52
  53         struct scatterlist sg[2];
  54         char result[128];
  55         struct crypto_ahash *tfm;
  56         struct ahash_request *req;
  57
  58         tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
  59         if (IS_ERR(tfm))
  60                 fail();
  61
  62         /* ... set up the scatterlists ... */
  63
  64         req = ahash_request_alloc(tfm, GFP_ATOMIC);
  65         if (!req)
  66                 fail();
  67
  68         ahash_request_set_callback(req, 0, NULL, NULL);
  69         ahash_request_set_crypt(req, sg, result, 2);
  70
  71         if (crypto_ahash_digest(req))
  72                 fail();
  73
  74         ahash_request_free(req);
  75         crypto_free_ahash(tfm);
  76
  77
  78 Many real examples are available in the regression test module (tcrypt.c).
  79
  80
  81 DEVELOPER NOTES
  82
  83 Transforms may only be allocated in user context, and cryptographic
  84 methods may only be called from softirq and user contexts.  For
  85 transforms with a setkey method it too should only be called from
  86 user context.
  87
  88 When using the API for ciphers, performance will be optimal if each
  89 scatterlist contains data which is a multiple of the cipher's block
  90 size (typically 8 bytes).  This prevents having to do any copying
  91 across non-aligned page fragment boundaries.
  92
  93
  94 ADDING NEW ALGORITHMS
  95
  96 When submitting a new algorithm for inclusion, a mandatory requirement
  97 is that at least a few test vectors from known sources (preferably
  98 standards) be included.
  99
 100 Converting existing well known code is preferred, as it is more likely
 101 to have been reviewed and widely tested.  If submitting code from LGPL
 102 sources, please consider changing the license to GPL (see section 3 of
 103 the LGPL).
 104
 105 Algorithms submitted must also be generally patent-free (e.g. IDEA
 106 will not be included in the mainline until around 2011), and be based
 107 on a recognized standard and/or have been subjected to appropriate
 108 peer review.
 109
 110 Also check for any RFCs which may relate to the use of specific algorithms,
 111 as well as general application notes such as RFC2451 ("The ESP CBC-Mode
 112 Cipher Algorithms").
 113
 114 It's a good idea to avoid using lots of macros and use inlined functions
 115 instead, as gcc does a good job with inlining, while excessive use of
 116 macros can cause compilation problems on some platforms.
 117
 118 Also check the TODO list at the web site listed below to see what people
 119 might already be working on.
 120
 121
 122 BUGS
 123
 124 Send bug reports to:
 125 linux-crypto@vger.kernel.org
 126 Cc: Herbert Xu <herbert@gondor.apana.org.au>,
 127     David S. Miller <davem@redhat.com>
 128
 129
 130 FURTHER INFORMATION
 131
 132 For further patches and various updates, including the current TODO
 133 list, see:
 134 http://gondor.apana.org.au/~herbert/crypto/
 135
 136
 137 AUTHORS
 138
 139 James Morris
 140 David S. Miller
 141 Herbert Xu
 142
 143
 144 CREDITS
 145
 146 The following people provided invaluable feedback during the development
 147 of the API:
 148
 149   Alexey Kuznetzov
 150   Rusty Russell
 151   Herbert Valerio Riedel
 152   Jeff Garzik
 153   Michael Richardson
 154   Andrew Morton
 155   Ingo Oeser
 156   Christoph Hellwig
 157
 158 Portions of this API were derived from the following projects:
 159
 160   Kerneli Cryptoapi (http://www.kerneli.org/)
 161     Alexander Kjeldaas
 162     Herbert Valerio Riedel
 163     Kyle McMartin
 164     Jean-Luc Cooke
 165     David Bryson
 166     Clemens Fruhwirth
 167     Tobias Ringstrom
 168     Harald Welte
 169
 170 and;
 171
 172   Nettle (http://www.lysator.liu.se/~nisse/nettle/)
 173     Niels Möller
 174
 175 Original developers of the crypto algorithms:
 176
 177   Dana L. How (DES)
 178   Andrew Tridgell and Steve French (MD4)
 179   Colin Plumb (MD5)
 180   Steve Reid (SHA1)
 181   Jean-Luc Cooke (SHA256, SHA384, SHA512)
 182   Kazunori Miyazawa / USAGI (HMAC)
 183   Matthew Skala (Twofish)
 184   Dag Arne Osvik (Serpent)
 185   Brian Gladman (AES)
 186   Kartikey Mahendra Bhatt (CAST6)
 187   Jon Oberheide (ARC4)
 188   Jouni Malinen (Michael MIC)
 189   NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
 190
 191 SHA1 algorithm contributors:
 192   Jean-Francois Dive
 193
 194 DES algorithm contributors:
 195   Raimar Falke
 196   Gisle Sælensminde
 197   Niels Möller
 198
 199 Blowfish algorithm contributors:
 200   Herbert Valerio Riedel
 201   Kyle McMartin
 202
 203 Twofish algorithm contributors:
 204   Werner Koch
 205   Marc Mutz
 206
 207 SHA256/384/512 algorithm contributors:
 208   Andrew McDonald
 209   Kyle McMartin
 210   Herbert Valerio Riedel
 211
 212 AES algorithm contributors:
 213   Alexander Kjeldaas
 214   Herbert Valerio Riedel
 215   Kyle McMartin
 216   Adam J. Richter
 217   Fruhwirth Clemens (i586)
 218   Linus Torvalds (i586)
 219
 220 CAST5 algorithm contributors:
 221   Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
 222
 223 TEA/XTEA algorithm contributors:
 224   Aaron Grothe
 225   Michael Ringe
 226
 227 Khazad algorithm contributors:
 228   Aaron Grothe
 229
 230 Whirlpool algorithm contributors:
 231   Aaron Grothe
 232   Jean-Luc Cooke
 233
 234 Anubis algorithm contributors:
 235   Aaron Grothe
 236
 237 Tiger algorithm contributors:
 238   Aaron Grothe
 239
 240 VIA PadLock contributors:
 241   Michal Ludvig
 242
 243 Camellia algorithm contributors:
 244   NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
 245
 246 Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
 247
 248 Please send any credits updates or corrections to:
 249 Herbert Xu <herbert@gondor.apana.org.au>
 250