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 three types of transforms: Ciphers, Digests and
  37 Compressors.  The compression algorithms especially seem to be performing
  38 very well so far.
  39
  40 Support for hardware crypto devices via an asynchronous interface is
  41 under development.
  42
  43 Here's an example of how to use the API:
  44
  45         #include <linux/crypto.h>
  46         #include <linux/err.h>
  47         #include <linux/scatterlist.h>
  48
  49         struct scatterlist sg[2];
  50         char result[128];
  51         struct crypto_hash *tfm;
  52         struct hash_desc desc;
  53
  54         tfm = crypto_alloc_hash("md5", 0, CRYPTO_ALG_ASYNC);
  55         if (IS_ERR(tfm))
  56                 fail();
  57
  58         /* ... set up the scatterlists ... */
  59
  60         desc.tfm = tfm;
  61         desc.flags = 0;
  62
  63         if (crypto_hash_digest(&desc, &sg, 2, result))
  64                 fail();
  65
  66         crypto_free_hash(tfm);
  67
  68
  69 Many real examples are available in the regression test module (tcrypt.c).
  70
  71
  72 CONFIGURATION NOTES
  73
  74 As Triple DES is part of the DES module, for those using modular builds,
  75 add the following line to /etc/modprobe.conf:
  76
  77   alias des3_ede des
  78
  79 The Null algorithms reside in the crypto_null module, so these lines
  80 should also be added:
  81
  82   alias cipher_null crypto_null
  83   alias digest_null crypto_null
  84   alias compress_null crypto_null
  85
  86 The SHA384 algorithm shares code within the SHA512 module, so you'll
  87 also need:
  88   alias sha384 sha512
  89
  90
  91 DEVELOPER NOTES
  92
  93 Transforms may only be allocated in user context, and cryptographic
  94 methods may only be called from softirq and user contexts.
  95
  96 When using the API for ciphers, performance will be optimal if each
  97 scatterlist contains data which is a multiple of the cipher's block
  98 size (typically 8 bytes).  This prevents having to do any copying
  99 across non-aligned page fragment boundaries.
 100
 101
 102 ADDING NEW ALGORITHMS
 103
 104 When submitting a new algorithm for inclusion, a mandatory requirement
 105 is that at least a few test vectors from known sources (preferably
 106 standards) be included.
 107
 108 Converting existing well known code is preferred, as it is more likely
 109 to have been reviewed and widely tested.  If submitting code from LGPL
 110 sources, please consider changing the license to GPL (see section 3 of
 111 the LGPL).
 112
 113 Algorithms submitted must also be generally patent-free (e.g. IDEA
 114 will not be included in the mainline until around 2011), and be based
 115 on a recognized standard and/or have been subjected to appropriate
 116 peer review.
 117
 118 Also check for any RFCs which may relate to the use of specific algorithms,
 119 as well as general application notes such as RFC2451 ("The ESP CBC-Mode
 120 Cipher Algorithms").
 121
 122 It's a good idea to avoid using lots of macros and use inlined functions
 123 instead, as gcc does a good job with inlining, while excessive use of
 124 macros can cause compilation problems on some platforms.
 125
 126 Also check the TODO list at the web site listed below to see what people
 127 might already be working on.
 128
 129
 130 BUGS
 131
 132 Send bug reports to:
 133 Herbert Xu <herbert@gondor.apana.org.au>
 134 Cc: David S. Miller <davem@redhat.com>
 135
 136
 137 FURTHER INFORMATION
 138
 139 For further patches and various updates, including the current TODO
 140 list, see:
 141 http://gondor.apana.org.au/~herbert/crypto/
 142
 143
 144 AUTHORS
 145
 146 James Morris
 147 David S. Miller
 148 Herbert Xu
 149
 150
 151 CREDITS
 152
 153 The following people provided invaluable feedback during the development
 154 of the API:
 155
 156   Alexey Kuznetzov
 157   Rusty Russell
 158   Herbert Valerio Riedel
 159   Jeff Garzik
 160   Michael Richardson
 161   Andrew Morton
 162   Ingo Oeser
 163   Christoph Hellwig
 164
 165 Portions of this API were derived from the following projects:
 166
 167   Kerneli Cryptoapi (http://www.kerneli.org/)
 168     Alexander Kjeldaas
 169     Herbert Valerio Riedel
 170     Kyle McMartin
 171     Jean-Luc Cooke
 172     David Bryson
 173     Clemens Fruhwirth
 174     Tobias Ringstrom
 175     Harald Welte
 176
 177 and;
 178
 179   Nettle (http://www.lysator.liu.se/~nisse/nettle/)
 180     Niels Möller
 181
 182 Original developers of the crypto algorithms:
 183
 184   Dana L. How (DES)
 185   Andrew Tridgell and Steve French (MD4)
 186   Colin Plumb (MD5)
 187   Steve Reid (SHA1)
 188   Jean-Luc Cooke (SHA256, SHA384, SHA512)
 189   Kazunori Miyazawa / USAGI (HMAC)
 190   Matthew Skala (Twofish)
 191   Dag Arne Osvik (Serpent)
 192   Brian Gladman (AES)
 193   Kartikey Mahendra Bhatt (CAST6)
 194   Jon Oberheide (ARC4)
 195   Jouni Malinen (Michael MIC)
 196
 197 SHA1 algorithm contributors:
 198   Jean-Francois Dive
 199
 200 DES algorithm contributors:
 201   Raimar Falke
 202   Gisle Sælensminde
 203   Niels Möller
 204
 205 Blowfish algorithm contributors:
 206   Herbert Valerio Riedel
 207   Kyle McMartin
 208
 209 Twofish algorithm contributors:
 210   Werner Koch
 211   Marc Mutz
 212
 213 SHA256/384/512 algorithm contributors:
 214   Andrew McDonald
 215   Kyle McMartin
 216   Herbert Valerio Riedel
 217
 218 AES algorithm contributors:
 219   Alexander Kjeldaas
 220   Herbert Valerio Riedel
 221   Kyle McMartin
 222   Adam J. Richter
 223   Fruhwirth Clemens (i586)
 224   Linus Torvalds (i586)
 225
 226 CAST5 algorithm contributors:
 227   Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
 228
 229 TEA/XTEA algorithm contributors:
 230   Aaron Grothe
 231   Michael Ringe
 232
 233 Khazad algorithm contributors:
 234   Aaron Grothe
 235
 236 Whirlpool algorithm contributors:
 237   Aaron Grothe
 238   Jean-Luc Cooke
 239
 240 Anubis algorithm contributors:
 241   Aaron Grothe
 242
 243 Tiger algorithm contributors:
 244   Aaron Grothe
 245
 246 VIA PadLock contributors:
 247   Michal Ludvig
 248
 249 Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
 250
 251 Please send any credits updates or corrections to:
 252 Herbert Xu <herbert@gondor.apana.org.au>
 253