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   NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
 197
 198 SHA1 algorithm contributors:
 199   Jean-Francois Dive
 200
 201 DES algorithm contributors:
 202   Raimar Falke
 203   Gisle Sælensminde
 204   Niels Möller
 205
 206 Blowfish algorithm contributors:
 207   Herbert Valerio Riedel
 208   Kyle McMartin
 209
 210 Twofish algorithm contributors:
 211   Werner Koch
 212   Marc Mutz
 213
 214 SHA256/384/512 algorithm contributors:
 215   Andrew McDonald
 216   Kyle McMartin
 217   Herbert Valerio Riedel
 218
 219 AES algorithm contributors:
 220   Alexander Kjeldaas
 221   Herbert Valerio Riedel
 222   Kyle McMartin
 223   Adam J. Richter
 224   Fruhwirth Clemens (i586)
 225   Linus Torvalds (i586)
 226
 227 CAST5 algorithm contributors:
 228   Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
 229
 230 TEA/XTEA algorithm contributors:
 231   Aaron Grothe
 232   Michael Ringe
 233
 234 Khazad algorithm contributors:
 235   Aaron Grothe
 236
 237 Whirlpool algorithm contributors:
 238   Aaron Grothe
 239   Jean-Luc Cooke
 240
 241 Anubis algorithm contributors:
 242   Aaron Grothe
 243
 244 Tiger algorithm contributors:
 245   Aaron Grothe
 246
 247 VIA PadLock contributors:
 248   Michal Ludvig
 249
 250 Camellia algorithm contributors:
 251   NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
 252
 253 Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
 254
 255 Please send any credits updates or corrections to:
 256 Herbert Xu <herbert@gondor.apana.org.au>
 257