1 /**
2 * \file md.h
3 *
4 * \brief This file contains the generic functions for message-digest
5 * (hashing) and HMAC.
6 *
7 * \author Adriaan de Jong <dejong@fox-it.com>
8 */
9 /*
10 * Copyright The Mbed TLS Contributors
11 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
12 */
13
14 #ifndef MBEDTLS_MD_H
15 #define MBEDTLS_MD_H
16 #include "mbedtls/private_access.h"
17
18 #include <stddef.h>
19
20 #include "mbedtls/build_info.h"
21 #include "mbedtls/platform_util.h"
22
23 #if defined(MBEDTLS_MD_LIGHT)
24
25 /*
26 * - MBEDTLS_MD_CAN_xxx is defined if the md module can perform xxx.
27 * - MBEDTLS_MD_xxx_VIA_PSA is defined if the md module may perform xxx via PSA
28 * (see below).
29 * - MBEDTLS_MD_SOME_PSA is defined if at least one algorithm may be performed
30 * via PSA (see below).
31 * - MBEDTLS_MD_SOME_LEGACY is defined if at least one algorithm may be performed
32 * via a direct legacy call (see below).
33 *
34 * The md module performs an algorithm via PSA if there is a PSA hash
35 * accelerator and the PSA driver subsytem is initialized at the time the
36 * operation is started, and makes a direct legacy call otherwise.
37 */
38
39 /* PSA accelerated implementations */
40 #if defined(MBEDTLS_PSA_CRYPTO_C)
41 #if defined(MBEDTLS_PSA_ACCEL_ALG_MD5)
42 #define MBEDTLS_MD_CAN_MD5
43 #define MBEDTLS_MD_MD5_VIA_PSA
44 #define MBEDTLS_MD_SOME_PSA
45 #endif
46 #if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_1)
47 #define MBEDTLS_MD_CAN_SHA1
48 #define MBEDTLS_MD_SHA1_VIA_PSA
49 #define MBEDTLS_MD_SOME_PSA
50 #endif
51 #if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_224)
52 #define MBEDTLS_MD_CAN_SHA224
53 #define MBEDTLS_MD_SHA224_VIA_PSA
54 #define MBEDTLS_MD_SOME_PSA
55 #endif
56 #if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_256)
57 #define MBEDTLS_MD_CAN_SHA256
58 #define MBEDTLS_MD_SHA256_VIA_PSA
59 #define MBEDTLS_MD_SOME_PSA
60 #endif
61 #if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_384)
62 #define MBEDTLS_MD_CAN_SHA384
63 #define MBEDTLS_MD_SHA384_VIA_PSA
64 #define MBEDTLS_MD_SOME_PSA
65 #endif
66 #if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_512)
67 #define MBEDTLS_MD_CAN_SHA512
68 #define MBEDTLS_MD_SHA512_VIA_PSA
69 #define MBEDTLS_MD_SOME_PSA
70 #endif
71 #if defined(MBEDTLS_PSA_ACCEL_ALG_RIPEMD160)
72 #define MBEDTLS_MD_CAN_RIPEMD160
73 #define MBEDTLS_MD_RIPEMD160_VIA_PSA
74 #define MBEDTLS_MD_SOME_PSA
75 #endif
76 #if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_224)
77 #define MBEDTLS_MD_CAN_SHA3_224
78 #define MBEDTLS_MD_SHA3_224_VIA_PSA
79 #define MBEDTLS_MD_SOME_PSA
80 #endif
81 #if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_256)
82 #define MBEDTLS_MD_CAN_SHA3_256
83 #define MBEDTLS_MD_SHA3_256_VIA_PSA
84 #define MBEDTLS_MD_SOME_PSA
85 #endif
86 #if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_384)
87 #define MBEDTLS_MD_CAN_SHA3_384
88 #define MBEDTLS_MD_SHA3_384_VIA_PSA
89 #define MBEDTLS_MD_SOME_PSA
90 #endif
91 #if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_512)
92 #define MBEDTLS_MD_CAN_SHA3_512
93 #define MBEDTLS_MD_SHA3_512_VIA_PSA
94 #define MBEDTLS_MD_SOME_PSA
95 #endif
96 #endif /* MBEDTLS_PSA_CRYPTO_C */
97
98 /* Built-in implementations */
99 #if defined(MBEDTLS_MD5_C)
100 #define MBEDTLS_MD_CAN_MD5
101 #define MBEDTLS_MD_SOME_LEGACY
102 #endif
103 #if defined(MBEDTLS_SHA1_C)
104 #define MBEDTLS_MD_CAN_SHA1
105 #define MBEDTLS_MD_SOME_LEGACY
106 #endif
107 #if defined(MBEDTLS_SHA224_C)
108 #define MBEDTLS_MD_CAN_SHA224
109 #define MBEDTLS_MD_SOME_LEGACY
110 #endif
111 #if defined(MBEDTLS_SHA256_C)
112 #define MBEDTLS_MD_CAN_SHA256
113 #define MBEDTLS_MD_SOME_LEGACY
114 #endif
115 #if defined(MBEDTLS_SHA384_C)
116 #define MBEDTLS_MD_CAN_SHA384
117 #define MBEDTLS_MD_SOME_LEGACY
118 #endif
119 #if defined(MBEDTLS_SHA512_C)
120 #define MBEDTLS_MD_CAN_SHA512
121 #define MBEDTLS_MD_SOME_LEGACY
122 #endif
123 #if defined(MBEDTLS_SHA3_C)
124 #define MBEDTLS_MD_CAN_SHA3_224
125 #define MBEDTLS_MD_CAN_SHA3_256
126 #define MBEDTLS_MD_CAN_SHA3_384
127 #define MBEDTLS_MD_CAN_SHA3_512
128 #define MBEDTLS_MD_SOME_LEGACY
129 #endif
130 #if defined(MBEDTLS_RIPEMD160_C)
131 #define MBEDTLS_MD_CAN_RIPEMD160
132 #define MBEDTLS_MD_SOME_LEGACY
133 #endif
134
135 #endif /* MBEDTLS_MD_LIGHT */
136
137 /** The selected feature is not available. */
138 #define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080
139 /** Bad input parameters to function. */
140 #define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100
141 /** Failed to allocate memory. */
142 #define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180
143 /** Opening or reading of file failed. */
144 #define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200
145
146 #ifdef __cplusplus
147 extern "C" {
148 #endif
149
150 /**
151 * \brief Supported message digests.
152 *
153 * \warning MD5 and SHA-1 are considered weak message digests and
154 * their use constitutes a security risk. We recommend considering
155 * stronger message digests instead.
156 *
157 */
158 /* Note: these are aligned with the definitions of PSA_ALG_ macros for hashes,
159 * in order to enable an efficient implementation of conversion functions.
160 * This is tested by md_to_from_psa() in test_suite_md. */
161 typedef enum {
162 MBEDTLS_MD_NONE=0, /**< None. */
163 MBEDTLS_MD_MD5=0x03, /**< The MD5 message digest. */
164 MBEDTLS_MD_RIPEMD160=0x04, /**< The RIPEMD-160 message digest. */
165 MBEDTLS_MD_SHA1=0x05, /**< The SHA-1 message digest. */
166 MBEDTLS_MD_SHA224=0x08, /**< The SHA-224 message digest. */
167 MBEDTLS_MD_SHA256=0x09, /**< The SHA-256 message digest. */
168 MBEDTLS_MD_SHA384=0x0a, /**< The SHA-384 message digest. */
169 MBEDTLS_MD_SHA512=0x0b, /**< The SHA-512 message digest. */
170 MBEDTLS_MD_SHA3_224=0x10, /**< The SHA3-224 message digest. */
171 MBEDTLS_MD_SHA3_256=0x11, /**< The SHA3-256 message digest. */
172 MBEDTLS_MD_SHA3_384=0x12, /**< The SHA3-384 message digest. */
173 MBEDTLS_MD_SHA3_512=0x13, /**< The SHA3-512 message digest. */
174 } mbedtls_md_type_t;
175
176 /* Note: this should always be >= PSA_HASH_MAX_SIZE
177 * in all builds with both CRYPTO_C and MD_LIGHT.
178 *
179 * This is to make things easier for modules such as TLS that may define a
180 * buffer size using MD_MAX_SIZE in a part of the code that's common to PSA
181 * and legacy, then assume the buffer's size is PSA_HASH_MAX_SIZE in another
182 * part of the code based on PSA.
183 */
184 #if defined(MBEDTLS_MD_CAN_SHA512) || defined(MBEDTLS_MD_CAN_SHA3_512)
185 #define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */
186 #elif defined(MBEDTLS_MD_CAN_SHA384) || defined(MBEDTLS_MD_CAN_SHA3_384)
187 #define MBEDTLS_MD_MAX_SIZE 48 /* longest known is SHA384 */
188 #elif defined(MBEDTLS_MD_CAN_SHA256) || defined(MBEDTLS_MD_CAN_SHA3_256)
189 #define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 */
190 #elif defined(MBEDTLS_MD_CAN_SHA224) || defined(MBEDTLS_MD_CAN_SHA3_224)
191 #define MBEDTLS_MD_MAX_SIZE 28 /* longest known is SHA224 */
192 #else
193 #define MBEDTLS_MD_MAX_SIZE 20 /* longest known is SHA1 or RIPE MD-160
194 or smaller (MD5 and earlier) */
195 #endif
196
197 #if defined(MBEDTLS_MD_CAN_SHA3_224)
198 #define MBEDTLS_MD_MAX_BLOCK_SIZE 144 /* the longest known is SHA3-224 */
199 #elif defined(MBEDTLS_MD_CAN_SHA3_256)
200 #define MBEDTLS_MD_MAX_BLOCK_SIZE 136
201 #elif defined(MBEDTLS_MD_CAN_SHA512) || defined(MBEDTLS_MD_CAN_SHA384)
202 #define MBEDTLS_MD_MAX_BLOCK_SIZE 128
203 #elif defined(MBEDTLS_MD_CAN_SHA3_384)
204 #define MBEDTLS_MD_MAX_BLOCK_SIZE 104
205 #elif defined(MBEDTLS_MD_CAN_SHA3_512)
206 #define MBEDTLS_MD_MAX_BLOCK_SIZE 72
207 #else
208 #define MBEDTLS_MD_MAX_BLOCK_SIZE 64
209 #endif
210
211 /**
212 * Opaque struct.
213 *
214 * Constructed using either #mbedtls_md_info_from_string or
215 * #mbedtls_md_info_from_type.
216 *
217 * Fields can be accessed with #mbedtls_md_get_size,
218 * #mbedtls_md_get_type and #mbedtls_md_get_name.
219 */
220 /* Defined internally in library/md_wrap.h. */
221 typedef struct mbedtls_md_info_t mbedtls_md_info_t;
222
223 /**
224 * Used internally to indicate whether a context uses legacy or PSA.
225 *
226 * Internal use only.
227 */
228 typedef enum {
229 MBEDTLS_MD_ENGINE_LEGACY = 0,
230 MBEDTLS_MD_ENGINE_PSA,
231 } mbedtls_md_engine_t;
232
233 /**
234 * The generic message-digest context.
235 */
236 typedef struct mbedtls_md_context_t {
237 /** Information about the associated message digest. */
238 const mbedtls_md_info_t *MBEDTLS_PRIVATE(md_info);
239
240 #if defined(MBEDTLS_MD_SOME_PSA)
241 /** Are hash operations dispatched to PSA or legacy? */
242 mbedtls_md_engine_t MBEDTLS_PRIVATE(engine);
243 #endif
244
245 /** The digest-specific context (legacy) or the PSA operation. */
246 void *MBEDTLS_PRIVATE(md_ctx);
247
248 #if defined(MBEDTLS_MD_C)
249 /** The HMAC part of the context. */
250 void *MBEDTLS_PRIVATE(hmac_ctx);
251 #endif
252 } mbedtls_md_context_t;
253
254 /**
255 * \brief This function returns the message-digest information
256 * associated with the given digest type.
257 *
258 * \param md_type The type of digest to search for.
259 *
260 * \return The message-digest information associated with \p md_type.
261 * \return NULL if the associated message-digest information is not found.
262 */
263 const mbedtls_md_info_t *mbedtls_md_info_from_type(mbedtls_md_type_t md_type);
264
265 /**
266 * \brief This function initializes a message-digest context without
267 * binding it to a particular message-digest algorithm.
268 *
269 * This function should always be called first. It prepares the
270 * context for mbedtls_md_setup() for binding it to a
271 * message-digest algorithm.
272 */
273 void mbedtls_md_init(mbedtls_md_context_t *ctx);
274
275 /**
276 * \brief This function clears the internal structure of \p ctx and
277 * frees any embedded internal structure, but does not free
278 * \p ctx itself.
279 *
280 * If you have called mbedtls_md_setup() on \p ctx, you must
281 * call mbedtls_md_free() when you are no longer using the
282 * context.
283 * Calling this function if you have previously
284 * called mbedtls_md_init() and nothing else is optional.
285 * You must not call this function if you have not called
286 * mbedtls_md_init().
287 */
288 void mbedtls_md_free(mbedtls_md_context_t *ctx);
289
290
291 /**
292 * \brief This function selects the message digest algorithm to use,
293 * and allocates internal structures.
294 *
295 * It should be called after mbedtls_md_init() or
296 * mbedtls_md_free(). Makes it necessary to call
297 * mbedtls_md_free() later.
298 *
299 * \param ctx The context to set up.
300 * \param md_info The information structure of the message-digest algorithm
301 * to use.
302 * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory),
303 * or non-zero: HMAC is used with this context.
304 *
305 * \return \c 0 on success.
306 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
307 * failure.
308 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
309 */
310 MBEDTLS_CHECK_RETURN_TYPICAL
311 int mbedtls_md_setup(mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac);
312
313 /**
314 * \brief This function clones the state of a message-digest
315 * context.
316 *
317 * \note You must call mbedtls_md_setup() on \c dst before calling
318 * this function.
319 *
320 * \note The two contexts must have the same type,
321 * for example, both are SHA-256.
322 *
323 * \warning This function clones the message-digest state, not the
324 * HMAC state.
325 *
326 * \param dst The destination context.
327 * \param src The context to be cloned.
328 *
329 * \return \c 0 on success.
330 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.
331 * \return #MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE if both contexts are
332 * not using the same engine. This can be avoided by moving
333 * the call to psa_crypto_init() before the first call to
334 * mbedtls_md_setup().
335 */
336 MBEDTLS_CHECK_RETURN_TYPICAL
337 int mbedtls_md_clone(mbedtls_md_context_t *dst,
338 const mbedtls_md_context_t *src);
339
340 /**
341 * \brief This function extracts the message-digest size from the
342 * message-digest information structure.
343 *
344 * \param md_info The information structure of the message-digest algorithm
345 * to use.
346 *
347 * \return The size of the message-digest output in Bytes.
348 */
349 unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info);
350
351 /**
352 * \brief This function gives the message-digest size associated to
353 * message-digest type.
354 *
355 * \param md_type The message-digest type.
356 *
357 * \return The size of the message-digest output in Bytes,
358 * or 0 if the message-digest type is not known.
359 */
mbedtls_md_get_size_from_type(mbedtls_md_type_t md_type)360 static inline unsigned char mbedtls_md_get_size_from_type(mbedtls_md_type_t md_type)
361 {
362 return mbedtls_md_get_size(mbedtls_md_info_from_type(md_type));
363 }
364
365 /**
366 * \brief This function extracts the message-digest type from the
367 * message-digest information structure.
368 *
369 * \param md_info The information structure of the message-digest algorithm
370 * to use.
371 *
372 * \return The type of the message digest.
373 */
374 mbedtls_md_type_t mbedtls_md_get_type(const mbedtls_md_info_t *md_info);
375
376 /**
377 * \brief This function starts a message-digest computation.
378 *
379 * You must call this function after setting up the context
380 * with mbedtls_md_setup(), and before passing data with
381 * mbedtls_md_update().
382 *
383 * \param ctx The generic message-digest context.
384 *
385 * \return \c 0 on success.
386 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
387 * failure.
388 */
389 MBEDTLS_CHECK_RETURN_TYPICAL
390 int mbedtls_md_starts(mbedtls_md_context_t *ctx);
391
392 /**
393 * \brief This function feeds an input buffer into an ongoing
394 * message-digest computation.
395 *
396 * You must call mbedtls_md_starts() before calling this
397 * function. You may call this function multiple times.
398 * Afterwards, call mbedtls_md_finish().
399 *
400 * \param ctx The generic message-digest context.
401 * \param input The buffer holding the input data.
402 * \param ilen The length of the input data.
403 *
404 * \return \c 0 on success.
405 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
406 * failure.
407 */
408 MBEDTLS_CHECK_RETURN_TYPICAL
409 int mbedtls_md_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen);
410
411 /**
412 * \brief This function finishes the digest operation,
413 * and writes the result to the output buffer.
414 *
415 * Call this function after a call to mbedtls_md_starts(),
416 * followed by any number of calls to mbedtls_md_update().
417 * Afterwards, you may either clear the context with
418 * mbedtls_md_free(), or call mbedtls_md_starts() to reuse
419 * the context for another digest operation with the same
420 * algorithm.
421 *
422 * \param ctx The generic message-digest context.
423 * \param output The buffer for the generic message-digest checksum result.
424 *
425 * \return \c 0 on success.
426 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
427 * failure.
428 */
429 MBEDTLS_CHECK_RETURN_TYPICAL
430 int mbedtls_md_finish(mbedtls_md_context_t *ctx, unsigned char *output);
431
432 /**
433 * \brief This function calculates the message-digest of a buffer,
434 * with respect to a configurable message-digest algorithm
435 * in a single call.
436 *
437 * The result is calculated as
438 * Output = message_digest(input buffer).
439 *
440 * \param md_info The information structure of the message-digest algorithm
441 * to use.
442 * \param input The buffer holding the data.
443 * \param ilen The length of the input data.
444 * \param output The generic message-digest checksum result.
445 *
446 * \return \c 0 on success.
447 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
448 * failure.
449 */
450 MBEDTLS_CHECK_RETURN_TYPICAL
451 int mbedtls_md(const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
452 unsigned char *output);
453
454 /**
455 * \brief This function returns the list of digests supported by the
456 * generic digest module.
457 *
458 * \note The list starts with the strongest available hashes.
459 *
460 * \return A statically allocated array of digests. Each element
461 * in the returned list is an integer belonging to the
462 * message-digest enumeration #mbedtls_md_type_t.
463 * The last entry is 0.
464 */
465 const int *mbedtls_md_list(void);
466
467 /**
468 * \brief This function returns the message-digest information
469 * associated with the given digest name.
470 *
471 * \param md_name The name of the digest to search for.
472 *
473 * \return The message-digest information associated with \p md_name.
474 * \return NULL if the associated message-digest information is not found.
475 */
476 const mbedtls_md_info_t *mbedtls_md_info_from_string(const char *md_name);
477
478 /**
479 * \brief This function returns the name of the message digest for
480 * the message-digest information structure given.
481 *
482 * \param md_info The information structure of the message-digest algorithm
483 * to use.
484 *
485 * \return The name of the message digest.
486 */
487 const char *mbedtls_md_get_name(const mbedtls_md_info_t *md_info);
488
489 /**
490 * \brief This function returns the message-digest information
491 * from the given context.
492 *
493 * \param ctx The context from which to extract the information.
494 * This must be initialized (or \c NULL).
495 *
496 * \return The message-digest information associated with \p ctx.
497 * \return \c NULL if \p ctx is \c NULL.
498 */
499 const mbedtls_md_info_t *mbedtls_md_info_from_ctx(
500 const mbedtls_md_context_t *ctx);
501
502 #if defined(MBEDTLS_FS_IO)
503 /**
504 * \brief This function calculates the message-digest checksum
505 * result of the contents of the provided file.
506 *
507 * The result is calculated as
508 * Output = message_digest(file contents).
509 *
510 * \param md_info The information structure of the message-digest algorithm
511 * to use.
512 * \param path The input file name.
513 * \param output The generic message-digest checksum result.
514 *
515 * \return \c 0 on success.
516 * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing
517 * the file pointed by \p path.
518 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
519 */
520 MBEDTLS_CHECK_RETURN_TYPICAL
521 int mbedtls_md_file(const mbedtls_md_info_t *md_info, const char *path,
522 unsigned char *output);
523 #endif /* MBEDTLS_FS_IO */
524
525 /**
526 * \brief This function sets the HMAC key and prepares to
527 * authenticate a new message.
528 *
529 * Call this function after mbedtls_md_setup(), to use
530 * the MD context for an HMAC calculation, then call
531 * mbedtls_md_hmac_update() to provide the input data, and
532 * mbedtls_md_hmac_finish() to get the HMAC value.
533 *
534 * \param ctx The message digest context containing an embedded HMAC
535 * context.
536 * \param key The HMAC secret key.
537 * \param keylen The length of the HMAC key in Bytes.
538 *
539 * \return \c 0 on success.
540 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
541 * failure.
542 */
543 MBEDTLS_CHECK_RETURN_TYPICAL
544 int mbedtls_md_hmac_starts(mbedtls_md_context_t *ctx, const unsigned char *key,
545 size_t keylen);
546
547 /**
548 * \brief This function feeds an input buffer into an ongoing HMAC
549 * computation.
550 *
551 * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
552 * before calling this function.
553 * You may call this function multiple times to pass the
554 * input piecewise.
555 * Afterwards, call mbedtls_md_hmac_finish().
556 *
557 * \param ctx The message digest context containing an embedded HMAC
558 * context.
559 * \param input The buffer holding the input data.
560 * \param ilen The length of the input data.
561 *
562 * \return \c 0 on success.
563 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
564 * failure.
565 */
566 MBEDTLS_CHECK_RETURN_TYPICAL
567 int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input,
568 size_t ilen);
569
570 /**
571 * \brief This function finishes the HMAC operation, and writes
572 * the result to the output buffer.
573 *
574 * Call this function after mbedtls_md_hmac_starts() and
575 * mbedtls_md_hmac_update() to get the HMAC value. Afterwards
576 * you may either call mbedtls_md_free() to clear the context,
577 * or call mbedtls_md_hmac_reset() to reuse the context with
578 * the same HMAC key.
579 *
580 * \param ctx The message digest context containing an embedded HMAC
581 * context.
582 * \param output The generic HMAC checksum result.
583 *
584 * \return \c 0 on success.
585 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
586 * failure.
587 */
588 MBEDTLS_CHECK_RETURN_TYPICAL
589 int mbedtls_md_hmac_finish(mbedtls_md_context_t *ctx, unsigned char *output);
590
591 /**
592 * \brief This function prepares to authenticate a new message with
593 * the same key as the previous HMAC operation.
594 *
595 * You may call this function after mbedtls_md_hmac_finish().
596 * Afterwards call mbedtls_md_hmac_update() to pass the new
597 * input.
598 *
599 * \param ctx The message digest context containing an embedded HMAC
600 * context.
601 *
602 * \return \c 0 on success.
603 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
604 * failure.
605 */
606 MBEDTLS_CHECK_RETURN_TYPICAL
607 int mbedtls_md_hmac_reset(mbedtls_md_context_t *ctx);
608
609 /**
610 * \brief This function calculates the full generic HMAC
611 * on the input buffer with the provided key.
612 *
613 * The function allocates the context, performs the
614 * calculation, and frees the context.
615 *
616 * The HMAC result is calculated as
617 * output = generic HMAC(hmac key, input buffer).
618 *
619 * \param md_info The information structure of the message-digest algorithm
620 * to use.
621 * \param key The HMAC secret key.
622 * \param keylen The length of the HMAC secret key in Bytes.
623 * \param input The buffer holding the input data.
624 * \param ilen The length of the input data.
625 * \param output The generic HMAC result.
626 *
627 * \return \c 0 on success.
628 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
629 * failure.
630 */
631 MBEDTLS_CHECK_RETURN_TYPICAL
632 int mbedtls_md_hmac(const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
633 const unsigned char *input, size_t ilen,
634 unsigned char *output);
635
636 #ifdef __cplusplus
637 }
638 #endif
639
640 #endif /* MBEDTLS_MD_H */
641
