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