1Developing Cipher Algorithms 2============================ 3 4Registering And Unregistering Transformation 5-------------------------------------------- 6 7There are three distinct types of registration functions in the Crypto 8API. One is used to register a generic cryptographic transformation, 9while the other two are specific to HASH transformations and 10COMPRESSion. We will discuss the latter two in a separate chapter, here 11we will only look at the generic ones. 12 13Before discussing the register functions, the data structure to be 14filled with each, struct crypto_alg, must be considered -- see below 15for a description of this data structure. 16 17The generic registration functions can be found in 18include/linux/crypto.h and their definition can be seen below. The 19former function registers a single transformation, while the latter 20works on an array of transformation descriptions. The latter is useful 21when registering transformations in bulk, for example when a driver 22implements 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 30The 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 38Notice that both registration and unregistration functions do return a 39value, so make sure to handle errors. A return code of zero implies 40success. Any return code < 0 implies an error. 41 42The bulk registration/unregistration functions register/unregister each 43transformation in the given array of length count. They handle errors as 44follows: 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 57Single-Block Symmetric Ciphers [CIPHER] 58--------------------------------------- 59 60Example of transformations: aes, arc4, ... 61 62This section describes the simplest of all transformation 63implementations, that being the CIPHER type used for symmetric ciphers. 64The CIPHER type is used for transformations which operate on exactly one 65block at a time and there are no dependencies between blocks at all. 66 67Registration specifics 68~~~~~~~~~~~~~~~~~~~~~~ 69 70The registration of [CIPHER] algorithm is specific in that struct 71crypto_alg field .cra_type is empty. The .cra_u.cipher has to be 72filled in with proper callbacks to implement this transformation. 73 74See struct cipher_alg below. 75 76Cipher Definition With struct cipher_alg 77~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 78 79Struct cipher_alg defines a single block cipher. 80 81Here are schematics of how these functions are called when operated from 82other part of the kernel. Note that the .cia_setkey() call might happen 83before or after any of these schematics happen, but must not happen 84during 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 95Please note that a pattern where .cia_setkey() is called multiple times 96is 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 108Multi-Block Ciphers 109------------------- 110 111Example of transformations: cbc(aes), ecb(arc4), ... 112 113This section describes the multi-block cipher transformation 114implementations. The multi-block ciphers are used for transformations 115which operate on scatterlists of data supplied to the transformation 116functions. They output the result into a scatterlist of data as well. 117 118Registration Specifics 119~~~~~~~~~~~~~~~~~~~~~~ 120 121The registration of multi-block cipher algorithms is one of the most 122standard procedures throughout the crypto API. 123 124Note, if a cipher implementation requires a proper alignment of data, 125the caller should use the functions of crypto_skcipher_alignmask() to 126identify a memory alignment mask. The kernel crypto API is able to 127process requests that are unaligned. This implies, however, additional 128overhead as the kernel crypto API needs to perform the realignment of 129the data which may imply moving of data. 130 131Cipher Definition With struct blkcipher_alg and ablkcipher_alg 132~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 133 134Struct blkcipher_alg defines a synchronous block cipher whereas struct 135ablkcipher_alg defines an asynchronous block cipher. 136 137Please refer to the single block cipher description for schematics of 138the block cipher usage. 139 140Specifics Of Asynchronous Multi-Block Cipher 141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 142 143There are a couple of specifics to the asynchronous interface. 144 145First of all, some of the drivers will want to use the Generic 146ScatterWalk in case the hardware needs to be fed separate chunks of the 147scatterlist which contains the plaintext and will contain the 148ciphertext. Please refer to the ScatterWalk interface offered by the 149Linux kernel scatter / gather list implementation. 150 151Hashing [HASH] 152-------------- 153 154Example of transformations: crc32, md5, sha1, sha256,... 155 156Registering And Unregistering The Transformation 157~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 158 159There are multiple ways to register a HASH transformation, depending on 160whether the transformation is synchronous [SHASH] or asynchronous 161[AHASH] and the amount of HASH transformations we are registering. You 162can 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 172The respective counterparts for unregistering the HASH transformation 173are 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 183Cipher Definition With struct shash_alg and ahash_alg 184~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 185 186Here are schematics of how these functions are called when operated from 187other part of the kernel. Note that the .setkey() call might happen 188before or after any of these schematics happen, but must not happen 189during any of these are in-flight. Please note that calling .init() 190followed immediately by .finish() is also a perfectly valid 191transformation. 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 214Here is a schematic of how the .export()/.import() functions are called 215when 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 239Note 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 243In other words implementations should mind the resource allocation and clean-up. 244No resources related to request objects should remain allocated after a call 245to .init() or .update(), since there might be no chance to free them. 246 247 248Specifics Of Asynchronous HASH Transformation 249~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 250 251Some of the drivers will want to use the Generic ScatterWalk in case the 252implementation needs to be fed separate chunks of the scatterlist which 253contains the input data. The buffer containing the resulting hash will 254always be properly aligned to .cra_alignmask so there is no need to 255worry about this. 256