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