summaryrefslogtreecommitdiff
path: root/Documentation/crypto/api-intro.rst
blob: 15201be0b8114e8030e0614418666decb2054eb0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
.. SPDX-License-Identifier: GPL-2.0

=============================
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 (https://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>