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