crypto: doc - hash data structures
[linux-block.git] / include / crypto / hash.h
CommitLineData
18e33e6d
HX
1/*
2 * Hash: Hash algorithms under the crypto API
3 *
4 * Copyright (c) 2008 Herbert Xu <herbert@gondor.apana.org.au>
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the Free
8 * Software Foundation; either version 2 of the License, or (at your option)
9 * any later version.
10 *
11 */
12
13#ifndef _CRYPTO_HASH_H
14#define _CRYPTO_HASH_H
15
16#include <linux/crypto.h>
17
88056ec3
HX
18struct crypto_ahash;
19
5d8c723f
SM
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 */
88056ec3
HX
42struct hash_alg_common {
43 unsigned int digestsize;
44 unsigned int statesize;
45
46 struct crypto_alg base;
47};
48
49struct ahash_request {
50 struct crypto_async_request base;
51
52 unsigned int nbytes;
53 struct scatterlist *src;
54 u8 *result;
55
66f6ce5e
HX
56 /* This field may only be used by the ahash API code. */
57 void *priv;
58
88056ec3
HX
59 void *__ctx[] CRYPTO_MINALIGN_ATTR;
60};
61
5d8c723f
SM
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 */
88056ec3
HX
118struct ahash_alg {
119 int (*init)(struct ahash_request *req);
120 int (*update)(struct ahash_request *req);
121 int (*final)(struct ahash_request *req);
122 int (*finup)(struct ahash_request *req);
123 int (*digest)(struct ahash_request *req);
124 int (*export)(struct ahash_request *req, void *out);
125 int (*import)(struct ahash_request *req, const void *in);
126 int (*setkey)(struct crypto_ahash *tfm, const u8 *key,
127 unsigned int keylen);
128
129 struct hash_alg_common halg;
130};
131
7b5a080b
HX
132struct shash_desc {
133 struct crypto_shash *tfm;
134 u32 flags;
135
136 void *__ctx[] CRYPTO_MINALIGN_ATTR;
137};
138
a0a77af1
BW
139#define SHASH_DESC_ON_STACK(shash, ctx) \
140 char __##shash##_desc[sizeof(struct shash_desc) + \
141 crypto_shash_descsize(ctx)] CRYPTO_MINALIGN_ATTR; \
142 struct shash_desc *shash = (struct shash_desc *)__##shash##_desc
143
5d8c723f
SM
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 */
7b5a080b
HX
161struct shash_alg {
162 int (*init)(struct shash_desc *desc);
163 int (*update)(struct shash_desc *desc, const u8 *data,
164 unsigned int len);
165 int (*final)(struct shash_desc *desc, u8 *out);
166 int (*finup)(struct shash_desc *desc, const u8 *data,
167 unsigned int len, u8 *out);
168 int (*digest)(struct shash_desc *desc, const u8 *data,
169 unsigned int len, u8 *out);
99d27e1c
HX
170 int (*export)(struct shash_desc *desc, void *out);
171 int (*import)(struct shash_desc *desc, const void *in);
7b5a080b
HX
172 int (*setkey)(struct crypto_shash *tfm, const u8 *key,
173 unsigned int keylen);
174
175 unsigned int descsize;
88056ec3
HX
176
177 /* These fields must match hash_alg_common. */
fa649664
HX
178 unsigned int digestsize
179 __attribute__ ((aligned(__alignof__(struct hash_alg_common))));
99d27e1c 180 unsigned int statesize;
7b5a080b
HX
181
182 struct crypto_alg base;
183};
184
18e33e6d 185struct crypto_ahash {
88056ec3
HX
186 int (*init)(struct ahash_request *req);
187 int (*update)(struct ahash_request *req);
188 int (*final)(struct ahash_request *req);
189 int (*finup)(struct ahash_request *req);
190 int (*digest)(struct ahash_request *req);
191 int (*export)(struct ahash_request *req, void *out);
192 int (*import)(struct ahash_request *req, const void *in);
193 int (*setkey)(struct crypto_ahash *tfm, const u8 *key,
194 unsigned int keylen);
195
88056ec3 196 unsigned int reqsize;
18e33e6d
HX
197 struct crypto_tfm base;
198};
199
7b5a080b 200struct crypto_shash {
113adefc 201 unsigned int descsize;
7b5a080b
HX
202 struct crypto_tfm base;
203};
204
18e33e6d
HX
205static inline struct crypto_ahash *__crypto_ahash_cast(struct crypto_tfm *tfm)
206{
88056ec3 207 return container_of(tfm, struct crypto_ahash, base);
18e33e6d
HX
208}
209
88056ec3
HX
210struct crypto_ahash *crypto_alloc_ahash(const char *alg_name, u32 type,
211 u32 mask);
18e33e6d
HX
212
213static inline struct crypto_tfm *crypto_ahash_tfm(struct crypto_ahash *tfm)
214{
215 return &tfm->base;
216}
217
218static inline void crypto_free_ahash(struct crypto_ahash *tfm)
219{
88056ec3 220 crypto_destroy_tfm(tfm, crypto_ahash_tfm(tfm));
18e33e6d
HX
221}
222
223static inline unsigned int crypto_ahash_alignmask(
224 struct crypto_ahash *tfm)
225{
226 return crypto_tfm_alg_alignmask(crypto_ahash_tfm(tfm));
227}
228
88056ec3
HX
229static inline struct hash_alg_common *__crypto_hash_alg_common(
230 struct crypto_alg *alg)
231{
232 return container_of(alg, struct hash_alg_common, base);
233}
234
235static inline struct hash_alg_common *crypto_hash_alg_common(
236 struct crypto_ahash *tfm)
18e33e6d 237{
88056ec3 238 return __crypto_hash_alg_common(crypto_ahash_tfm(tfm)->__crt_alg);
18e33e6d
HX
239}
240
241static inline unsigned int crypto_ahash_digestsize(struct crypto_ahash *tfm)
242{
500b3e3c 243 return crypto_hash_alg_common(tfm)->digestsize;
88056ec3
HX
244}
245
246static inline unsigned int crypto_ahash_statesize(struct crypto_ahash *tfm)
247{
248 return crypto_hash_alg_common(tfm)->statesize;
18e33e6d
HX
249}
250
251static inline u32 crypto_ahash_get_flags(struct crypto_ahash *tfm)
252{
253 return crypto_tfm_get_flags(crypto_ahash_tfm(tfm));
254}
255
256static inline void crypto_ahash_set_flags(struct crypto_ahash *tfm, u32 flags)
257{
258 crypto_tfm_set_flags(crypto_ahash_tfm(tfm), flags);
259}
260
261static inline void crypto_ahash_clear_flags(struct crypto_ahash *tfm, u32 flags)
262{
263 crypto_tfm_clear_flags(crypto_ahash_tfm(tfm), flags);
264}
265
266static inline struct crypto_ahash *crypto_ahash_reqtfm(
267 struct ahash_request *req)
268{
269 return __crypto_ahash_cast(req->base.tfm);
270}
271
272static inline unsigned int crypto_ahash_reqsize(struct crypto_ahash *tfm)
273{
88056ec3 274 return tfm->reqsize;
18e33e6d
HX
275}
276
dec8b786
HX
277static inline void *ahash_request_ctx(struct ahash_request *req)
278{
279 return req->__ctx;
280}
281
66f6ce5e
HX
282int crypto_ahash_setkey(struct crypto_ahash *tfm, const u8 *key,
283 unsigned int keylen);
284int crypto_ahash_finup(struct ahash_request *req);
285int crypto_ahash_final(struct ahash_request *req);
286int crypto_ahash_digest(struct ahash_request *req);
18e33e6d 287
88056ec3 288static inline int crypto_ahash_export(struct ahash_request *req, void *out)
dec8b786 289{
88056ec3 290 return crypto_ahash_reqtfm(req)->export(req, out);
dec8b786
HX
291}
292
88056ec3
HX
293static inline int crypto_ahash_import(struct ahash_request *req, const void *in)
294{
295 return crypto_ahash_reqtfm(req)->import(req, in);
296}
dec8b786 297
318e5313
HX
298static inline int crypto_ahash_init(struct ahash_request *req)
299{
88056ec3 300 return crypto_ahash_reqtfm(req)->init(req);
318e5313
HX
301}
302
303static inline int crypto_ahash_update(struct ahash_request *req)
304{
88056ec3 305 return crypto_ahash_reqtfm(req)->update(req);
318e5313
HX
306}
307
18e33e6d
HX
308static inline void ahash_request_set_tfm(struct ahash_request *req,
309 struct crypto_ahash *tfm)
310{
311 req->base.tfm = crypto_ahash_tfm(tfm);
312}
313
314static inline struct ahash_request *ahash_request_alloc(
315 struct crypto_ahash *tfm, gfp_t gfp)
316{
317 struct ahash_request *req;
318
319 req = kmalloc(sizeof(struct ahash_request) +
320 crypto_ahash_reqsize(tfm), gfp);
321
322 if (likely(req))
323 ahash_request_set_tfm(req, tfm);
324
325 return req;
326}
327
328static inline void ahash_request_free(struct ahash_request *req)
329{
aef73cfc 330 kzfree(req);
18e33e6d
HX
331}
332
333static inline struct ahash_request *ahash_request_cast(
334 struct crypto_async_request *req)
335{
336 return container_of(req, struct ahash_request, base);
337}
338
339static inline void ahash_request_set_callback(struct ahash_request *req,
340 u32 flags,
3e3dc25f 341 crypto_completion_t compl,
18e33e6d
HX
342 void *data)
343{
3e3dc25f 344 req->base.complete = compl;
18e33e6d
HX
345 req->base.data = data;
346 req->base.flags = flags;
347}
348
349static inline void ahash_request_set_crypt(struct ahash_request *req,
350 struct scatterlist *src, u8 *result,
351 unsigned int nbytes)
352{
353 req->src = src;
354 req->nbytes = nbytes;
355 req->result = result;
356}
357
7b5a080b
HX
358struct crypto_shash *crypto_alloc_shash(const char *alg_name, u32 type,
359 u32 mask);
360
361static inline struct crypto_tfm *crypto_shash_tfm(struct crypto_shash *tfm)
362{
363 return &tfm->base;
364}
365
366static inline void crypto_free_shash(struct crypto_shash *tfm)
367{
412e87ae 368 crypto_destroy_tfm(tfm, crypto_shash_tfm(tfm));
7b5a080b
HX
369}
370
371static inline unsigned int crypto_shash_alignmask(
372 struct crypto_shash *tfm)
373{
374 return crypto_tfm_alg_alignmask(crypto_shash_tfm(tfm));
375}
376
97495986
HX
377static inline unsigned int crypto_shash_blocksize(struct crypto_shash *tfm)
378{
379 return crypto_tfm_alg_blocksize(crypto_shash_tfm(tfm));
380}
381
7b5a080b
HX
382static inline struct shash_alg *__crypto_shash_alg(struct crypto_alg *alg)
383{
384 return container_of(alg, struct shash_alg, base);
385}
386
387static inline struct shash_alg *crypto_shash_alg(struct crypto_shash *tfm)
388{
389 return __crypto_shash_alg(crypto_shash_tfm(tfm)->__crt_alg);
390}
391
392static inline unsigned int crypto_shash_digestsize(struct crypto_shash *tfm)
393{
394 return crypto_shash_alg(tfm)->digestsize;
395}
396
99d27e1c
HX
397static inline unsigned int crypto_shash_statesize(struct crypto_shash *tfm)
398{
399 return crypto_shash_alg(tfm)->statesize;
400}
401
7b5a080b
HX
402static inline u32 crypto_shash_get_flags(struct crypto_shash *tfm)
403{
404 return crypto_tfm_get_flags(crypto_shash_tfm(tfm));
405}
406
407static inline void crypto_shash_set_flags(struct crypto_shash *tfm, u32 flags)
408{
409 crypto_tfm_set_flags(crypto_shash_tfm(tfm), flags);
410}
411
412static inline void crypto_shash_clear_flags(struct crypto_shash *tfm, u32 flags)
413{
414 crypto_tfm_clear_flags(crypto_shash_tfm(tfm), flags);
415}
416
417static inline unsigned int crypto_shash_descsize(struct crypto_shash *tfm)
418{
113adefc 419 return tfm->descsize;
7b5a080b
HX
420}
421
422static inline void *shash_desc_ctx(struct shash_desc *desc)
423{
424 return desc->__ctx;
425}
426
427int crypto_shash_setkey(struct crypto_shash *tfm, const u8 *key,
428 unsigned int keylen);
429int crypto_shash_digest(struct shash_desc *desc, const u8 *data,
430 unsigned int len, u8 *out);
431
99d27e1c 432static inline int crypto_shash_export(struct shash_desc *desc, void *out)
dec8b786 433{
99d27e1c 434 return crypto_shash_alg(desc->tfm)->export(desc, out);
dec8b786
HX
435}
436
99d27e1c
HX
437static inline int crypto_shash_import(struct shash_desc *desc, const void *in)
438{
439 return crypto_shash_alg(desc->tfm)->import(desc, in);
440}
dec8b786 441
7b5a080b
HX
442static inline int crypto_shash_init(struct shash_desc *desc)
443{
444 return crypto_shash_alg(desc->tfm)->init(desc);
445}
446
447int crypto_shash_update(struct shash_desc *desc, const u8 *data,
448 unsigned int len);
449int crypto_shash_final(struct shash_desc *desc, u8 *out);
450int crypto_shash_finup(struct shash_desc *desc, const u8 *data,
451 unsigned int len, u8 *out);
452
18e33e6d 453#endif /* _CRYPTO_HASH_H */