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 An asynchronous scheduling interface is in planning but not yet
  42 implemented, as we need to further analyze the requirements of all of
  43 the possible hardware scenarios (e.g. IPsec NIC offload).
  44
  45 Here's an example of how to use the API:
  46
  47         #include <linux/crypto.h>
  48
  49         struct scatterlist sg[2];
  50         char result[128];
  51         struct crypto_tfm *tfm;
  52
  53         tfm = crypto_alloc_tfm("md5", 0);
  54         if (tfm == NULL)
  55                 fail();
  56
  57         /* ... set up the scatterlists ... */
  58
  59         crypto_digest_init(tfm);
  60         crypto_digest_update(tfm, &sg, 2);
  61         crypto_digest_final(tfm, result);
  62
  63         crypto_free_tfm(tfm);
  64
  65
  66 Many real examples are available in the regression test module (tcrypt.c).
  67
  68
  69 CONFIGURATION NOTES
  70
  71 As Triple DES is part of the DES module, for those using modular builds,
  72 add the following line to /etc/modules.conf:
  73
  74   alias des3_ede des
  75
  76 The Null algorithms reside in the crypto_null module, so these lines
  77 should also be added:
  78
  79   alias cipher_null crypto_null
  80   alias digest_null crypto_null
  81   alias compress_null crypto_null
  82
  83 The SHA384 algorithm shares code within the SHA512 module, so you'll
  84 also need:
  85   alias sha384 sha512
  86
  87
  88 DEVELOPER NOTES
  89
  90 None of this code should be called from hardirq context, only softirq and
  91 user contexts.
  92
  93 When using the API for ciphers, performance will be optimal if each
  94 scatterlist contains data which is a multiple of the cipher's block
  95 size (typically 8 bytes).  This prevents having to do any copying
  96 across non-aligned page fragment boundaries.
  97
  98
  99 ADDING NEW ALGORITHMS
 100
 101 When submitting a new algorithm for inclusion, a mandatory requirement
 102 is that at least a few test vectors from known sources (preferably
 103 standards) be included.
 104
 105 Converting existing well known code is preferred, as it is more likely
 106 to have been reviewed and widely tested.  If submitting code from LGPL
 107 sources, please consider changing the license to GPL (see section 3 of
 108 the LGPL).
 109
 110 Algorithms submitted must also be generally patent-free (e.g. IDEA
 111 will not be included in the mainline until around 2011), and be based
 112 on a recognized standard and/or have been subjected to appropriate
 113 peer review.
 114
 115 Also check for any RFCs which may relate to the use of specific algorithms,
 116 as well as general application notes such as RFC2451 ("The ESP CBC-Mode
 117 Cipher Algorithms").
 118
 119 It's a good idea to avoid using lots of macros and use inlined functions
 120 instead, as gcc does a good job with inlining, while excessive use of
 121 macros can cause compilation problems on some platforms.
 122
 123 Also check the TODO list at the web site listed below to see what people
 124 might already be working on.
 125
 126
 127 BUGS
 128
 129 Send bug reports to:
 130 James Morris <jmorris@intercode.com.au>
 131 Cc: David S. Miller <davem@redhat.com>
 132
 133
 134 FURTHER INFORMATION
 135
 136 For further patches and various updates, including the current TODO
 137 list, see:
 138 http://samba.org/~jamesm/crypto/
 139
 140 Ongoing development discussion may also be found on
 141 kerneli cryptoapi-devel,
 142 see http://www.kerneli.org/mailman/listinfo/cryptoapi-devel
 143
 144
 145 AUTHORS
 146
 147 James Morris
 148 David S. Miller
 149 Jean-Francois Dive (SHA1 algorithm module)
 150
 151
 152 CREDITS
 153
 154 The following people provided invaluable feedback during the development
 155 of the API:
 156
 157   Alexey Kuznetzov
 158   Rusty Russell
 159   Herbert Valerio Riedel
 160   Jeff Garzik
 161   Michael Richardson
 162   Andrew Morton
 163   Ingo Oeser
 164   Christoph Hellwig
 165
 166 Portions of this API were derived from the following projects:
 167
 168   Kerneli Cryptoapi (http://www.kerneli.org/)
 169     Alexander Kjeldaas
 170     Herbert Valerio Riedel
 171     Kyle McMartin
 172     Jean-Luc Cooke
 173     David Bryson
 174     Clemens Fruhwirth
 175     Tobias Ringstrom
 176     Harald Welte
 177
 178 and;
 179
 180   Nettle (http://www.lysator.liu.se/~nisse/nettle/)
 181     Niels Möller
 182
 183 Original developers of the crypto algorithms:
 184
 185   Dana L. How (DES)
 186   Andrew Tridgell and Steve French (MD4)
 187   Colin Plumb (MD5)
 188   Steve Reid (SHA1)
 189   Jean-Luc Cooke (SHA256, SHA384, SHA512)
 190   Kazunori Miyazawa / USAGI (HMAC)
 191   Matthew Skala (Twofish)
 192   Dag Arne Osvik (Serpent)
 193   Brian Gladman (AES)
 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
 219 Please send any credits updates or corrections to:
 220 James Morris <jmorris@intercode.com.au>
 221