1 /** 2 * \file md.h 3 * 4 * \brief This file contains the generic message-digest wrapper. 5 * 6 * \author Adriaan de Jong <dejong@fox-it.com> 7 */ 8 /* 9 * Copyright The Mbed TLS Contributors 10 * SPDX-License-Identifier: Apache-2.0 11 * 12 * Licensed under the Apache License, Version 2.0 (the "License"); you may 13 * not use this file except in compliance with the License. 14 * You may obtain a copy of the License at 15 * 16 * http://www.apache.org/licenses/LICENSE-2.0 17 * 18 * Unless required by applicable law or agreed to in writing, software 19 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 20 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 * See the License for the specific language governing permissions and 22 * limitations under the License. 23 */ 24 25 #ifndef MBEDTLS_MD_H 26 #define MBEDTLS_MD_H 27 28 #include <stddef.h> 29 30 #if !defined(MBEDTLS_CONFIG_FILE) 31 #include "mbedtls/config.h" 32 #else 33 #include MBEDTLS_CONFIG_FILE 34 #endif 35 #include "mbedtls/platform_util.h" 36 37 /** The selected feature is not available. */ 38 #define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080 39 /** Bad input parameters to function. */ 40 #define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100 41 /** Failed to allocate memory. */ 42 #define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180 43 /** Opening or reading of file failed. */ 44 #define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200 45 46 /* MBEDTLS_ERR_MD_HW_ACCEL_FAILED is deprecated and should not be used. */ 47 /** MD hardware accelerator failed. */ 48 #define MBEDTLS_ERR_MD_HW_ACCEL_FAILED -0x5280 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /** 55 * \brief Supported message digests. 56 * 57 * \warning MD2, MD4, MD5 and SHA-1 are considered weak message digests and 58 * their use constitutes a security risk. We recommend considering 59 * stronger message digests instead. 60 * 61 */ 62 typedef enum { 63 MBEDTLS_MD_NONE=0, /**< None. */ 64 MBEDTLS_MD_MD2, /**< The MD2 message digest. */ 65 MBEDTLS_MD_MD4, /**< The MD4 message digest. */ 66 MBEDTLS_MD_MD5, /**< The MD5 message digest. */ 67 MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */ 68 MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */ 69 MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */ 70 MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */ 71 MBEDTLS_MD_SHA512, /**< The SHA-512 message digest. */ 72 MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */ 73 } mbedtls_md_type_t; 74 75 #if defined(MBEDTLS_SHA512_C) 76 #define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */ 77 #else 78 #define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 or less */ 79 #endif 80 81 #if defined(MBEDTLS_SHA512_C) 82 #define MBEDTLS_MD_MAX_BLOCK_SIZE 128 83 #else 84 #define MBEDTLS_MD_MAX_BLOCK_SIZE 64 85 #endif 86 87 /** 88 * Opaque struct defined in md_internal.h. 89 */ 90 typedef struct mbedtls_md_info_t mbedtls_md_info_t; 91 92 /** 93 * The generic message-digest context. 94 */ 95 typedef struct mbedtls_md_context_t 96 { 97 /** Information about the associated message digest. */ 98 const mbedtls_md_info_t *md_info; 99 100 /** The digest-specific context. */ 101 void *md_ctx; 102 103 /** The HMAC part of the context. */ 104 void *hmac_ctx; 105 } mbedtls_md_context_t; 106 107 /** 108 * \brief This function returns the list of digests supported by the 109 * generic digest module. 110 * 111 * \note The list starts with the strongest available hashes. 112 * 113 * \return A statically allocated array of digests. Each element 114 * in the returned list is an integer belonging to the 115 * message-digest enumeration #mbedtls_md_type_t. 116 * The last entry is 0. 117 */ 118 const int *mbedtls_md_list( void ); 119 120 /** 121 * \brief This function returns the message-digest information 122 * associated with the given digest name. 123 * 124 * \param md_name The name of the digest to search for. 125 * 126 * \return The message-digest information associated with \p md_name. 127 * \return NULL if the associated message-digest information is not found. 128 */ 129 const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name ); 130 131 /** 132 * \brief This function returns the message-digest information 133 * associated with the given digest type. 134 * 135 * \param md_type The type of digest to search for. 136 * 137 * \return The message-digest information associated with \p md_type. 138 * \return NULL if the associated message-digest information is not found. 139 */ 140 const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type ); 141 142 /** 143 * \brief This function initializes a message-digest context without 144 * binding it to a particular message-digest algorithm. 145 * 146 * This function should always be called first. It prepares the 147 * context for mbedtls_md_setup() for binding it to a 148 * message-digest algorithm. 149 */ 150 void mbedtls_md_init( mbedtls_md_context_t *ctx ); 151 152 /** 153 * \brief This function clears the internal structure of \p ctx and 154 * frees any embedded internal structure, but does not free 155 * \p ctx itself. 156 * 157 * If you have called mbedtls_md_setup() on \p ctx, you must 158 * call mbedtls_md_free() when you are no longer using the 159 * context. 160 * Calling this function if you have previously 161 * called mbedtls_md_init() and nothing else is optional. 162 * You must not call this function if you have not called 163 * mbedtls_md_init(). 164 */ 165 void mbedtls_md_free( mbedtls_md_context_t *ctx ); 166 167 #if ! defined(MBEDTLS_DEPRECATED_REMOVED) 168 #if defined(MBEDTLS_DEPRECATED_WARNING) 169 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 170 #else 171 #define MBEDTLS_DEPRECATED 172 #endif 173 /** 174 * \brief This function selects the message digest algorithm to use, 175 * and allocates internal structures. 176 * 177 * It should be called after mbedtls_md_init() or mbedtls_md_free(). 178 * Makes it necessary to call mbedtls_md_free() later. 179 * 180 * \deprecated Superseded by mbedtls_md_setup() in 2.0.0 181 * 182 * \param ctx The context to set up. 183 * \param md_info The information structure of the message-digest algorithm 184 * to use. 185 * 186 * \return \c 0 on success. 187 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 188 * failure. 189 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure. 190 */ 191 int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED; 192 #undef MBEDTLS_DEPRECATED 193 #endif /* MBEDTLS_DEPRECATED_REMOVED */ 194 195 /** 196 * \brief This function selects the message digest algorithm to use, 197 * and allocates internal structures. 198 * 199 * It should be called after mbedtls_md_init() or 200 * mbedtls_md_free(). Makes it necessary to call 201 * mbedtls_md_free() later. 202 * 203 * \param ctx The context to set up. 204 * \param md_info The information structure of the message-digest algorithm 205 * to use. 206 * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory), 207 * or non-zero: HMAC is used with this context. 208 * 209 * \return \c 0 on success. 210 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 211 * failure. 212 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure. 213 */ 214 MBEDTLS_CHECK_RETURN_TYPICAL 215 int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac ); 216 217 /** 218 * \brief This function clones the state of an message-digest 219 * context. 220 * 221 * \note You must call mbedtls_md_setup() on \c dst before calling 222 * this function. 223 * 224 * \note The two contexts must have the same type, 225 * for example, both are SHA-256. 226 * 227 * \warning This function clones the message-digest state, not the 228 * HMAC state. 229 * 230 * \param dst The destination context. 231 * \param src The context to be cloned. 232 * 233 * \return \c 0 on success. 234 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure. 235 */ 236 MBEDTLS_CHECK_RETURN_TYPICAL 237 int mbedtls_md_clone( mbedtls_md_context_t *dst, 238 const mbedtls_md_context_t *src ); 239 240 /** 241 * \brief This function extracts the message-digest size from the 242 * message-digest information structure. 243 * 244 * \param md_info The information structure of the message-digest algorithm 245 * to use. 246 * 247 * \return The size of the message-digest output in Bytes. 248 */ 249 unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info ); 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 extracts the message-digest name from the 264 * message-digest information structure. 265 * 266 * \param md_info The information structure of the message-digest algorithm 267 * to use. 268 * 269 * \return The name of the message digest. 270 */ 271 const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info ); 272 273 /** 274 * \brief This function starts a message-digest computation. 275 * 276 * You must call this function after setting up the context 277 * with mbedtls_md_setup(), and before passing data with 278 * mbedtls_md_update(). 279 * 280 * \param ctx The generic message-digest context. 281 * 282 * \return \c 0 on success. 283 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 284 * failure. 285 */ 286 MBEDTLS_CHECK_RETURN_TYPICAL 287 int mbedtls_md_starts( mbedtls_md_context_t *ctx ); 288 289 /** 290 * \brief This function feeds an input buffer into an ongoing 291 * message-digest computation. 292 * 293 * You must call mbedtls_md_starts() before calling this 294 * function. You may call this function multiple times. 295 * Afterwards, call mbedtls_md_finish(). 296 * 297 * \param ctx The generic message-digest context. 298 * \param input The buffer holding the input data. 299 * \param ilen The length of the input data. 300 * 301 * \return \c 0 on success. 302 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 303 * failure. 304 */ 305 MBEDTLS_CHECK_RETURN_TYPICAL 306 int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen ); 307 308 /** 309 * \brief This function finishes the digest operation, 310 * and writes the result to the output buffer. 311 * 312 * Call this function after a call to mbedtls_md_starts(), 313 * followed by any number of calls to mbedtls_md_update(). 314 * Afterwards, you may either clear the context with 315 * mbedtls_md_free(), or call mbedtls_md_starts() to reuse 316 * the context for another digest operation with the same 317 * algorithm. 318 * 319 * \param ctx The generic message-digest context. 320 * \param output The buffer for the generic message-digest checksum result. 321 * 322 * \return \c 0 on success. 323 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 324 * failure. 325 */ 326 MBEDTLS_CHECK_RETURN_TYPICAL 327 int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output ); 328 329 /** 330 * \brief This function calculates the message-digest of a buffer, 331 * with respect to a configurable message-digest algorithm 332 * in a single call. 333 * 334 * The result is calculated as 335 * Output = message_digest(input buffer). 336 * 337 * \param md_info The information structure of the message-digest algorithm 338 * to use. 339 * \param input The buffer holding the data. 340 * \param ilen The length of the input data. 341 * \param output The generic message-digest checksum result. 342 * 343 * \return \c 0 on success. 344 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 345 * failure. 346 */ 347 MBEDTLS_CHECK_RETURN_TYPICAL 348 int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, 349 unsigned char *output ); 350 351 #if defined(MBEDTLS_FS_IO) 352 /** 353 * \brief This function calculates the message-digest checksum 354 * result of the contents of the provided file. 355 * 356 * The result is calculated as 357 * Output = message_digest(file contents). 358 * 359 * \param md_info The information structure of the message-digest algorithm 360 * to use. 361 * \param path The input file name. 362 * \param output The generic message-digest checksum result. 363 * 364 * \return \c 0 on success. 365 * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing 366 * the file pointed by \p path. 367 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL. 368 */ 369 MBEDTLS_CHECK_RETURN_TYPICAL 370 int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path, 371 unsigned char *output ); 372 #endif /* MBEDTLS_FS_IO */ 373 374 /** 375 * \brief This function sets the HMAC key and prepares to 376 * authenticate a new message. 377 * 378 * Call this function after mbedtls_md_setup(), to use 379 * the MD context for an HMAC calculation, then call 380 * mbedtls_md_hmac_update() to provide the input data, and 381 * mbedtls_md_hmac_finish() to get the HMAC value. 382 * 383 * \param ctx The message digest context containing an embedded HMAC 384 * context. 385 * \param key The HMAC secret key. 386 * \param keylen The length of the HMAC key in Bytes. 387 * 388 * \return \c 0 on success. 389 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 390 * failure. 391 */ 392 MBEDTLS_CHECK_RETURN_TYPICAL 393 int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key, 394 size_t keylen ); 395 396 /** 397 * \brief This function feeds an input buffer into an ongoing HMAC 398 * computation. 399 * 400 * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() 401 * before calling this function. 402 * You may call this function multiple times to pass the 403 * input piecewise. 404 * Afterwards, call mbedtls_md_hmac_finish(). 405 * 406 * \param ctx The message digest context containing an embedded HMAC 407 * context. 408 * \param input The buffer holding the input data. 409 * \param ilen The length of the input data. 410 * 411 * \return \c 0 on success. 412 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 413 * failure. 414 */ 415 MBEDTLS_CHECK_RETURN_TYPICAL 416 int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input, 417 size_t ilen ); 418 419 /** 420 * \brief This function finishes the HMAC operation, and writes 421 * the result to the output buffer. 422 * 423 * Call this function after mbedtls_md_hmac_starts() and 424 * mbedtls_md_hmac_update() to get the HMAC value. Afterwards 425 * you may either call mbedtls_md_free() to clear the context, 426 * or call mbedtls_md_hmac_reset() to reuse the context with 427 * the same HMAC key. 428 * 429 * \param ctx The message digest context containing an embedded HMAC 430 * context. 431 * \param output The generic HMAC checksum result. 432 * 433 * \return \c 0 on success. 434 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 435 * failure. 436 */ 437 MBEDTLS_CHECK_RETURN_TYPICAL 438 int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output); 439 440 /** 441 * \brief This function prepares to authenticate a new message with 442 * the same key as the previous HMAC operation. 443 * 444 * You may call this function after mbedtls_md_hmac_finish(). 445 * Afterwards call mbedtls_md_hmac_update() to pass the new 446 * input. 447 * 448 * \param ctx The message digest context containing an embedded HMAC 449 * context. 450 * 451 * \return \c 0 on success. 452 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 453 * failure. 454 */ 455 MBEDTLS_CHECK_RETURN_TYPICAL 456 int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx ); 457 458 /** 459 * \brief This function calculates the full generic HMAC 460 * on the input buffer with the provided key. 461 * 462 * The function allocates the context, performs the 463 * calculation, and frees the context. 464 * 465 * The HMAC result is calculated as 466 * output = generic HMAC(hmac key, input buffer). 467 * 468 * \param md_info The information structure of the message-digest algorithm 469 * to use. 470 * \param key The HMAC secret key. 471 * \param keylen The length of the HMAC secret key in Bytes. 472 * \param input The buffer holding the input data. 473 * \param ilen The length of the input data. 474 * \param output The generic HMAC result. 475 * 476 * \return \c 0 on success. 477 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 478 * failure. 479 */ 480 MBEDTLS_CHECK_RETURN_TYPICAL 481 int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, 482 const unsigned char *input, size_t ilen, 483 unsigned char *output ); 484 485 /* Internal use */ 486 MBEDTLS_CHECK_RETURN_TYPICAL 487 int mbedtls_md_process( mbedtls_md_context_t *ctx, const unsigned char *data ); 488 489 #ifdef __cplusplus 490 } 491 #endif 492 493 #endif /* MBEDTLS_MD_H */ 494