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