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

TOMOYO Linux Cross Reference
Linux/include/crypto/hash.h

Version: ~ [ linux-5.14-rc3 ] ~ [ linux-5.13.5 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.53 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.135 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.198 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.240 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.276 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.276 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.18.140 ] ~ [ linux-3.16.85 ] ~ [ linux-3.14.79 ] ~ [ linux-3.12.74 ] ~ [ 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.5 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

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

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

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | 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.

osdn.jp