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