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