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