Line data Source code
1 : /* SPDX-License-Identifier: GPL-2.0-or-later */
2 : /*
3 : * Hash: Hash algorithms under the crypto API
4 : *
5 : * Copyright (c) 2008 Herbert Xu <herbert@gondor.apana.org.au>
6 : */
7 :
8 : #ifndef _CRYPTO_HASH_H
9 : #define _CRYPTO_HASH_H
10 :
11 : #include <linux/atomic.h>
12 : #include <linux/crypto.h>
13 : #include <linux/string.h>
14 :
15 : struct crypto_ahash;
16 :
17 : /**
18 : * DOC: Message Digest Algorithm Definitions
19 : *
20 : * These data structures define modular message digest algorithm
21 : * implementations, managed via crypto_register_ahash(),
22 : * crypto_register_shash(), crypto_unregister_ahash() and
23 : * crypto_unregister_shash().
24 : */
25 :
26 : /*
27 : * struct crypto_istat_hash - statistics for has algorithm
28 : * @hash_cnt: number of hash requests
29 : * @hash_tlen: total data size hashed
30 : * @err_cnt: number of error for hash requests
31 : */
32 : struct crypto_istat_hash {
33 : atomic64_t hash_cnt;
34 : atomic64_t hash_tlen;
35 : atomic64_t err_cnt;
36 : };
37 :
38 : #ifdef CONFIG_CRYPTO_STATS
39 : #define HASH_ALG_COMMON_STAT struct crypto_istat_hash stat;
40 : #else
41 : #define HASH_ALG_COMMON_STAT
42 : #endif
43 :
44 : /*
45 : * struct hash_alg_common - define properties of message digest
46 : * @stat: Statistics for hash algorithm.
47 : * @digestsize: Size of the result of the transformation. A buffer of this size
48 : * must be available to the @final and @finup calls, so they can
49 : * store the resulting hash into it. For various predefined sizes,
50 : * search include/crypto/ using
51 : * git grep _DIGEST_SIZE include/crypto.
52 : * @statesize: Size of the block for partial state of the transformation. A
53 : * buffer of this size must be passed to the @export function as it
54 : * will save the partial state of the transformation into it. On the
55 : * other side, the @import function will load the state from a
56 : * buffer of this size as well.
57 : * @base: Start of data structure of cipher algorithm. The common data
58 : * structure of crypto_alg contains information common to all ciphers.
59 : * The hash_alg_common data structure now adds the hash-specific
60 : * information.
61 : */
62 : #define HASH_ALG_COMMON { \
63 : HASH_ALG_COMMON_STAT \
64 : \
65 : unsigned int digestsize; \
66 : unsigned int statesize; \
67 : \
68 : struct crypto_alg base; \
69 : }
70 : struct hash_alg_common HASH_ALG_COMMON;
71 :
72 : struct ahash_request {
73 : struct crypto_async_request base;
74 :
75 : unsigned int nbytes;
76 : struct scatterlist *src;
77 : u8 *result;
78 :
79 : /* This field may only be used by the ahash API code. */
80 : void *priv;
81 :
82 : void *__ctx[] CRYPTO_MINALIGN_ATTR;
83 : };
84 :
85 : /**
86 : * struct ahash_alg - asynchronous message digest definition
87 : * @init: **[mandatory]** Initialize the transformation context. Intended only to initialize the
88 : * state of the HASH transformation at the beginning. This shall fill in
89 : * the internal structures used during the entire duration of the whole
90 : * transformation. No data processing happens at this point. Driver code
91 : * implementation must not use req->result.
92 : * @update: **[mandatory]** Push a chunk of data into the driver for transformation. This
93 : * function actually pushes blocks of data from upper layers into the
94 : * driver, which then passes those to the hardware as seen fit. This
95 : * function must not finalize the HASH transformation by calculating the
96 : * final message digest as this only adds more data into the
97 : * transformation. This function shall not modify the transformation
98 : * context, as this function may be called in parallel with the same
99 : * transformation object. Data processing can happen synchronously
100 : * [SHASH] or asynchronously [AHASH] at this point. Driver must not use
101 : * req->result.
102 : * @final: **[mandatory]** Retrieve result from the driver. This function finalizes the
103 : * transformation and retrieves the resulting hash from the driver and
104 : * pushes it back to upper layers. No data processing happens at this
105 : * point unless hardware requires it to finish the transformation
106 : * (then the data buffered by the device driver is processed).
107 : * @finup: **[optional]** Combination of @update and @final. This function is effectively a
108 : * combination of @update and @final calls issued in sequence. As some
109 : * hardware cannot do @update and @final separately, this callback was
110 : * added to allow such hardware to be used at least by IPsec. Data
111 : * processing can happen synchronously [SHASH] or asynchronously [AHASH]
112 : * at this point.
113 : * @digest: Combination of @init and @update and @final. This function
114 : * effectively behaves as the entire chain of operations, @init,
115 : * @update and @final issued in sequence. Just like @finup, this was
116 : * added for hardware which cannot do even the @finup, but can only do
117 : * the whole transformation in one run. Data processing can happen
118 : * synchronously [SHASH] or asynchronously [AHASH] at this point.
119 : * @setkey: Set optional key used by the hashing algorithm. Intended to push
120 : * optional key used by the hashing algorithm from upper layers into
121 : * the driver. This function can store the key in the transformation
122 : * context or can outright program it into the hardware. In the former
123 : * case, one must be careful to program the key into the hardware at
124 : * appropriate time and one must be careful that .setkey() can be
125 : * called multiple times during the existence of the transformation
126 : * object. Not all hashing algorithms do implement this function as it
127 : * is only needed for keyed message digests. SHAx/MDx/CRCx do NOT
128 : * implement this function. HMAC(MDx)/HMAC(SHAx)/CMAC(AES) do implement
129 : * this function. This function must be called before any other of the
130 : * @init, @update, @final, @finup, @digest is called. No data
131 : * processing happens at this point.
132 : * @export: Export partial state of the transformation. This function dumps the
133 : * entire state of the ongoing transformation into a provided block of
134 : * data so it can be @import 'ed back later on. This is useful in case
135 : * you want to save partial result of the transformation after
136 : * processing certain amount of data and reload this partial result
137 : * multiple times later on for multiple re-use. No data processing
138 : * happens at this point. Driver must not use req->result.
139 : * @import: Import partial state of the transformation. This function loads the
140 : * entire state of the ongoing transformation from a provided block of
141 : * data so the transformation can continue from this point onward. No
142 : * data processing happens at this point. Driver must not use
143 : * req->result.
144 : * @init_tfm: Initialize the cryptographic transformation object.
145 : * This function is called only once at the instantiation
146 : * time, right after the transformation context was
147 : * allocated. In case the cryptographic hardware has
148 : * some special requirements which need to be handled
149 : * by software, this function shall check for the precise
150 : * requirement of the transformation and put any software
151 : * fallbacks in place.
152 : * @exit_tfm: Deinitialize the cryptographic transformation object.
153 : * This is a counterpart to @init_tfm, used to remove
154 : * various changes set in @init_tfm.
155 : * @clone_tfm: Copy transform into new object, may allocate memory.
156 : * @halg: see struct hash_alg_common
157 : */
158 : struct ahash_alg {
159 : int (*init)(struct ahash_request *req);
160 : int (*update)(struct ahash_request *req);
161 : int (*final)(struct ahash_request *req);
162 : int (*finup)(struct ahash_request *req);
163 : int (*digest)(struct ahash_request *req);
164 : int (*export)(struct ahash_request *req, void *out);
165 : int (*import)(struct ahash_request *req, const void *in);
166 : int (*setkey)(struct crypto_ahash *tfm, const u8 *key,
167 : unsigned int keylen);
168 : int (*init_tfm)(struct crypto_ahash *tfm);
169 : void (*exit_tfm)(struct crypto_ahash *tfm);
170 : int (*clone_tfm)(struct crypto_ahash *dst, struct crypto_ahash *src);
171 :
172 : struct hash_alg_common halg;
173 : };
174 :
175 : struct shash_desc {
176 : struct crypto_shash *tfm;
177 : void *__ctx[] __aligned(ARCH_SLAB_MINALIGN);
178 : };
179 :
180 : #define HASH_MAX_DIGESTSIZE 64
181 :
182 : /*
183 : * Worst case is hmac(sha3-224-generic). Its context is a nested 'shash_desc'
184 : * containing a 'struct sha3_state'.
185 : */
186 : #define HASH_MAX_DESCSIZE (sizeof(struct shash_desc) + 360)
187 :
188 : #define SHASH_DESC_ON_STACK(shash, ctx) \
189 : char __##shash##_desc[sizeof(struct shash_desc) + HASH_MAX_DESCSIZE] \
190 : __aligned(__alignof__(struct shash_desc)); \
191 : struct shash_desc *shash = (struct shash_desc *)__##shash##_desc
192 :
193 : /**
194 : * struct shash_alg - synchronous message digest definition
195 : * @init: see struct ahash_alg
196 : * @update: see struct ahash_alg
197 : * @final: see struct ahash_alg
198 : * @finup: see struct ahash_alg
199 : * @digest: see struct ahash_alg
200 : * @export: see struct ahash_alg
201 : * @import: see struct ahash_alg
202 : * @setkey: see struct ahash_alg
203 : * @init_tfm: Initialize the cryptographic transformation object.
204 : * This function is called only once at the instantiation
205 : * time, right after the transformation context was
206 : * allocated. In case the cryptographic hardware has
207 : * some special requirements which need to be handled
208 : * by software, this function shall check for the precise
209 : * requirement of the transformation and put any software
210 : * fallbacks in place.
211 : * @exit_tfm: Deinitialize the cryptographic transformation object.
212 : * This is a counterpart to @init_tfm, used to remove
213 : * various changes set in @init_tfm.
214 : * @clone_tfm: Copy transform into new object, may allocate memory.
215 : * @digestsize: see struct ahash_alg
216 : * @statesize: see struct ahash_alg
217 : * @descsize: Size of the operational state for the message digest. This state
218 : * size is the memory size that needs to be allocated for
219 : * shash_desc.__ctx
220 : * @stat: Statistics for hash algorithm.
221 : * @base: internally used
222 : * @halg: see struct hash_alg_common
223 : * @HASH_ALG_COMMON: see struct hash_alg_common
224 : */
225 : struct shash_alg {
226 : int (*init)(struct shash_desc *desc);
227 : int (*update)(struct shash_desc *desc, const u8 *data,
228 : unsigned int len);
229 : int (*final)(struct shash_desc *desc, u8 *out);
230 : int (*finup)(struct shash_desc *desc, const u8 *data,
231 : unsigned int len, u8 *out);
232 : int (*digest)(struct shash_desc *desc, const u8 *data,
233 : unsigned int len, u8 *out);
234 : int (*export)(struct shash_desc *desc, void *out);
235 : int (*import)(struct shash_desc *desc, const void *in);
236 : int (*setkey)(struct crypto_shash *tfm, const u8 *key,
237 : unsigned int keylen);
238 : int (*init_tfm)(struct crypto_shash *tfm);
239 : void (*exit_tfm)(struct crypto_shash *tfm);
240 : int (*clone_tfm)(struct crypto_shash *dst, struct crypto_shash *src);
241 :
242 : unsigned int descsize;
243 :
244 : union {
245 : struct HASH_ALG_COMMON;
246 : struct hash_alg_common halg;
247 : };
248 : };
249 : #undef HASH_ALG_COMMON
250 : #undef HASH_ALG_COMMON_STAT
251 :
252 : struct crypto_ahash {
253 : int (*init)(struct ahash_request *req);
254 : int (*update)(struct ahash_request *req);
255 : int (*final)(struct ahash_request *req);
256 : int (*finup)(struct ahash_request *req);
257 : int (*digest)(struct ahash_request *req);
258 : int (*export)(struct ahash_request *req, void *out);
259 : int (*import)(struct ahash_request *req, const void *in);
260 : int (*setkey)(struct crypto_ahash *tfm, const u8 *key,
261 : unsigned int keylen);
262 :
263 : unsigned int statesize;
264 : unsigned int reqsize;
265 : struct crypto_tfm base;
266 : };
267 :
268 : struct crypto_shash {
269 : unsigned int descsize;
270 : struct crypto_tfm base;
271 : };
272 :
273 : /**
274 : * DOC: Asynchronous Message Digest API
275 : *
276 : * The asynchronous message digest API is used with the ciphers of type
277 : * CRYPTO_ALG_TYPE_AHASH (listed as type "ahash" in /proc/crypto)
278 : *
279 : * The asynchronous cipher operation discussion provided for the
280 : * CRYPTO_ALG_TYPE_SKCIPHER API applies here as well.
281 : */
282 :
283 : static inline struct crypto_ahash *__crypto_ahash_cast(struct crypto_tfm *tfm)
284 : {
285 : return container_of(tfm, struct crypto_ahash, base);
286 : }
287 :
288 : /**
289 : * crypto_alloc_ahash() - allocate ahash cipher handle
290 : * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
291 : * ahash cipher
292 : * @type: specifies the type of the cipher
293 : * @mask: specifies the mask for the cipher
294 : *
295 : * Allocate a cipher handle for an ahash. The returned struct
296 : * crypto_ahash is the cipher handle that is required for any subsequent
297 : * API invocation for that ahash.
298 : *
299 : * Return: allocated cipher handle in case of success; IS_ERR() is true in case
300 : * of an error, PTR_ERR() returns the error code.
301 : */
302 : struct crypto_ahash *crypto_alloc_ahash(const char *alg_name, u32 type,
303 : u32 mask);
304 :
305 : struct crypto_ahash *crypto_clone_ahash(struct crypto_ahash *tfm);
306 :
307 : static inline struct crypto_tfm *crypto_ahash_tfm(struct crypto_ahash *tfm)
308 : {
309 : return &tfm->base;
310 : }
311 :
312 : /**
313 : * crypto_free_ahash() - zeroize and free the ahash handle
314 : * @tfm: cipher handle to be freed
315 : *
316 : * If @tfm is a NULL or error pointer, this function does nothing.
317 : */
318 : static inline void crypto_free_ahash(struct crypto_ahash *tfm)
319 : {
320 : crypto_destroy_tfm(tfm, crypto_ahash_tfm(tfm));
321 : }
322 :
323 : /**
324 : * crypto_has_ahash() - Search for the availability of an ahash.
325 : * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
326 : * ahash
327 : * @type: specifies the type of the ahash
328 : * @mask: specifies the mask for the ahash
329 : *
330 : * Return: true when the ahash is known to the kernel crypto API; false
331 : * otherwise
332 : */
333 : int crypto_has_ahash(const char *alg_name, u32 type, u32 mask);
334 :
335 : static inline const char *crypto_ahash_alg_name(struct crypto_ahash *tfm)
336 : {
337 : return crypto_tfm_alg_name(crypto_ahash_tfm(tfm));
338 : }
339 :
340 : static inline const char *crypto_ahash_driver_name(struct crypto_ahash *tfm)
341 : {
342 : return crypto_tfm_alg_driver_name(crypto_ahash_tfm(tfm));
343 : }
344 :
345 : static inline unsigned int crypto_ahash_alignmask(
346 : struct crypto_ahash *tfm)
347 : {
348 : return crypto_tfm_alg_alignmask(crypto_ahash_tfm(tfm));
349 : }
350 :
351 : /**
352 : * crypto_ahash_blocksize() - obtain block size for cipher
353 : * @tfm: cipher handle
354 : *
355 : * The block size for the message digest cipher referenced with the cipher
356 : * handle is returned.
357 : *
358 : * Return: block size of cipher
359 : */
360 : static inline unsigned int crypto_ahash_blocksize(struct crypto_ahash *tfm)
361 : {
362 : return crypto_tfm_alg_blocksize(crypto_ahash_tfm(tfm));
363 : }
364 :
365 : static inline struct hash_alg_common *__crypto_hash_alg_common(
366 : struct crypto_alg *alg)
367 : {
368 : return container_of(alg, struct hash_alg_common, base);
369 : }
370 :
371 : static inline struct hash_alg_common *crypto_hash_alg_common(
372 : struct crypto_ahash *tfm)
373 : {
374 : return __crypto_hash_alg_common(crypto_ahash_tfm(tfm)->__crt_alg);
375 : }
376 :
377 : /**
378 : * crypto_ahash_digestsize() - obtain message digest size
379 : * @tfm: cipher handle
380 : *
381 : * The size for the message digest created by the message digest cipher
382 : * referenced with the cipher handle is returned.
383 : *
384 : *
385 : * Return: message digest size of cipher
386 : */
387 : static inline unsigned int crypto_ahash_digestsize(struct crypto_ahash *tfm)
388 : {
389 : return crypto_hash_alg_common(tfm)->digestsize;
390 : }
391 :
392 : /**
393 : * crypto_ahash_statesize() - obtain size of the ahash state
394 : * @tfm: cipher handle
395 : *
396 : * Return the size of the ahash state. With the crypto_ahash_export()
397 : * function, the caller can export the state into a buffer whose size is
398 : * defined with this function.
399 : *
400 : * Return: size of the ahash state
401 : */
402 : static inline unsigned int crypto_ahash_statesize(struct crypto_ahash *tfm)
403 : {
404 : return tfm->statesize;
405 : }
406 :
407 : static inline u32 crypto_ahash_get_flags(struct crypto_ahash *tfm)
408 : {
409 : return crypto_tfm_get_flags(crypto_ahash_tfm(tfm));
410 : }
411 :
412 : static inline void crypto_ahash_set_flags(struct crypto_ahash *tfm, u32 flags)
413 : {
414 : crypto_tfm_set_flags(crypto_ahash_tfm(tfm), flags);
415 : }
416 :
417 : static inline void crypto_ahash_clear_flags(struct crypto_ahash *tfm, u32 flags)
418 : {
419 : crypto_tfm_clear_flags(crypto_ahash_tfm(tfm), flags);
420 : }
421 :
422 : /**
423 : * crypto_ahash_reqtfm() - obtain cipher handle from request
424 : * @req: asynchronous request handle that contains the reference to the ahash
425 : * cipher handle
426 : *
427 : * Return the ahash cipher handle that is registered with the asynchronous
428 : * request handle ahash_request.
429 : *
430 : * Return: ahash cipher handle
431 : */
432 : static inline struct crypto_ahash *crypto_ahash_reqtfm(
433 : struct ahash_request *req)
434 : {
435 : return __crypto_ahash_cast(req->base.tfm);
436 : }
437 :
438 : /**
439 : * crypto_ahash_reqsize() - obtain size of the request data structure
440 : * @tfm: cipher handle
441 : *
442 : * Return: size of the request data
443 : */
444 : static inline unsigned int crypto_ahash_reqsize(struct crypto_ahash *tfm)
445 : {
446 : return tfm->reqsize;
447 : }
448 :
449 : static inline void *ahash_request_ctx(struct ahash_request *req)
450 : {
451 : return req->__ctx;
452 : }
453 :
454 : /**
455 : * crypto_ahash_setkey - set key for cipher handle
456 : * @tfm: cipher handle
457 : * @key: buffer holding the key
458 : * @keylen: length of the key in bytes
459 : *
460 : * The caller provided key is set for the ahash cipher. The cipher
461 : * handle must point to a keyed hash in order for this function to succeed.
462 : *
463 : * Return: 0 if the setting of the key was successful; < 0 if an error occurred
464 : */
465 : int crypto_ahash_setkey(struct crypto_ahash *tfm, const u8 *key,
466 : unsigned int keylen);
467 :
468 : /**
469 : * crypto_ahash_finup() - update and finalize message digest
470 : * @req: reference to the ahash_request handle that holds all information
471 : * needed to perform the cipher operation
472 : *
473 : * This function is a "short-hand" for the function calls of
474 : * crypto_ahash_update and crypto_ahash_final. The parameters have the same
475 : * meaning as discussed for those separate functions.
476 : *
477 : * Return: see crypto_ahash_final()
478 : */
479 : int crypto_ahash_finup(struct ahash_request *req);
480 :
481 : /**
482 : * crypto_ahash_final() - calculate message digest
483 : * @req: reference to the ahash_request handle that holds all information
484 : * needed to perform the cipher operation
485 : *
486 : * Finalize the message digest operation and create the message digest
487 : * based on all data added to the cipher handle. The message digest is placed
488 : * into the output buffer registered with the ahash_request handle.
489 : *
490 : * Return:
491 : * 0 if the message digest was successfully calculated;
492 : * -EINPROGRESS if data is fed into hardware (DMA) or queued for later;
493 : * -EBUSY if queue is full and request should be resubmitted later;
494 : * other < 0 if an error occurred
495 : */
496 : int crypto_ahash_final(struct ahash_request *req);
497 :
498 : /**
499 : * crypto_ahash_digest() - calculate message digest for a buffer
500 : * @req: reference to the ahash_request handle that holds all information
501 : * needed to perform the cipher operation
502 : *
503 : * This function is a "short-hand" for the function calls of crypto_ahash_init,
504 : * crypto_ahash_update and crypto_ahash_final. The parameters have the same
505 : * meaning as discussed for those separate three functions.
506 : *
507 : * Return: see crypto_ahash_final()
508 : */
509 : int crypto_ahash_digest(struct ahash_request *req);
510 :
511 : /**
512 : * crypto_ahash_export() - extract current message digest state
513 : * @req: reference to the ahash_request handle whose state is exported
514 : * @out: output buffer of sufficient size that can hold the hash state
515 : *
516 : * This function exports the hash state of the ahash_request handle into the
517 : * caller-allocated output buffer out which must have sufficient size (e.g. by
518 : * calling crypto_ahash_statesize()).
519 : *
520 : * Return: 0 if the export was successful; < 0 if an error occurred
521 : */
522 : static inline int crypto_ahash_export(struct ahash_request *req, void *out)
523 : {
524 : return crypto_ahash_reqtfm(req)->export(req, out);
525 : }
526 :
527 : /**
528 : * crypto_ahash_import() - import message digest state
529 : * @req: reference to ahash_request handle the state is imported into
530 : * @in: buffer holding the state
531 : *
532 : * This function imports the hash state into the ahash_request handle from the
533 : * input buffer. That buffer should have been generated with the
534 : * crypto_ahash_export function.
535 : *
536 : * Return: 0 if the import was successful; < 0 if an error occurred
537 : */
538 : static inline int crypto_ahash_import(struct ahash_request *req, const void *in)
539 : {
540 : struct crypto_ahash *tfm = crypto_ahash_reqtfm(req);
541 :
542 : if (crypto_ahash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY)
543 : return -ENOKEY;
544 :
545 : return tfm->import(req, in);
546 : }
547 :
548 : /**
549 : * crypto_ahash_init() - (re)initialize message digest handle
550 : * @req: ahash_request handle that already is initialized with all necessary
551 : * data using the ahash_request_* API functions
552 : *
553 : * The call (re-)initializes the message digest referenced by the ahash_request
554 : * handle. Any potentially existing state created by previous operations is
555 : * discarded.
556 : *
557 : * Return: see crypto_ahash_final()
558 : */
559 : static inline int crypto_ahash_init(struct ahash_request *req)
560 : {
561 : struct crypto_ahash *tfm = crypto_ahash_reqtfm(req);
562 :
563 : if (crypto_ahash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY)
564 : return -ENOKEY;
565 :
566 : return tfm->init(req);
567 : }
568 :
569 : static inline struct crypto_istat_hash *hash_get_stat(
570 : struct hash_alg_common *alg)
571 : {
572 : #ifdef CONFIG_CRYPTO_STATS
573 : return &alg->stat;
574 : #else
575 : return NULL;
576 : #endif
577 : }
578 :
579 : static inline int crypto_hash_errstat(struct hash_alg_common *alg, int err)
580 : {
581 : if (!IS_ENABLED(CONFIG_CRYPTO_STATS))
582 : return err;
583 :
584 : if (err && err != -EINPROGRESS && err != -EBUSY)
585 : atomic64_inc(&hash_get_stat(alg)->err_cnt);
586 :
587 : return err;
588 : }
589 :
590 : /**
591 : * crypto_ahash_update() - add data to message digest for processing
592 : * @req: ahash_request handle that was previously initialized with the
593 : * crypto_ahash_init call.
594 : *
595 : * Updates the message digest state of the &ahash_request handle. The input data
596 : * is pointed to by the scatter/gather list registered in the &ahash_request
597 : * handle
598 : *
599 : * Return: see crypto_ahash_final()
600 : */
601 : static inline int crypto_ahash_update(struct ahash_request *req)
602 : {
603 : struct crypto_ahash *tfm = crypto_ahash_reqtfm(req);
604 : struct hash_alg_common *alg = crypto_hash_alg_common(tfm);
605 :
606 : if (IS_ENABLED(CONFIG_CRYPTO_STATS))
607 : atomic64_add(req->nbytes, &hash_get_stat(alg)->hash_tlen);
608 :
609 : return crypto_hash_errstat(alg, tfm->update(req));
610 : }
611 :
612 : /**
613 : * DOC: Asynchronous Hash Request Handle
614 : *
615 : * The &ahash_request data structure contains all pointers to data
616 : * required for the asynchronous cipher operation. This includes the cipher
617 : * handle (which can be used by multiple &ahash_request instances), pointer
618 : * to plaintext and the message digest output buffer, asynchronous callback
619 : * function, etc. It acts as a handle to the ahash_request_* API calls in a
620 : * similar way as ahash handle to the crypto_ahash_* API calls.
621 : */
622 :
623 : /**
624 : * ahash_request_set_tfm() - update cipher handle reference in request
625 : * @req: request handle to be modified
626 : * @tfm: cipher handle that shall be added to the request handle
627 : *
628 : * Allow the caller to replace the existing ahash handle in the request
629 : * data structure with a different one.
630 : */
631 : static inline void ahash_request_set_tfm(struct ahash_request *req,
632 : struct crypto_ahash *tfm)
633 : {
634 : req->base.tfm = crypto_ahash_tfm(tfm);
635 : }
636 :
637 : /**
638 : * ahash_request_alloc() - allocate request data structure
639 : * @tfm: cipher handle to be registered with the request
640 : * @gfp: memory allocation flag that is handed to kmalloc by the API call.
641 : *
642 : * Allocate the request data structure that must be used with the ahash
643 : * message digest API calls. During
644 : * the allocation, the provided ahash handle
645 : * is registered in the request data structure.
646 : *
647 : * Return: allocated request handle in case of success, or NULL if out of memory
648 : */
649 : static inline struct ahash_request *ahash_request_alloc(
650 : struct crypto_ahash *tfm, gfp_t gfp)
651 : {
652 : struct ahash_request *req;
653 :
654 : req = kmalloc(sizeof(struct ahash_request) +
655 : crypto_ahash_reqsize(tfm), gfp);
656 :
657 : if (likely(req))
658 : ahash_request_set_tfm(req, tfm);
659 :
660 : return req;
661 : }
662 :
663 : /**
664 : * ahash_request_free() - zeroize and free the request data structure
665 : * @req: request data structure cipher handle to be freed
666 : */
667 : static inline void ahash_request_free(struct ahash_request *req)
668 : {
669 : kfree_sensitive(req);
670 : }
671 :
672 : static inline void ahash_request_zero(struct ahash_request *req)
673 : {
674 : memzero_explicit(req, sizeof(*req) +
675 : crypto_ahash_reqsize(crypto_ahash_reqtfm(req)));
676 : }
677 :
678 : static inline struct ahash_request *ahash_request_cast(
679 : struct crypto_async_request *req)
680 : {
681 : return container_of(req, struct ahash_request, base);
682 : }
683 :
684 : /**
685 : * ahash_request_set_callback() - set asynchronous callback function
686 : * @req: request handle
687 : * @flags: specify zero or an ORing of the flags
688 : * CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
689 : * increase the wait queue beyond the initial maximum size;
690 : * CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
691 : * @compl: callback function pointer to be registered with the request handle
692 : * @data: The data pointer refers to memory that is not used by the kernel
693 : * crypto API, but provided to the callback function for it to use. Here,
694 : * the caller can provide a reference to memory the callback function can
695 : * operate on. As the callback function is invoked asynchronously to the
696 : * related functionality, it may need to access data structures of the
697 : * related functionality which can be referenced using this pointer. The
698 : * callback function can access the memory via the "data" field in the
699 : * &crypto_async_request data structure provided to the callback function.
700 : *
701 : * This function allows setting the callback function that is triggered once
702 : * the cipher operation completes.
703 : *
704 : * The callback function is registered with the &ahash_request handle and
705 : * must comply with the following template::
706 : *
707 : * void callback_function(struct crypto_async_request *req, int error)
708 : */
709 : static inline void ahash_request_set_callback(struct ahash_request *req,
710 : u32 flags,
711 : crypto_completion_t compl,
712 : void *data)
713 : {
714 : req->base.complete = compl;
715 : req->base.data = data;
716 : req->base.flags = flags;
717 : }
718 :
719 : /**
720 : * ahash_request_set_crypt() - set data buffers
721 : * @req: ahash_request handle to be updated
722 : * @src: source scatter/gather list
723 : * @result: buffer that is filled with the message digest -- the caller must
724 : * ensure that the buffer has sufficient space by, for example, calling
725 : * crypto_ahash_digestsize()
726 : * @nbytes: number of bytes to process from the source scatter/gather list
727 : *
728 : * By using this call, the caller references the source scatter/gather list.
729 : * The source scatter/gather list points to the data the message digest is to
730 : * be calculated for.
731 : */
732 : static inline void ahash_request_set_crypt(struct ahash_request *req,
733 : struct scatterlist *src, u8 *result,
734 : unsigned int nbytes)
735 : {
736 : req->src = src;
737 : req->nbytes = nbytes;
738 : req->result = result;
739 : }
740 :
741 : /**
742 : * DOC: Synchronous Message Digest API
743 : *
744 : * The synchronous message digest API is used with the ciphers of type
745 : * CRYPTO_ALG_TYPE_SHASH (listed as type "shash" in /proc/crypto)
746 : *
747 : * The message digest API is able to maintain state information for the
748 : * caller.
749 : *
750 : * The synchronous message digest API can store user-related context in its
751 : * shash_desc request data structure.
752 : */
753 :
754 : /**
755 : * crypto_alloc_shash() - allocate message digest handle
756 : * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
757 : * message digest cipher
758 : * @type: specifies the type of the cipher
759 : * @mask: specifies the mask for the cipher
760 : *
761 : * Allocate a cipher handle for a message digest. The returned &struct
762 : * crypto_shash is the cipher handle that is required for any subsequent
763 : * API invocation for that message digest.
764 : *
765 : * Return: allocated cipher handle in case of success; IS_ERR() is true in case
766 : * of an error, PTR_ERR() returns the error code.
767 : */
768 : struct crypto_shash *crypto_alloc_shash(const char *alg_name, u32 type,
769 : u32 mask);
770 :
771 : struct crypto_shash *crypto_clone_shash(struct crypto_shash *tfm);
772 :
773 : int crypto_has_shash(const char *alg_name, u32 type, u32 mask);
774 :
775 : static inline struct crypto_tfm *crypto_shash_tfm(struct crypto_shash *tfm)
776 : {
777 0 : return &tfm->base;
778 : }
779 :
780 : /**
781 : * crypto_free_shash() - zeroize and free the message digest handle
782 : * @tfm: cipher handle to be freed
783 : *
784 : * If @tfm is a NULL or error pointer, this function does nothing.
785 : */
786 : static inline void crypto_free_shash(struct crypto_shash *tfm)
787 : {
788 0 : crypto_destroy_tfm(tfm, crypto_shash_tfm(tfm));
789 0 : }
790 :
791 : static inline const char *crypto_shash_alg_name(struct crypto_shash *tfm)
792 : {
793 : return crypto_tfm_alg_name(crypto_shash_tfm(tfm));
794 : }
795 :
796 : static inline const char *crypto_shash_driver_name(struct crypto_shash *tfm)
797 : {
798 0 : return crypto_tfm_alg_driver_name(crypto_shash_tfm(tfm));
799 : }
800 :
801 : static inline unsigned int crypto_shash_alignmask(
802 : struct crypto_shash *tfm)
803 : {
804 : return crypto_tfm_alg_alignmask(crypto_shash_tfm(tfm));
805 : }
806 :
807 : /**
808 : * crypto_shash_blocksize() - obtain block size for cipher
809 : * @tfm: cipher handle
810 : *
811 : * The block size for the message digest cipher referenced with the cipher
812 : * handle is returned.
813 : *
814 : * Return: block size of cipher
815 : */
816 : static inline unsigned int crypto_shash_blocksize(struct crypto_shash *tfm)
817 : {
818 : return crypto_tfm_alg_blocksize(crypto_shash_tfm(tfm));
819 : }
820 :
821 : static inline struct shash_alg *__crypto_shash_alg(struct crypto_alg *alg)
822 : {
823 : return container_of(alg, struct shash_alg, base);
824 : }
825 :
826 : static inline struct shash_alg *crypto_shash_alg(struct crypto_shash *tfm)
827 : {
828 0 : return __crypto_shash_alg(crypto_shash_tfm(tfm)->__crt_alg);
829 : }
830 :
831 : /**
832 : * crypto_shash_digestsize() - obtain message digest size
833 : * @tfm: cipher handle
834 : *
835 : * The size for the message digest created by the message digest cipher
836 : * referenced with the cipher handle is returned.
837 : *
838 : * Return: digest size of cipher
839 : */
840 : static inline unsigned int crypto_shash_digestsize(struct crypto_shash *tfm)
841 : {
842 : return crypto_shash_alg(tfm)->digestsize;
843 : }
844 :
845 : static inline unsigned int crypto_shash_statesize(struct crypto_shash *tfm)
846 : {
847 : return crypto_shash_alg(tfm)->statesize;
848 : }
849 :
850 : static inline u32 crypto_shash_get_flags(struct crypto_shash *tfm)
851 : {
852 0 : return crypto_tfm_get_flags(crypto_shash_tfm(tfm));
853 : }
854 :
855 : static inline void crypto_shash_set_flags(struct crypto_shash *tfm, u32 flags)
856 : {
857 : crypto_tfm_set_flags(crypto_shash_tfm(tfm), flags);
858 : }
859 :
860 : static inline void crypto_shash_clear_flags(struct crypto_shash *tfm, u32 flags)
861 : {
862 : crypto_tfm_clear_flags(crypto_shash_tfm(tfm), flags);
863 : }
864 :
865 : /**
866 : * crypto_shash_descsize() - obtain the operational state size
867 : * @tfm: cipher handle
868 : *
869 : * The size of the operational state the cipher needs during operation is
870 : * returned for the hash referenced with the cipher handle. This size is
871 : * required to calculate the memory requirements to allow the caller allocating
872 : * sufficient memory for operational state.
873 : *
874 : * The operational state is defined with struct shash_desc where the size of
875 : * that data structure is to be calculated as
876 : * sizeof(struct shash_desc) + crypto_shash_descsize(alg)
877 : *
878 : * Return: size of the operational state
879 : */
880 : static inline unsigned int crypto_shash_descsize(struct crypto_shash *tfm)
881 : {
882 0 : return tfm->descsize;
883 : }
884 :
885 : static inline void *shash_desc_ctx(struct shash_desc *desc)
886 : {
887 : return desc->__ctx;
888 : }
889 :
890 : /**
891 : * crypto_shash_setkey() - set key for message digest
892 : * @tfm: cipher handle
893 : * @key: buffer holding the key
894 : * @keylen: length of the key in bytes
895 : *
896 : * The caller provided key is set for the keyed message digest cipher. The
897 : * cipher handle must point to a keyed message digest cipher in order for this
898 : * function to succeed.
899 : *
900 : * Context: Any context.
901 : * Return: 0 if the setting of the key was successful; < 0 if an error occurred
902 : */
903 : int crypto_shash_setkey(struct crypto_shash *tfm, const u8 *key,
904 : unsigned int keylen);
905 :
906 : /**
907 : * crypto_shash_digest() - calculate message digest for buffer
908 : * @desc: see crypto_shash_final()
909 : * @data: see crypto_shash_update()
910 : * @len: see crypto_shash_update()
911 : * @out: see crypto_shash_final()
912 : *
913 : * This function is a "short-hand" for the function calls of crypto_shash_init,
914 : * crypto_shash_update and crypto_shash_final. The parameters have the same
915 : * meaning as discussed for those separate three functions.
916 : *
917 : * Context: Any context.
918 : * Return: 0 if the message digest creation was successful; < 0 if an error
919 : * occurred
920 : */
921 : int crypto_shash_digest(struct shash_desc *desc, const u8 *data,
922 : unsigned int len, u8 *out);
923 :
924 : /**
925 : * crypto_shash_tfm_digest() - calculate message digest for buffer
926 : * @tfm: hash transformation object
927 : * @data: see crypto_shash_update()
928 : * @len: see crypto_shash_update()
929 : * @out: see crypto_shash_final()
930 : *
931 : * This is a simplified version of crypto_shash_digest() for users who don't
932 : * want to allocate their own hash descriptor (shash_desc). Instead,
933 : * crypto_shash_tfm_digest() takes a hash transformation object (crypto_shash)
934 : * directly, and it allocates a hash descriptor on the stack internally.
935 : * Note that this stack allocation may be fairly large.
936 : *
937 : * Context: Any context.
938 : * Return: 0 on success; < 0 if an error occurred.
939 : */
940 : int crypto_shash_tfm_digest(struct crypto_shash *tfm, const u8 *data,
941 : unsigned int len, u8 *out);
942 :
943 : /**
944 : * crypto_shash_export() - extract operational state for message digest
945 : * @desc: reference to the operational state handle whose state is exported
946 : * @out: output buffer of sufficient size that can hold the hash state
947 : *
948 : * This function exports the hash state of the operational state handle into the
949 : * caller-allocated output buffer out which must have sufficient size (e.g. by
950 : * calling crypto_shash_descsize).
951 : *
952 : * Context: Any context.
953 : * Return: 0 if the export creation was successful; < 0 if an error occurred
954 : */
955 : static inline int crypto_shash_export(struct shash_desc *desc, void *out)
956 : {
957 : return crypto_shash_alg(desc->tfm)->export(desc, out);
958 : }
959 :
960 : /**
961 : * crypto_shash_import() - import operational state
962 : * @desc: reference to the operational state handle the state imported into
963 : * @in: buffer holding the state
964 : *
965 : * This function imports the hash state into the operational state handle from
966 : * the input buffer. That buffer should have been generated with the
967 : * crypto_ahash_export function.
968 : *
969 : * Context: Any context.
970 : * Return: 0 if the import was successful; < 0 if an error occurred
971 : */
972 : static inline int crypto_shash_import(struct shash_desc *desc, const void *in)
973 : {
974 : struct crypto_shash *tfm = desc->tfm;
975 :
976 : if (crypto_shash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY)
977 : return -ENOKEY;
978 :
979 : return crypto_shash_alg(tfm)->import(desc, in);
980 : }
981 :
982 : /**
983 : * crypto_shash_init() - (re)initialize message digest
984 : * @desc: operational state handle that is already filled
985 : *
986 : * The call (re-)initializes the message digest referenced by the
987 : * operational state handle. Any potentially existing state created by
988 : * previous operations is discarded.
989 : *
990 : * Context: Any context.
991 : * Return: 0 if the message digest initialization was successful; < 0 if an
992 : * error occurred
993 : */
994 0 : static inline int crypto_shash_init(struct shash_desc *desc)
995 : {
996 0 : struct crypto_shash *tfm = desc->tfm;
997 :
998 0 : if (crypto_shash_get_flags(tfm) & CRYPTO_TFM_NEED_KEY)
999 : return -ENOKEY;
1000 :
1001 0 : return crypto_shash_alg(tfm)->init(desc);
1002 : }
1003 :
1004 : /**
1005 : * crypto_shash_update() - add data to message digest for processing
1006 : * @desc: operational state handle that is already initialized
1007 : * @data: input data to be added to the message digest
1008 : * @len: length of the input data
1009 : *
1010 : * Updates the message digest state of the operational state handle.
1011 : *
1012 : * Context: Any context.
1013 : * Return: 0 if the message digest update was successful; < 0 if an error
1014 : * occurred
1015 : */
1016 : int crypto_shash_update(struct shash_desc *desc, const u8 *data,
1017 : unsigned int len);
1018 :
1019 : /**
1020 : * crypto_shash_final() - calculate message digest
1021 : * @desc: operational state handle that is already filled with data
1022 : * @out: output buffer filled with the message digest
1023 : *
1024 : * Finalize the message digest operation and create the message digest
1025 : * based on all data added to the cipher handle. The message digest is placed
1026 : * into the output buffer. The caller must ensure that the output buffer is
1027 : * large enough by using crypto_shash_digestsize.
1028 : *
1029 : * Context: Any context.
1030 : * Return: 0 if the message digest creation was successful; < 0 if an error
1031 : * occurred
1032 : */
1033 : int crypto_shash_final(struct shash_desc *desc, u8 *out);
1034 :
1035 : /**
1036 : * crypto_shash_finup() - calculate message digest of buffer
1037 : * @desc: see crypto_shash_final()
1038 : * @data: see crypto_shash_update()
1039 : * @len: see crypto_shash_update()
1040 : * @out: see crypto_shash_final()
1041 : *
1042 : * This function is a "short-hand" for the function calls of
1043 : * crypto_shash_update and crypto_shash_final. The parameters have the same
1044 : * meaning as discussed for those separate functions.
1045 : *
1046 : * Context: Any context.
1047 : * Return: 0 if the message digest creation was successful; < 0 if an error
1048 : * occurred
1049 : */
1050 : int crypto_shash_finup(struct shash_desc *desc, const u8 *data,
1051 : unsigned int len, u8 *out);
1052 :
1053 : static inline void shash_desc_zero(struct shash_desc *desc)
1054 : {
1055 : memzero_explicit(desc,
1056 : sizeof(*desc) + crypto_shash_descsize(desc->tfm));
1057 : }
1058 :
1059 : #endif /* _CRYPTO_HASH_H */
|
