Documentation/crypto/api-intro.txt - arm/linux - Git at Google


                     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).

 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 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>

	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).

	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 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>