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 blkcipher_alg and ablkcipher_alg
122 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ !! 132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
123 133
124 Struct skcipher_alg defines a multi-block ciph !! 134 Struct blkcipher_alg defines a synchronous block cipher whereas struct
125 length-preserving symmetric cipher algorithm. !! 135 ablkcipher_alg defines an asynchronous block cipher.
126 136
127 Scatterlist handling !! 137 Please refer to the single block cipher description for schematics of
128 ~~~~~~~~~~~~~~~~~~~~ !! 138 the block cipher usage.
129 139
130 Some drivers will want to use the Generic Scat !! 140 Specifics Of Asynchronous Multi-Block Cipher
131 hardware needs to be fed separate chunks of th !! 141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
132 contains the plaintext and will contain the ci !! 142
133 to the ScatterWalk interface offered by the Li !! 143 There are a couple of specifics to the asynchronous interface.
134 gather list implementation. !! 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.
135 150
136 Hashing [HASH] 151 Hashing [HASH]
137 -------------- 152 --------------
138 153
139 Example of transformations: crc32, md5, sha1, 154 Example of transformations: crc32, md5, sha1, sha256,...
140 155
141 Registering And Unregistering The Transformati 156 Registering And Unregistering The Transformation
142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 157 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
143 158
144 There are multiple ways to register a HASH tra 159 There are multiple ways to register a HASH transformation, depending on
145 whether the transformation is synchronous [SHA 160 whether the transformation is synchronous [SHASH] or asynchronous
146 [AHASH] and the amount of HASH transformations 161 [AHASH] and the amount of HASH transformations we are registering. You
147 can find the prototypes defined in include/cry 162 can find the prototypes defined in include/crypto/internal/hash.h:
148 163
149 :: 164 ::
150 165
151 int crypto_register_ahash(struct ahash_ 166 int crypto_register_ahash(struct ahash_alg *alg);
152 167
153 int crypto_register_shash(struct shash_ 168 int crypto_register_shash(struct shash_alg *alg);
154 int crypto_register_shashes(struct shas 169 int crypto_register_shashes(struct shash_alg *algs, int count);
155 170
156 171
157 The respective counterparts for unregistering 172 The respective counterparts for unregistering the HASH transformation
158 are as follows: 173 are as follows:
159 174
160 :: 175 ::
161 176
162 void crypto_unregister_ahash(struct aha !! 177 int crypto_unregister_ahash(struct ahash_alg *alg);
163 178
164 void crypto_unregister_shash(struct sha !! 179 int crypto_unregister_shash(struct shash_alg *alg);
165 void crypto_unregister_shashes(struct s !! 180 int crypto_unregister_shashes(struct shash_alg *algs, int count);
166 181
167 182
168 Cipher Definition With struct shash_alg and ah 183 Cipher Definition With struct shash_alg and ahash_alg
169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 184 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
170 185
171 Here are schematics of how these functions are 186 Here are schematics of how these functions are called when operated from
172 other part of the kernel. Note that the .setke 187 other part of the kernel. Note that the .setkey() call might happen
173 before or after any of these schematics happen 188 before or after any of these schematics happen, but must not happen
174 during any of these are in-flight. Please note 189 during any of these are in-flight. Please note that calling .init()
175 followed immediately by .final() is also a per !! 190 followed immediately by .finish() is also a perfectly valid
176 transformation. 191 transformation.
177 192
178 :: 193 ::
179 194
180 I) DATA -----------. 195 I) DATA -----------.
181 v 196 v
182 .init() -> .update() -> .final() 197 .init() -> .update() -> .final() ! .update() might not be called
183 ^ | | 198 ^ | | at all in this scenario.
184 '----' '---> 199 '----' '---> HASH
185 200
186 II) DATA -----------.-----------. 201 II) DATA -----------.-----------.
187 v v 202 v v
188 .init() -> .update() -> .finup() 203 .init() -> .update() -> .finup() ! .update() may not be called
189 ^ | | 204 ^ | | at all in this scenario.
190 '----' '---> 205 '----' '---> HASH
191 206
192 III) DATA -----------. 207 III) DATA -----------.
193 v 208 v
194 .digest() 209 .digest() ! The entire process is handled
195 | 210 | by the .digest() call.
196 '---------------> 211 '---------------> HASH
197 212
198 213
199 Here is a schematic of how the .export()/.impo 214 Here is a schematic of how the .export()/.import() functions are called
200 when used from another part of the kernel. 215 when used from another part of the kernel.
201 216
202 :: 217 ::
203 218
204 KEY--. DATA--. 219 KEY--. DATA--.
205 v v 220 v v ! .update() may not be called
206 .setkey() -> .init() -> .update() -> . 221 .setkey() -> .init() -> .update() -> .export() at all in this scenario.
207 ^ | 222 ^ | |
208 '-----' 223 '-----' '--> PARTIAL_HASH
209 224
210 ----------- other transformations happe 225 ----------- other transformations happen here -----------
211 226
212 PARTIAL_HASH--. DATA1--. 227 PARTIAL_HASH--. DATA1--.
213 v v 228 v v
214 .import -> .update() -> .fina 229 .import -> .update() -> .final() ! .update() may not be called
215 ^ | | 230 ^ | | at all in this scenario.
216 '----' '- 231 '----' '--> HASH1
217 232
218 PARTIAL_HASH--. DATA2-. 233 PARTIAL_HASH--. DATA2-.
219 v v 234 v v
220 .import -> .finup() 235 .import -> .finup()
221 | 236 |
222 '-------------- 237 '---------------> HASH2
223 238
224 Note that it is perfectly legal to "abandon" a 239 Note that it is perfectly legal to "abandon" a request object:
225 - call .init() and then (as many times) .updat 240 - call .init() and then (as many times) .update()
226 - _not_ call any of .final(), .finup() or .exp 241 - _not_ call any of .final(), .finup() or .export() at any point in future
227 242
228 In other words implementations should mind the 243 In other words implementations should mind the resource allocation and clean-up.
229 No resources related to request objects should 244 No resources related to request objects should remain allocated after a call
230 to .init() or .update(), since there might be 245 to .init() or .update(), since there might be no chance to free them.
231 246
232 247
233 Specifics Of Asynchronous HASH Transformation 248 Specifics Of Asynchronous HASH Transformation
234 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 249 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
235 250
236 Some of the drivers will want to use the Gener 251 Some of the drivers will want to use the Generic ScatterWalk in case the
237 implementation needs to be fed separate chunks 252 implementation needs to be fed separate chunks of the scatterlist which
238 contains the input data. !! 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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.