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