~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/crypto/devel-algos.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/crypto/devel-algos.rst (Version linux-6.12-rc7) and /Documentation/crypto/devel-algos.rst (Version linux-6.0.19)


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

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php