summaryrefslogtreecommitdiff
path: root/Documentation/crypto/api-intro.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/crypto/api-intro.txt')
-rw-r--r--Documentation/crypto/api-intro.txt244
1 files changed, 244 insertions, 0 deletions
diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.txt
new file mode 100644
index 000000000000..a2d5b4900772
--- /dev/null
+++ b/Documentation/crypto/api-intro.txt
@@ -0,0 +1,244 @@
+
+ Scatterlist Cryptographic API
+
+INTRODUCTION
+
+The Scatterlist Crypto API takes page vectors (scatterlists) as
+arguments, and works directly on pages. In some cases (e.g. ECB
+mode ciphers), this will allow for pages to be encrypted in-place
+with no copying.
+
+One of the initial goals of this design was to readily support IPsec,
+so that processing can be applied to paged skb's without the need
+for linearization.
+
+
+DETAILS
+
+At the lowest level are algorithms, which register dynamically with the
+API.
+
+'Transforms' are user-instantiated objects, which maintain state, handle all
+of the implementation logic (e.g. manipulating page vectors), provide an
+abstraction to the underlying algorithms, and handle common logical
+operations (e.g. cipher modes, HMAC for digests). However, at the user
+level they are very simple.
+
+Conceptually, the API layering looks like this:
+
+ [transform api] (user interface)
+ [transform ops] (per-type logic glue e.g. cipher.c, digest.c)
+ [algorithm api] (for registering algorithms)
+
+The idea is to make the user interface and algorithm registration API
+very simple, while hiding the core logic from both. Many good ideas
+from existing APIs such as Cryptoapi and Nettle have been adapted for this.
+
+The API currently supports three types of transforms: Ciphers, Digests and
+Compressors. The compression algorithms especially seem to be performing
+very well so far.
+
+Support for hardware crypto devices via an asynchronous interface is
+under development.
+
+Here's an example of how to use the API:
+
+ #include <linux/crypto.h>
+
+ struct scatterlist sg[2];
+ char result[128];
+ struct crypto_tfm *tfm;
+
+ tfm = crypto_alloc_tfm("md5", 0);
+ if (tfm == NULL)
+ fail();
+
+ /* ... set up the scatterlists ... */
+
+ crypto_digest_init(tfm);
+ crypto_digest_update(tfm, &sg, 2);
+ crypto_digest_final(tfm, result);
+
+ crypto_free_tfm(tfm);
+
+
+Many real examples are available in the regression test module (tcrypt.c).
+
+
+CONFIGURATION NOTES
+
+As Triple DES is part of the DES module, for those using modular builds,
+add the following line to /etc/modprobe.conf:
+
+ alias des3_ede des
+
+The Null algorithms reside in the crypto_null module, so these lines
+should also be added:
+
+ alias cipher_null crypto_null
+ alias digest_null crypto_null
+ alias compress_null crypto_null
+
+The SHA384 algorithm shares code within the SHA512 module, so you'll
+also need:
+ alias sha384 sha512
+
+
+DEVELOPER NOTES
+
+Transforms may only be allocated in user context, and cryptographic
+methods may only be called from softirq and user contexts.
+
+When using the API for ciphers, performance will be optimal if each
+scatterlist contains data which is a multiple of the cipher's block
+size (typically 8 bytes). This prevents having to do any copying
+across non-aligned page fragment boundaries.
+
+
+ADDING NEW ALGORITHMS
+
+When submitting a new algorithm for inclusion, a mandatory requirement
+is that at least a few test vectors from known sources (preferably
+standards) be included.
+
+Converting existing well known code is preferred, as it is more likely
+to have been reviewed and widely tested. If submitting code from LGPL
+sources, please consider changing the license to GPL (see section 3 of
+the LGPL).
+
+Algorithms submitted must also be generally patent-free (e.g. IDEA
+will not be included in the mainline until around 2011), and be based
+on a recognized standard and/or have been subjected to appropriate
+peer review.
+
+Also check for any RFCs which may relate to the use of specific algorithms,
+as well as general application notes such as RFC2451 ("The ESP CBC-Mode
+Cipher Algorithms").
+
+It's a good idea to avoid using lots of macros and use inlined functions
+instead, as gcc does a good job with inlining, while excessive use of
+macros can cause compilation problems on some platforms.
+
+Also check the TODO list at the web site listed below to see what people
+might already be working on.
+
+
+BUGS
+
+Send bug reports to:
+James Morris <jmorris@redhat.com>
+Cc: David S. Miller <davem@redhat.com>
+
+
+FURTHER INFORMATION
+
+For further patches and various updates, including the current TODO
+list, see:
+http://samba.org/~jamesm/crypto/
+
+
+AUTHORS
+
+James Morris
+David S. Miller
+
+
+CREDITS
+
+The following people provided invaluable feedback during the development
+of the API:
+
+ Alexey Kuznetzov
+ Rusty Russell
+ Herbert Valerio Riedel
+ Jeff Garzik
+ Michael Richardson
+ Andrew Morton
+ Ingo Oeser
+ Christoph Hellwig
+
+Portions of this API were derived from the following projects:
+
+ Kerneli Cryptoapi (http://www.kerneli.org/)
+ Alexander Kjeldaas
+ Herbert Valerio Riedel
+ Kyle McMartin
+ Jean-Luc Cooke
+ David Bryson
+ Clemens Fruhwirth
+ Tobias Ringstrom
+ Harald Welte
+
+and;
+
+ Nettle (http://www.lysator.liu.se/~nisse/nettle/)
+ Niels Möller
+
+Original developers of the crypto algorithms:
+
+ Dana L. How (DES)
+ Andrew Tridgell and Steve French (MD4)
+ Colin Plumb (MD5)
+ Steve Reid (SHA1)
+ Jean-Luc Cooke (SHA256, SHA384, SHA512)
+ Kazunori Miyazawa / USAGI (HMAC)
+ Matthew Skala (Twofish)
+ Dag Arne Osvik (Serpent)
+ Brian Gladman (AES)
+ Kartikey Mahendra Bhatt (CAST6)
+ Jon Oberheide (ARC4)
+ Jouni Malinen (Michael MIC)
+
+SHA1 algorithm contributors:
+ Jean-Francois Dive
+
+DES algorithm contributors:
+ Raimar Falke
+ Gisle Sælensminde
+ Niels Möller
+
+Blowfish algorithm contributors:
+ Herbert Valerio Riedel
+ Kyle McMartin
+
+Twofish algorithm contributors:
+ Werner Koch
+ Marc Mutz
+
+SHA256/384/512 algorithm contributors:
+ Andrew McDonald
+ Kyle McMartin
+ Herbert Valerio Riedel
+
+AES algorithm contributors:
+ Alexander Kjeldaas
+ Herbert Valerio Riedel
+ Kyle McMartin
+ Adam J. Richter
+ Fruhwirth Clemens (i586)
+ Linus Torvalds (i586)
+
+CAST5 algorithm contributors:
+ Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
+
+TEA/XTEA algorithm contributors:
+ Aaron Grothe
+
+Khazad algorithm contributors:
+ Aaron Grothe
+
+Whirlpool algorithm contributors:
+ Aaron Grothe
+ Jean-Luc Cooke
+
+Anubis algorithm contributors:
+ Aaron Grothe
+
+Tiger algorithm contributors:
+ Aaron Grothe
+
+Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
+
+Please send any credits updates or corrections to:
+James Morris <jmorris@redhat.com>
+