254 lines
6.2 KiB
Plaintext
254 lines
6.2 KiB
Plaintext
|
||
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) and provide an
|
||
abstraction to the underlying algorithms. 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, compress.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>
|
||
#include <linux/err.h>
|
||
#include <linux/scatterlist.h>
|
||
|
||
struct scatterlist sg[2];
|
||
char result[128];
|
||
struct crypto_hash *tfm;
|
||
struct hash_desc desc;
|
||
|
||
tfm = crypto_alloc_hash("md5", 0, CRYPTO_ALG_ASYNC);
|
||
if (IS_ERR(tfm))
|
||
fail();
|
||
|
||
/* ... set up the scatterlists ... */
|
||
|
||
desc.tfm = tfm;
|
||
desc.flags = 0;
|
||
|
||
if (crypto_hash_digest(&desc, &sg, 2, result))
|
||
fail();
|
||
|
||
crypto_free_hash(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:
|
||
Herbert Xu <herbert@gondor.apana.org.au>
|
||
Cc: David S. Miller <davem@redhat.com>
|
||
|
||
|
||
FURTHER INFORMATION
|
||
|
||
For further patches and various updates, including the current TODO
|
||
list, see:
|
||
http://gondor.apana.org.au/~herbert/crypto/
|
||
|
||
|
||
AUTHORS
|
||
|
||
James Morris
|
||
David S. Miller
|
||
Herbert Xu
|
||
|
||
|
||
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
|
||
Michael Ringe
|
||
|
||
Khazad algorithm contributors:
|
||
Aaron Grothe
|
||
|
||
Whirlpool algorithm contributors:
|
||
Aaron Grothe
|
||
Jean-Luc Cooke
|
||
|
||
Anubis algorithm contributors:
|
||
Aaron Grothe
|
||
|
||
Tiger algorithm contributors:
|
||
Aaron Grothe
|
||
|
||
VIA PadLock contributors:
|
||
Michal Ludvig
|
||
|
||
Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
|
||
|
||
Please send any credits updates or corrections to:
|
||
Herbert Xu <herbert@gondor.apana.org.au>
|
||
|