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