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