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