Scatterlist Cryptographic API

Introduction

The Scatterlist Crypto API takes page vectors (scatterlists) asarguments, and works directly on pages. In some cases (e.g. ECBmode ciphers), this will allow for pages to be encrypted in-placewith 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 needfor linearization.

Details

At the lowest level are algorithms, which register dynamically with theAPI.

‘Transforms’ are user-instantiated objects, which maintain state, handle allof the implementation logic (e.g. manipulating page vectors) and provide anabstraction to the underlying algorithms. However, at the userlevel 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 APIvery simple, while hiding the core logic from both. Many good ideasfrom existing APIs such as Cryptoapi and Nettle have been adapted for this.

The API currently supports five main types of transforms: AEAD (AuthenticatedEncryption with Associated Data), Block Ciphers, Ciphers, Compressors andHashes.

Please note that Block Ciphers is somewhat of a misnomer. It is in factmeant to support all ciphers including stream ciphers. The differencebetween Block Ciphers and Ciphers is that the latter operates on exactlyone block while the former can operate on an arbitrary amount of data,subject to block size requirements (i.e., non-stream ciphers can onlyprocess multiples of blocks).

Here’s an example of how to use the API:

#include <crypto/hash.h>#include <linux/err.h>#include <linux/scatterlist.h>struct scatterlist sg[2];char result[128];struct crypto_ahash *tfm;struct ahash_request *req;tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);if (IS_ERR(tfm))        fail();/* ... set up the scatterlists ... */req = ahash_request_alloc(tfm, GFP_ATOMIC);if (!req)        fail();ahash_request_set_callback(req, 0, NULL, NULL);ahash_request_set_crypt(req, sg, result, 2);if (crypto_ahash_digest(req))        fail();ahash_request_free(req);crypto_free_ahash(tfm);

Many real examples are available in the regression test module (tcrypt.c).

Developer Notes

Transforms may only be allocated in user context, and cryptographicmethods may only be called from softirq and user contexts. Fortransforms with a setkey method it too should only be called fromuser context.

When using the API for ciphers, performance will be optimal if eachscatterlist contains data which is a multiple of the cipher’s blocksize (typically 8 bytes). This prevents having to do any copyingacross non-aligned page fragment boundaries.

Adding New Algorithms

When submitting a new algorithm for inclusion, a mandatory requirementis that at least a few test vectors from known sources (preferablystandards) be included.

Converting existing well known code is preferred, as it is more likelyto have been reviewed and widely tested. If submitting code from LGPLsources, please consider changing the license to GPL (see section 3 ofthe LGPL).

Algorithms submitted must also be generally patent-free (e.g. IDEAwill not be included in the mainline until around 2011), and be basedon a recognized standard and/or have been subjected to appropriatepeer 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-ModeCipher Algorithms”).

It’s a good idea to avoid using lots of macros and use inlined functionsinstead, as gcc does a good job with inlining, while excessive use ofmacros can cause compilation problems on some platforms.

Also check the TODO list at the web site listed below to see what peoplemight 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 TODOlist, 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 developmentof 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;

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>