Commit | Line | Data |
---|---|---|
3b72c814 SM |
1 | Developing Cipher Algorithms |
2 | ============================ | |
3 | ||
4 | Registering And Unregistering Transformation | |
5 | -------------------------------------------- | |
6 | ||
7 | There are three distinct types of registration functions in the Crypto | |
8 | API. One is used to register a generic cryptographic transformation, | |
9 | while the other two are specific to HASH transformations and | |
10 | COMPRESSion. We will discuss the latter two in a separate chapter, here | |
11 | we will only look at the generic ones. | |
12 | ||
13 | Before discussing the register functions, the data structure to be | |
14 | filled with each, struct crypto_alg, must be considered -- see below | |
15 | for a description of this data structure. | |
16 | ||
17 | The generic registration functions can be found in | |
18 | include/linux/crypto.h and their definition can be seen below. The | |
19 | former function registers a single transformation, while the latter | |
20 | works on an array of transformation descriptions. The latter is useful | |
21 | when registering transformations in bulk, for example when a driver | |
22 | implements multiple transformations. | |
23 | ||
24 | :: | |
25 | ||
26 | int crypto_register_alg(struct crypto_alg *alg); | |
27 | int crypto_register_algs(struct crypto_alg *algs, int count); | |
28 | ||
29 | ||
30 | The counterparts to those functions are listed below. | |
31 | ||
32 | :: | |
33 | ||
34 | int crypto_unregister_alg(struct crypto_alg *alg); | |
35 | int crypto_unregister_algs(struct crypto_alg *algs, int count); | |
36 | ||
37 | ||
38 | Notice that both registration and unregistration functions do return a | |
39 | value, so make sure to handle errors. A return code of zero implies | |
40 | success. Any return code < 0 implies an error. | |
41 | ||
42 | The bulk registration/unregistration functions register/unregister each | |
43 | transformation in the given array of length count. They handle errors as | |
44 | follows: | |
45 | ||
46 | - crypto_register_algs() succeeds if and only if it successfully | |
47 | registers all the given transformations. If an error occurs partway | |
48 | through, then it rolls back successful registrations before returning | |
49 | the error code. Note that if a driver needs to handle registration | |
50 | errors for individual transformations, then it will need to use the | |
51 | non-bulk function crypto_register_alg() instead. | |
52 | ||
53 | - crypto_unregister_algs() tries to unregister all the given | |
54 | transformations, continuing on error. It logs errors and always | |
55 | returns zero. | |
56 | ||
57 | Single-Block Symmetric Ciphers [CIPHER] | |
58 | --------------------------------------- | |
59 | ||
60 | Example of transformations: aes, arc4, ... | |
61 | ||
62 | This section describes the simplest of all transformation | |
63 | implementations, that being the CIPHER type used for symmetric ciphers. | |
64 | The CIPHER type is used for transformations which operate on exactly one | |
65 | block at a time and there are no dependencies between blocks at all. | |
66 | ||
67 | Registration specifics | |
68 | ~~~~~~~~~~~~~~~~~~~~~~ | |
69 | ||
70 | The registration of [CIPHER] algorithm is specific in that struct | |
71 | crypto_alg field .cra_type is empty. The .cra_u.cipher has to be | |
72 | filled in with proper callbacks to implement this transformation. | |
73 | ||
74 | See struct cipher_alg below. | |
75 | ||
76 | Cipher Definition With struct cipher_alg | |
77 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
78 | ||
79 | Struct cipher_alg defines a single block cipher. | |
80 | ||
81 | Here are schematics of how these functions are called when operated from | |
82 | other part of the kernel. Note that the .cia_setkey() call might happen | |
83 | before or after any of these schematics happen, but must not happen | |
84 | during any of these are in-flight. | |
85 | ||
86 | :: | |
87 | ||
88 | KEY ---. PLAINTEXT ---. | |
89 | v v | |
90 | .cia_setkey() -> .cia_encrypt() | |
91 | | | |
92 | '-----> CIPHERTEXT | |
93 | ||
94 | ||
95 | Please note that a pattern where .cia_setkey() is called multiple times | |
96 | is also valid: | |
97 | ||
98 | :: | |
99 | ||
100 | ||
101 | KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --. | |
102 | v v v v | |
103 | .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt() | |
104 | | | | |
105 | '---> CIPHERTEXT1 '---> CIPHERTEXT2 | |
106 | ||
107 | ||
108 | Multi-Block Ciphers | |
109 | ------------------- | |
110 | ||
111 | Example of transformations: cbc(aes), ecb(arc4), ... | |
112 | ||
113 | This section describes the multi-block cipher transformation | |
114 | implementations. The multi-block ciphers are used for transformations | |
115 | which operate on scatterlists of data supplied to the transformation | |
116 | functions. They output the result into a scatterlist of data as well. | |
117 | ||
118 | Registration Specifics | |
119 | ~~~~~~~~~~~~~~~~~~~~~~ | |
120 | ||
121 | The registration of multi-block cipher algorithms is one of the most | |
122 | standard procedures throughout the crypto API. | |
123 | ||
124 | Note, if a cipher implementation requires a proper alignment of data, | |
125 | the caller should use the functions of crypto_skcipher_alignmask() to | |
126 | identify a memory alignment mask. The kernel crypto API is able to | |
127 | process requests that are unaligned. This implies, however, additional | |
128 | overhead as the kernel crypto API needs to perform the realignment of | |
129 | the data which may imply moving of data. | |
130 | ||
131 | Cipher Definition With struct blkcipher_alg and ablkcipher_alg | |
132 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
133 | ||
134 | Struct blkcipher_alg defines a synchronous block cipher whereas struct | |
135 | ablkcipher_alg defines an asynchronous block cipher. | |
136 | ||
137 | Please refer to the single block cipher description for schematics of | |
138 | the block cipher usage. | |
139 | ||
140 | Specifics Of Asynchronous Multi-Block Cipher | |
141 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
142 | ||
143 | There are a couple of specifics to the asynchronous interface. | |
144 | ||
145 | First of all, some of the drivers will want to use the Generic | |
146 | ScatterWalk in case the hardware needs to be fed separate chunks of the | |
147 | scatterlist which contains the plaintext and will contain the | |
148 | ciphertext. Please refer to the ScatterWalk interface offered by the | |
149 | Linux kernel scatter / gather list implementation. | |
150 | ||
151 | Hashing [HASH] | |
152 | -------------- | |
153 | ||
154 | Example of transformations: crc32, md5, sha1, sha256,... | |
155 | ||
156 | Registering And Unregistering The Transformation | |
157 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
158 | ||
159 | There are multiple ways to register a HASH transformation, depending on | |
160 | whether the transformation is synchronous [SHASH] or asynchronous | |
161 | [AHASH] and the amount of HASH transformations we are registering. You | |
162 | can find the prototypes defined in include/crypto/internal/hash.h: | |
163 | ||
164 | :: | |
165 | ||
166 | int crypto_register_ahash(struct ahash_alg *alg); | |
167 | ||
168 | int crypto_register_shash(struct shash_alg *alg); | |
169 | int crypto_register_shashes(struct shash_alg *algs, int count); | |
170 | ||
171 | ||
172 | The respective counterparts for unregistering the HASH transformation | |
173 | are as follows: | |
174 | ||
175 | :: | |
176 | ||
177 | int crypto_unregister_ahash(struct ahash_alg *alg); | |
178 | ||
179 | int crypto_unregister_shash(struct shash_alg *alg); | |
180 | int crypto_unregister_shashes(struct shash_alg *algs, int count); | |
181 | ||
182 | ||
183 | Cipher Definition With struct shash_alg and ahash_alg | |
184 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
185 | ||
186 | Here are schematics of how these functions are called when operated from | |
187 | other part of the kernel. Note that the .setkey() call might happen | |
188 | before or after any of these schematics happen, but must not happen | |
189 | during any of these are in-flight. Please note that calling .init() | |
190 | followed immediately by .finish() is also a perfectly valid | |
191 | transformation. | |
192 | ||
193 | :: | |
194 | ||
195 | I) DATA -----------. | |
196 | v | |
197 | .init() -> .update() -> .final() ! .update() might not be called | |
198 | ^ | | at all in this scenario. | |
199 | '----' '---> HASH | |
200 | ||
201 | II) DATA -----------.-----------. | |
202 | v v | |
203 | .init() -> .update() -> .finup() ! .update() may not be called | |
204 | ^ | | at all in this scenario. | |
205 | '----' '---> HASH | |
206 | ||
207 | III) DATA -----------. | |
208 | v | |
209 | .digest() ! The entire process is handled | |
210 | | by the .digest() call. | |
211 | '---------------> HASH | |
212 | ||
213 | ||
214 | Here is a schematic of how the .export()/.import() functions are called | |
215 | when used from another part of the kernel. | |
216 | ||
217 | :: | |
218 | ||
219 | KEY--. DATA--. | |
220 | v v ! .update() may not be called | |
221 | .setkey() -> .init() -> .update() -> .export() at all in this scenario. | |
222 | ^ | | | |
223 | '-----' '--> PARTIAL_HASH | |
224 | ||
225 | ----------- other transformations happen here ----------- | |
226 | ||
227 | PARTIAL_HASH--. DATA1--. | |
228 | v v | |
229 | .import -> .update() -> .final() ! .update() may not be called | |
230 | ^ | | at all in this scenario. | |
231 | '----' '--> HASH1 | |
232 | ||
233 | PARTIAL_HASH--. DATA2-. | |
234 | v v | |
235 | .import -> .finup() | |
236 | | | |
237 | '---------------> HASH2 | |
238 | ||
0550f5a5 HG |
239 | Note that it is perfectly legal to "abandon" a request object: |
240 | - call .init() and then (as many times) .update() | |
241 | - _not_ call any of .final(), .finup() or .export() at any point in future | |
242 | ||
243 | In other words implementations should mind the resource allocation and clean-up. | |
244 | No resources related to request objects should remain allocated after a call | |
245 | to .init() or .update(), since there might be no chance to free them. | |
246 | ||
3b72c814 SM |
247 | |
248 | Specifics Of Asynchronous HASH Transformation | |
249 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
250 | ||
251 | Some of the drivers will want to use the Generic ScatterWalk in case the | |
252 | implementation needs to be fed separate chunks of the scatterlist which | |
253 | contains the input data. The buffer containing the resulting hash will | |
254 | always be properly aligned to .cra_alignmask so there is no need to | |
255 | worry about this. |