[deliverable/linux.git] / Documentation / crypto / api-intro.txt


                    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/)
Commit	Line	Data
1da177e4 LT	1
	2	Scatterlist Cryptographic API
	3
	4	INTRODUCTION
	5
	6	The Scatterlist Crypto API takes page vectors (scatterlists) as
	7	arguments, and works directly on pages. In some cases (e.g. ECB
	8	mode ciphers), this will allow for pages to be encrypted in-place
	9	with no copying.
	10
	11	One of the initial goals of this design was to readily support IPsec,
	12	so that processing can be applied to paged skb's without the need
	13	for linearization.
	14
	15
	16	DETAILS
	17
	18	At the lowest level are algorithms, which register dynamically with the
	19	API.
	20
	21	'Transforms' are user-instantiated objects, which maintain state, handle all
878b9014 HX	22	of the implementation logic (e.g. manipulating page vectors) and provide an
878b9014 HX	23	abstraction to the underlying algorithms. However, at the user
1da177e4 LT	24	level they are very simple.
	25
	26	Conceptually, the API layering looks like this:
	27
	28	[transform api] (user interface)
878b9014	29	[transform ops] (per-type logic glue e.g. cipher.c, compress.c)
1da177e4 LT	30	[algorithm api] (for registering algorithms)
	31
	32	The idea is to make the user interface and algorithm registration API
	33	very simple, while hiding the core logic from both. Many good ideas
	34	from existing APIs such as Cryptoapi and Nettle have been adapted for this.
	35
	36	The API currently supports three types of transforms: Ciphers, Digests and
	37	Compressors. The compression algorithms especially seem to be performing
	38	very well so far.
	39
	40	Support for hardware crypto devices via an asynchronous interface is
	41	under development.
	42
	43	Here's an example of how to use the API:
	44
	45	#include <linux/crypto.h>
878b9014 HX	46	#include <linux/err.h>
878b9014 HX	47	#include <linux/scatterlist.h>
1da177e4 LT	48
	49	struct scatterlist sg[2];
	50	char result[128];
878b9014 HX	51	struct crypto_hash *tfm;
878b9014 HX	52	struct hash_desc desc;
1da177e4	53
878b9014 HX	54	tfm = crypto_alloc_hash("md5", 0, CRYPTO_ALG_ASYNC);
878b9014 HX	55	if (IS_ERR(tfm))
1da177e4 LT	56	fail();
	57
	58	/* ... set up the scatterlists ... */
878b9014 HX	59
	60	desc.tfm = tfm;
	61	desc.flags = 0;
1da177e4	62
878b9014 HX	63	if (crypto_hash_digest(&desc, &sg, 2, result))
878b9014 HX	64	fail();
1da177e4	65
878b9014	66	crypto_free_hash(tfm);
1da177e4 LT	67
	68
	69	Many real examples are available in the regression test module (tcrypt.c).
	70
	71
	72	CONFIGURATION NOTES
	73
	74	As Triple DES is part of the DES module, for those using modular builds,
	75	add the following line to /etc/modprobe.conf:
	76
	77	alias des3_ede des
	78
	79	The Null algorithms reside in the crypto_null module, so these lines
	80	should also be added:
	81
	82	alias cipher_null crypto_null
	83	alias digest_null crypto_null
	84	alias compress_null crypto_null
	85
	86	The SHA384 algorithm shares code within the SHA512 module, so you'll
	87	also need:
	88	alias sha384 sha512
	89
	90
	91	DEVELOPER NOTES
	92
	93	Transforms may only be allocated in user context, and cryptographic
	94	methods may only be called from softirq and user contexts.
	95
	96	When using the API for ciphers, performance will be optimal if each
	97	scatterlist contains data which is a multiple of the cipher's block
	98	size (typically 8 bytes). This prevents having to do any copying
	99	across non-aligned page fragment boundaries.
	100
	101
	102	ADDING NEW ALGORITHMS
	103
	104	When submitting a new algorithm for inclusion, a mandatory requirement
	105	is that at least a few test vectors from known sources (preferably
	106	standards) be included.
	107
	108	Converting existing well known code is preferred, as it is more likely
	109	to have been reviewed and widely tested. If submitting code from LGPL
	110	sources, please consider changing the license to GPL (see section 3 of
	111	the LGPL).
	112
	113	Algorithms submitted must also be generally patent-free (e.g. IDEA
	114	will not be included in the mainline until around 2011), and be based
	115	on a recognized standard and/or have been subjected to appropriate
	116	peer review.
	117
	118	Also check for any RFCs which may relate to the use of specific algorithms,
	119	as well as general application notes such as RFC2451 ("The ESP CBC-Mode
	120	Cipher Algorithms").
	121
	122	It's a good idea to avoid using lots of macros and use inlined functions
	123	instead, as gcc does a good job with inlining, while excessive use of
	124	macros can cause compilation problems on some platforms.
	125
	126	Also check the TODO list at the web site listed below to see what people
	127	might already be working on.
	128
	129
	130	BUGS
131
132	Send bug reports to:
878b9014	133	Herbert Xu <herbert@gondor.apana.org.au>
1da177e4 LT	134	Cc: David S. Miller <davem@redhat.com>
	135
	136
	137	FURTHER INFORMATION
	138
	139	For further patches and various updates, including the current TODO
	140	list, see:
878b9014	141	http://gondor.apana.org.au/~herbert/crypto/
1da177e4 LT	142
	143
	144	AUTHORS
	145
	146	James Morris
	147	David S. Miller
878b9014	148	Herbert Xu
1da177e4 LT	149
	150
	151	CREDITS
	152
	153	The following people provided invaluable feedback during the development
	154	of the API:
	155
	156	Alexey Kuznetzov
	157	Rusty Russell
	158	Herbert Valerio Riedel
	159	Jeff Garzik
	160	Michael Richardson
	161	Andrew Morton
	162	Ingo Oeser
	163	Christoph Hellwig
	164
	165	Portions of this API were derived from the following projects:
	166
	167	Kerneli Cryptoapi (http://www.kerneli.org/)
	168	Alexander Kjeldaas
	169	Herbert Valerio Riedel
	170	Kyle McMartin
	171	Jean-Luc Cooke
	172	David Bryson
	173	Clemens Fruhwirth
	174	Tobias Ringstrom
	175	Harald Welte
	176
	177	and;
	178
	179	Nettle (http://www.lysator.liu.se/~nisse/nettle/)