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