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