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.