Commit 5d8c723f61f2e6dacbd02d80a516115993c4f292
Committed by
Herbert Xu
1 parent
aa1b6fbcbe
Exists in
ti-lsk-linux-4.1.y
and in
10 other branches
crypto: doc - hash data structures
The hash data structures needed to be filled in by cipher developers are documented. Signed-off-by: Stephan Mueller <smueller@chronox.de> Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
Showing 1 changed file with 95 additions and 0 deletions Side-by-side Diff
include/crypto/hash.h
... | ... | @@ -17,6 +17,28 @@ |
17 | 17 | |
18 | 18 | struct crypto_ahash; |
19 | 19 | |
20 | +/** | |
21 | + * DOC: Message Digest Algorithm Definitions | |
22 | + * | |
23 | + * These data structures define modular message digest algorithm | |
24 | + * implementations, managed via crypto_register_ahash(), | |
25 | + * crypto_register_shash(), crypto_unregister_ahash() and | |
26 | + * crypto_unregister_shash(). | |
27 | + */ | |
28 | + | |
29 | +/** | |
30 | + * struct hash_alg_common - define properties of message digest | |
31 | + * @digestsize: Size of the result of the transformation. A buffer of this size | |
32 | + * must be available to the @final and @finup calls, so they can | |
33 | + * store the resulting hash into it. For various predefined sizes, | |
34 | + * search include/crypto/ using | |
35 | + * git grep _DIGEST_SIZE include/crypto. | |
36 | + * @statesize: Size of the block for partial state of the transformation. A | |
37 | + * buffer of this size must be passed to the @export function as it | |
38 | + * will save the partial state of the transformation into it. On the | |
39 | + * other side, the @import function will load the state from a | |
40 | + * buffer of this size as well. | |
41 | + */ | |
20 | 42 | struct hash_alg_common { |
21 | 43 | unsigned int digestsize; |
22 | 44 | unsigned int statesize; |
... | ... | @@ -37,6 +59,62 @@ |
37 | 59 | void *__ctx[] CRYPTO_MINALIGN_ATTR; |
38 | 60 | }; |
39 | 61 | |
62 | +/** | |
63 | + * struct ahash_alg - asynchronous message digest definition | |
64 | + * @init: Initialize the transformation context. Intended only to initialize the | |
65 | + * state of the HASH transformation at the begining. This shall fill in | |
66 | + * the internal structures used during the entire duration of the whole | |
67 | + * transformation. No data processing happens at this point. | |
68 | + * @update: Push a chunk of data into the driver for transformation. This | |
69 | + * function actually pushes blocks of data from upper layers into the | |
70 | + * driver, which then passes those to the hardware as seen fit. This | |
71 | + * function must not finalize the HASH transformation by calculating the | |
72 | + * final message digest as this only adds more data into the | |
73 | + * transformation. This function shall not modify the transformation | |
74 | + * context, as this function may be called in parallel with the same | |
75 | + * transformation object. Data processing can happen synchronously | |
76 | + * [SHASH] or asynchronously [AHASH] at this point. | |
77 | + * @final: Retrieve result from the driver. This function finalizes the | |
78 | + * transformation and retrieves the resulting hash from the driver and | |
79 | + * pushes it back to upper layers. No data processing happens at this | |
80 | + * point. | |
81 | + * @finup: Combination of @update and @final. This function is effectively a | |
82 | + * combination of @update and @final calls issued in sequence. As some | |
83 | + * hardware cannot do @update and @final separately, this callback was | |
84 | + * added to allow such hardware to be used at least by IPsec. Data | |
85 | + * processing can happen synchronously [SHASH] or asynchronously [AHASH] | |
86 | + * at this point. | |
87 | + * @digest: Combination of @init and @update and @final. This function | |
88 | + * effectively behaves as the entire chain of operations, @init, | |
89 | + * @update and @final issued in sequence. Just like @finup, this was | |
90 | + * added for hardware which cannot do even the @finup, but can only do | |
91 | + * the whole transformation in one run. Data processing can happen | |
92 | + * synchronously [SHASH] or asynchronously [AHASH] at this point. | |
93 | + * @setkey: Set optional key used by the hashing algorithm. Intended to push | |
94 | + * optional key used by the hashing algorithm from upper layers into | |
95 | + * the driver. This function can store the key in the transformation | |
96 | + * context or can outright program it into the hardware. In the former | |
97 | + * case, one must be careful to program the key into the hardware at | |
98 | + * appropriate time and one must be careful that .setkey() can be | |
99 | + * called multiple times during the existence of the transformation | |
100 | + * object. Not all hashing algorithms do implement this function as it | |
101 | + * is only needed for keyed message digests. SHAx/MDx/CRCx do NOT | |
102 | + * implement this function. HMAC(MDx)/HMAC(SHAx)/CMAC(AES) do implement | |
103 | + * this function. This function must be called before any other of the | |
104 | + * @init, @update, @final, @finup, @digest is called. No data | |
105 | + * processing happens at this point. | |
106 | + * @export: Export partial state of the transformation. This function dumps the | |
107 | + * entire state of the ongoing transformation into a provided block of | |
108 | + * data so it can be @import 'ed back later on. This is useful in case | |
109 | + * you want to save partial result of the transformation after | |
110 | + * processing certain amount of data and reload this partial result | |
111 | + * multiple times later on for multiple re-use. No data processing | |
112 | + * happens at this point. | |
113 | + * @import: Import partial state of the transformation. This function loads the | |
114 | + * entire state of the ongoing transformation from a provided block of | |
115 | + * data so the transformation can continue from this point onward. No | |
116 | + * data processing happens at this point. | |
117 | + */ | |
40 | 118 | struct ahash_alg { |
41 | 119 | int (*init)(struct ahash_request *req); |
42 | 120 | int (*update)(struct ahash_request *req); |
... | ... | @@ -63,6 +141,23 @@ |
63 | 141 | crypto_shash_descsize(ctx)] CRYPTO_MINALIGN_ATTR; \ |
64 | 142 | struct shash_desc *shash = (struct shash_desc *)__##shash##_desc |
65 | 143 | |
144 | +/** | |
145 | + * struct shash_alg - synchronous message digest definition | |
146 | + * @init: see struct ahash_alg | |
147 | + * @update: see struct ahash_alg | |
148 | + * @final: see struct ahash_alg | |
149 | + * @finup: see struct ahash_alg | |
150 | + * @digest: see struct ahash_alg | |
151 | + * @export: see struct ahash_alg | |
152 | + * @import: see struct ahash_alg | |
153 | + * @setkey: see struct ahash_alg | |
154 | + * @digestsize: see struct ahash_alg | |
155 | + * @statesize: see struct ahash_alg | |
156 | + * @dedcsize: Size of the operational state for the message digest. This state | |
157 | + * size is the memory size that needs to be allocated for | |
158 | + * shash_desc.__ctx | |
159 | + * @base: internally used | |
160 | + */ | |
66 | 161 | struct shash_alg { |
67 | 162 | int (*init)(struct shash_desc *desc); |
68 | 163 | int (*update)(struct shash_desc *desc, const u8 *data, |