linux/Documentation/crypto/api-intro.txt
<<
>>
Prefs
   1
   2                    Scatterlist Cryptographic API
   3                   
   4INTRODUCTION
   5
   6The Scatterlist Crypto API takes page vectors (scatterlists) as
   7arguments, and works directly on pages.  In some cases (e.g. ECB
   8mode ciphers), this will allow for pages to be encrypted in-place
   9with no copying.
  10
  11One of the initial goals of this design was to readily support IPsec,
  12so that processing can be applied to paged skb's without the need
  13for linearization.
  14
  15
  16DETAILS
  17
  18At the lowest level are algorithms, which register dynamically with the
  19API.
  20
  21'Transforms' are user-instantiated objects, which maintain state, handle all
  22of the implementation logic (e.g. manipulating page vectors) and provide an 
  23abstraction to the underlying algorithms.  However, at the user 
  24level they are very simple.
  25
  26Conceptually, 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  
  32The idea is to make the user interface and algorithm registration API
  33very simple, while hiding the core logic from both.  Many good ideas
  34from existing APIs such as Cryptoapi and Nettle have been adapted for this.
  35
  36The API currently supports five main types of transforms: AEAD (Authenticated
  37Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
  38Hashes.
  39
  40Please note that Block Ciphers is somewhat of a misnomer.  It is in fact
  41meant to support all ciphers including stream ciphers.  The difference
  42between Block Ciphers and Ciphers is that the latter operates on exactly
  43one block while the former can operate on an arbitrary amount of data,
  44subject to block size requirements (i.e., non-stream ciphers can only
  45process multiples of blocks).
  46
  47Support for hardware crypto devices via an asynchronous interface is
  48under development.
  49
  50Here'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    
  76Many real examples are available in the regression test module (tcrypt.c).
  77
  78
  79DEVELOPER NOTES
  80
  81Transforms may only be allocated in user context, and cryptographic
  82methods may only be called from softirq and user contexts.  For
  83transforms with a setkey method it too should only be called from
  84user context.
  85
  86When using the API for ciphers, performance will be optimal if each
  87scatterlist contains data which is a multiple of the cipher's block
  88size (typically 8 bytes).  This prevents having to do any copying
  89across non-aligned page fragment boundaries.
  90
  91
  92ADDING NEW ALGORITHMS
  93
  94When submitting a new algorithm for inclusion, a mandatory requirement
  95is that at least a few test vectors from known sources (preferably
  96standards) be included.
  97
  98Converting existing well known code is preferred, as it is more likely
  99to have been reviewed and widely tested.  If submitting code from LGPL
 100sources, please consider changing the license to GPL (see section 3 of
 101the LGPL).
 102
 103Algorithms submitted must also be generally patent-free (e.g. IDEA
 104will not be included in the mainline until around 2011), and be based
 105on a recognized standard and/or have been subjected to appropriate
 106peer review.
 107
 108Also check for any RFCs which may relate to the use of specific algorithms,
 109as well as general application notes such as RFC2451 ("The ESP CBC-Mode
 110Cipher Algorithms").
 111
 112It's a good idea to avoid using lots of macros and use inlined functions
 113instead, as gcc does a good job with inlining, while excessive use of
 114macros can cause compilation problems on some platforms.
 115
 116Also check the TODO list at the web site listed below to see what people
 117might already be working on.
 118
 119
 120BUGS
 121
 122Send bug reports to:
 123linux-crypto@vger.kernel.org
 124Cc: Herbert Xu <herbert@gondor.apana.org.au>,
 125    David S. Miller <davem@redhat.com>
 126
 127
 128FURTHER INFORMATION
 129
 130For further patches and various updates, including the current TODO
 131list, see:
 132http://gondor.apana.org.au/~herbert/crypto/
 133
 134
 135AUTHORS
 136
 137James Morris
 138David S. Miller
 139Herbert Xu
 140
 141
 142CREDITS
 143
 144The following people provided invaluable feedback during the development
 145of 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
 156Portions 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
 168and;
 169  
 170  Nettle (http://www.lysator.liu.se/~nisse/nettle/)
 171    Niels Möller
 172
 173Original 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
 189SHA1 algorithm contributors:
 190  Jean-Francois Dive
 191  
 192DES algorithm contributors:
 193  Raimar Falke
 194  Gisle Sælensminde
 195  Niels Möller
 196
 197Blowfish algorithm contributors:
 198  Herbert Valerio Riedel
 199  Kyle McMartin
 200
 201Twofish algorithm contributors:
 202  Werner Koch
 203  Marc Mutz
 204
 205SHA256/384/512 algorithm contributors:
 206  Andrew McDonald
 207  Kyle McMartin
 208  Herbert Valerio Riedel
 209  
 210AES 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
 218CAST5 algorithm contributors:
 219  Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
 220
 221TEA/XTEA algorithm contributors:
 222  Aaron Grothe
 223  Michael Ringe
 224
 225Khazad algorithm contributors:
 226  Aaron Grothe
 227
 228Whirlpool algorithm contributors:
 229  Aaron Grothe
 230  Jean-Luc Cooke
 231
 232Anubis algorithm contributors:
 233  Aaron Grothe
 234
 235Tiger algorithm contributors:
 236  Aaron Grothe
 237
 238VIA PadLock contributors:
 239  Michal Ludvig
 240
 241Camellia algorithm contributors:
 242  NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
 243
 244Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
 245
 246Please send any credits updates or corrections to:
 247Herbert Xu <herbert@gondor.apana.org.au>
 248
 249
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.