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