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

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

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

~ [ 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