GNU Linux-libre 4.19.211-gnu1
[releases.git] / Documentation / crypto / devel-algos.rst
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
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
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.