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