Subversion Repositories or1k

                    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 

        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/modules.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 

Cc: David S. Miller 

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)

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

CAST5/CAST6 algorithm contributors:

  Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).

Generic scatterwalk code by Adam J. Richter 

Please send any credits updates or corrections to:

James Morris