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