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