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 #ifdef USE_HISI_MBED 146 MBEDTLS_MD_MD5 = 3, /**< The MD5 message digest. */ 147 #else 148 MBEDTLS_MD_MD5, /**< The MD5 message digest. */ 149 #endif 150 MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */ 151 MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */ 152 MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */ 153 MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */ 154 MBEDTLS_MD_SHA512, /**< The SHA-512 message digest. */ 155 MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */ 156 } mbedtls_md_type_t; 157 158 #if defined(MBEDTLS_MD_CAN_SHA512) 159 #define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */ 160 #elif defined(MBEDTLS_MD_CAN_SHA384) 161 #define MBEDTLS_MD_MAX_SIZE 48 /* longest known is SHA384 */ 162 #elif defined(MBEDTLS_MD_CAN_SHA256) 163 #define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 */ 164 #elif defined(MBEDTLS_MD_CAN_SHA224) 165 #define MBEDTLS_MD_MAX_SIZE 28 /* longest known is SHA224 */ 166 #else 167 #define MBEDTLS_MD_MAX_SIZE 20 /* longest known is SHA1 or RIPE MD-160 168 or smaller (MD5 and earlier) */ 169 #endif 170 171 #if defined(MBEDTLS_MD_CAN_SHA512) 172 #define MBEDTLS_MD_MAX_BLOCK_SIZE 128 173 #else 174 #define MBEDTLS_MD_MAX_BLOCK_SIZE 64 175 #endif 176 177 /** 178 * Opaque struct. 179 * 180 * Constructed using either #mbedtls_md_info_from_string or 181 * #mbedtls_md_info_from_type. 182 * 183 * Fields can be accessed with #mbedtls_md_get_size, 184 * #mbedtls_md_get_type and #mbedtls_md_get_name. 185 */ 186 /* Defined internally in library/md_wrap.h. */ 187 typedef struct mbedtls_md_info_t mbedtls_md_info_t; 188 189 /** 190 * Used internally to indicate whether a context uses legacy or PSA. 191 * 192 * Internal use only. 193 */ 194 typedef enum { 195 MBEDTLS_MD_ENGINE_LEGACY = 0, 196 MBEDTLS_MD_ENGINE_PSA, 197 } mbedtls_md_engine_t; 198 199 /** 200 * The generic message-digest context. 201 */ 202 typedef struct mbedtls_md_context_t { 203 /** Information about the associated message digest. */ 204 const mbedtls_md_info_t *MBEDTLS_PRIVATE(md_info); 205 206 #if defined(MBEDTLS_MD_SOME_PSA) 207 /** Are hash operations dispatched to PSA or legacy? */ 208 mbedtls_md_engine_t MBEDTLS_PRIVATE(engine); 209 #endif 210 211 /** The digest-specific context (legacy) or the PSA operation. */ 212 void *MBEDTLS_PRIVATE(md_ctx); 213 214 #if defined(MBEDTLS_MD_C) 215 /** The HMAC part of the context. */ 216 void *MBEDTLS_PRIVATE(hmac_ctx); 217 #endif 218 } mbedtls_md_context_t; 219 220 /** 221 * \brief This function returns the message-digest information 222 * associated with the given digest type. 223 * 224 * \param md_type The type of digest to search for. 225 * 226 * \return The message-digest information associated with \p md_type. 227 * \return NULL if the associated message-digest information is not found. 228 */ 229 const mbedtls_md_info_t *mbedtls_md_info_from_type(mbedtls_md_type_t md_type); 230 231 /** 232 * \brief This function initializes a message-digest context without 233 * binding it to a particular message-digest algorithm. 234 * 235 * This function should always be called first. It prepares the 236 * context for mbedtls_md_setup() for binding it to a 237 * message-digest algorithm. 238 */ 239 void mbedtls_md_init(mbedtls_md_context_t *ctx); 240 241 /** 242 * \brief This function clears the internal structure of \p ctx and 243 * frees any embedded internal structure, but does not free 244 * \p ctx itself. 245 * 246 * If you have called mbedtls_md_setup() on \p ctx, you must 247 * call mbedtls_md_free() when you are no longer using the 248 * context. 249 * Calling this function if you have previously 250 * called mbedtls_md_init() and nothing else is optional. 251 * You must not call this function if you have not called 252 * mbedtls_md_init(). 253 */ 254 void mbedtls_md_free(mbedtls_md_context_t *ctx); 255 256 257 /** 258 * \brief This function selects the message digest algorithm to use, 259 * and allocates internal structures. 260 * 261 * It should be called after mbedtls_md_init() or 262 * mbedtls_md_free(). Makes it necessary to call 263 * mbedtls_md_free() later. 264 * 265 * \param ctx The context to set up. 266 * \param md_info The information structure of the message-digest algorithm 267 * to use. 268 * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory), 269 * or non-zero: HMAC is used with this context. 270 * 271 * \return \c 0 on success. 272 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 273 * failure. 274 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure. 275 */ 276 MBEDTLS_CHECK_RETURN_TYPICAL 277 int mbedtls_md_setup(mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac); 278 279 /** 280 * \brief This function clones the state of a message-digest 281 * context. 282 * 283 * \note You must call mbedtls_md_setup() on \c dst before calling 284 * this function. 285 * 286 * \note The two contexts must have the same type, 287 * for example, both are SHA-256. 288 * 289 * \warning This function clones the message-digest state, not the 290 * HMAC state. 291 * 292 * \param dst The destination context. 293 * \param src The context to be cloned. 294 * 295 * \return \c 0 on success. 296 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure. 297 * \return #MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE if both contexts are 298 * not using the same engine. This can be avoided by moving 299 * the call to psa_crypto_init() before the first call to 300 * mbedtls_md_setup(). 301 */ 302 MBEDTLS_CHECK_RETURN_TYPICAL 303 int mbedtls_md_clone(mbedtls_md_context_t *dst, 304 const mbedtls_md_context_t *src); 305 306 /** 307 * \brief This function extracts the message-digest size from the 308 * message-digest information structure. 309 * 310 * \param md_info The information structure of the message-digest algorithm 311 * to use. 312 * 313 * \return The size of the message-digest output in Bytes. 314 */ 315 unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info); 316 317 /** 318 * \brief This function extracts the message-digest type from the 319 * message-digest information structure. 320 * 321 * \param md_info The information structure of the message-digest algorithm 322 * to use. 323 * 324 * \return The type of the message digest. 325 */ 326 mbedtls_md_type_t mbedtls_md_get_type(const mbedtls_md_info_t *md_info); 327 328 /** 329 * \brief This function starts a message-digest computation. 330 * 331 * You must call this function after setting up the context 332 * with mbedtls_md_setup(), and before passing data with 333 * mbedtls_md_update(). 334 * 335 * \param ctx The generic message-digest context. 336 * 337 * \return \c 0 on success. 338 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 339 * failure. 340 */ 341 MBEDTLS_CHECK_RETURN_TYPICAL 342 int mbedtls_md_starts(mbedtls_md_context_t *ctx); 343 344 /** 345 * \brief This function feeds an input buffer into an ongoing 346 * message-digest computation. 347 * 348 * You must call mbedtls_md_starts() before calling this 349 * function. You may call this function multiple times. 350 * Afterwards, call mbedtls_md_finish(). 351 * 352 * \param ctx The generic message-digest context. 353 * \param input The buffer holding the input data. 354 * \param ilen The length of the input data. 355 * 356 * \return \c 0 on success. 357 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 358 * failure. 359 */ 360 MBEDTLS_CHECK_RETURN_TYPICAL 361 int mbedtls_md_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen); 362 363 /** 364 * \brief This function finishes the digest operation, 365 * and writes the result to the output buffer. 366 * 367 * Call this function after a call to mbedtls_md_starts(), 368 * followed by any number of calls to mbedtls_md_update(). 369 * Afterwards, you may either clear the context with 370 * mbedtls_md_free(), or call mbedtls_md_starts() to reuse 371 * the context for another digest operation with the same 372 * algorithm. 373 * 374 * \param ctx The generic message-digest context. 375 * \param output The buffer for the generic message-digest checksum result. 376 * 377 * \return \c 0 on success. 378 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 379 * failure. 380 */ 381 MBEDTLS_CHECK_RETURN_TYPICAL 382 int mbedtls_md_finish(mbedtls_md_context_t *ctx, unsigned char *output); 383 384 /** 385 * \brief This function calculates the message-digest of a buffer, 386 * with respect to a configurable message-digest algorithm 387 * in a single call. 388 * 389 * The result is calculated as 390 * Output = message_digest(input buffer). 391 * 392 * \param md_info The information structure of the message-digest algorithm 393 * to use. 394 * \param input The buffer holding the data. 395 * \param ilen The length of the input data. 396 * \param output The generic message-digest checksum result. 397 * 398 * \return \c 0 on success. 399 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 400 * failure. 401 */ 402 MBEDTLS_CHECK_RETURN_TYPICAL 403 int mbedtls_md(const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, 404 unsigned char *output); 405 406 /** 407 * \brief This function returns the list of digests supported by the 408 * generic digest module. 409 * 410 * \note The list starts with the strongest available hashes. 411 * 412 * \return A statically allocated array of digests. Each element 413 * in the returned list is an integer belonging to the 414 * message-digest enumeration #mbedtls_md_type_t. 415 * The last entry is 0. 416 */ 417 const int *mbedtls_md_list(void); 418 419 /** 420 * \brief This function returns the message-digest information 421 * associated with the given digest name. 422 * 423 * \param md_name The name of the digest to search for. 424 * 425 * \return The message-digest information associated with \p md_name. 426 * \return NULL if the associated message-digest information is not found. 427 */ 428 const mbedtls_md_info_t *mbedtls_md_info_from_string(const char *md_name); 429 430 /** 431 * \brief This function extracts the message-digest name from the 432 * message-digest information structure. 433 * 434 * \param md_info The information structure of the message-digest algorithm 435 * to use. 436 * 437 * \return The name of the message digest. 438 */ 439 const char *mbedtls_md_get_name(const mbedtls_md_info_t *md_info); 440 441 /** 442 * \brief This function returns the message-digest information 443 * from the given context. 444 * 445 * \param ctx The context from which to extract the information. 446 * This must be initialized (or \c NULL). 447 * 448 * \return The message-digest information associated with \p ctx. 449 * \return \c NULL if \p ctx is \c NULL. 450 */ 451 const mbedtls_md_info_t *mbedtls_md_info_from_ctx( 452 const mbedtls_md_context_t *ctx); 453 454 #if defined(MBEDTLS_FS_IO) 455 /** 456 * \brief This function calculates the message-digest checksum 457 * result of the contents of the provided file. 458 * 459 * The result is calculated as 460 * Output = message_digest(file contents). 461 * 462 * \param md_info The information structure of the message-digest algorithm 463 * to use. 464 * \param path The input file name. 465 * \param output The generic message-digest checksum result. 466 * 467 * \return \c 0 on success. 468 * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing 469 * the file pointed by \p path. 470 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL. 471 */ 472 MBEDTLS_CHECK_RETURN_TYPICAL 473 int mbedtls_md_file(const mbedtls_md_info_t *md_info, const char *path, 474 unsigned char *output); 475 #endif /* MBEDTLS_FS_IO */ 476 477 /** 478 * \brief This function sets the HMAC key and prepares to 479 * authenticate a new message. 480 * 481 * Call this function after mbedtls_md_setup(), to use 482 * the MD context for an HMAC calculation, then call 483 * mbedtls_md_hmac_update() to provide the input data, and 484 * mbedtls_md_hmac_finish() to get the HMAC value. 485 * 486 * \param ctx The message digest context containing an embedded HMAC 487 * context. 488 * \param key The HMAC secret key. 489 * \param keylen The length of the HMAC key in Bytes. 490 * 491 * \return \c 0 on success. 492 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 493 * failure. 494 */ 495 MBEDTLS_CHECK_RETURN_TYPICAL 496 int mbedtls_md_hmac_starts(mbedtls_md_context_t *ctx, const unsigned char *key, 497 size_t keylen); 498 499 /** 500 * \brief This function feeds an input buffer into an ongoing HMAC 501 * computation. 502 * 503 * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() 504 * before calling this function. 505 * You may call this function multiple times to pass the 506 * input piecewise. 507 * Afterwards, call mbedtls_md_hmac_finish(). 508 * 509 * \param ctx The message digest context containing an embedded HMAC 510 * context. 511 * \param input The buffer holding the input data. 512 * \param ilen The length of the input data. 513 * 514 * \return \c 0 on success. 515 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 516 * failure. 517 */ 518 MBEDTLS_CHECK_RETURN_TYPICAL 519 int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input, 520 size_t ilen); 521 522 /** 523 * \brief This function finishes the HMAC operation, and writes 524 * the result to the output buffer. 525 * 526 * Call this function after mbedtls_md_hmac_starts() and 527 * mbedtls_md_hmac_update() to get the HMAC value. Afterwards 528 * you may either call mbedtls_md_free() to clear the context, 529 * or call mbedtls_md_hmac_reset() to reuse the context with 530 * the same HMAC key. 531 * 532 * \param ctx The message digest context containing an embedded HMAC 533 * context. 534 * \param output The generic HMAC checksum result. 535 * 536 * \return \c 0 on success. 537 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 538 * failure. 539 */ 540 MBEDTLS_CHECK_RETURN_TYPICAL 541 int mbedtls_md_hmac_finish(mbedtls_md_context_t *ctx, unsigned char *output); 542 543 /** 544 * \brief This function prepares to authenticate a new message with 545 * the same key as the previous HMAC operation. 546 * 547 * You may call this function after mbedtls_md_hmac_finish(). 548 * Afterwards call mbedtls_md_hmac_update() to pass the new 549 * input. 550 * 551 * \param ctx The message digest context containing an embedded HMAC 552 * context. 553 * 554 * \return \c 0 on success. 555 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 556 * failure. 557 */ 558 MBEDTLS_CHECK_RETURN_TYPICAL 559 int mbedtls_md_hmac_reset(mbedtls_md_context_t *ctx); 560 561 /** 562 * \brief This function calculates the full generic HMAC 563 * on the input buffer with the provided key. 564 * 565 * The function allocates the context, performs the 566 * calculation, and frees the context. 567 * 568 * The HMAC result is calculated as 569 * output = generic HMAC(hmac key, input buffer). 570 * 571 * \param md_info The information structure of the message-digest algorithm 572 * to use. 573 * \param key The HMAC secret key. 574 * \param keylen The length of the HMAC secret key in Bytes. 575 * \param input The buffer holding the input data. 576 * \param ilen The length of the input data. 577 * \param output The generic HMAC result. 578 * 579 * \return \c 0 on success. 580 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 581 * failure. 582 */ 583 MBEDTLS_CHECK_RETURN_TYPICAL 584 int mbedtls_md_hmac(const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, 585 const unsigned char *input, size_t ilen, 586 unsigned char *output); 587 588 #ifdef __cplusplus 589 } 590 #endif 591 592 #endif /* MBEDTLS_MD_H */ 593