You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
248 lines
6.4 KiB
248 lines
6.4 KiB
|
|
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 five main types of transforms: AEAD (Authenticated |
|
Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and |
|
Hashes. |
|
|
|
Please note that Block Ciphers is somewhat of a misnomer. It is in fact |
|
meant to support all ciphers including stream ciphers. The difference |
|
between Block Ciphers and Ciphers is that the latter operates on exactly |
|
one block while the former can operate on an arbitrary amount of data, |
|
subject to block size requirements (i.e., non-stream ciphers can only |
|
process multiples of blocks). |
|
|
|
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). |
|
|
|
|
|
DEVELOPER NOTES |
|
|
|
Transforms may only be allocated in user context, and cryptographic |
|
methods may only be called from softirq and user contexts. For |
|
transforms with a setkey method it too should only be called from |
|
user context. |
|
|
|
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: |
|
linux-crypto@vger.kernel.org |
|
Cc: Herbert Xu <herbert@gondor.apana.org.au>, |
|
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) |
|
NTT(Nippon Telegraph and Telephone Corporation) (Camellia) |
|
|
|
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 |
|
|
|
Camellia algorithm contributors: |
|
NTT(Nippon Telegraph and Telephone Corporation) (Camellia) |
|
|
|
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> |
|
|
|
|