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 OR GPL-2.0-or-later 11 * 12 * This file is provided under the Apache License 2.0, or the 13 * GNU General Public License v2.0 or later. 14 * 15 * ********** 16 * Apache License 2.0: 17 * 18 * Licensed under the Apache License, Version 2.0 (the "License"); you may 19 * not use this file except in compliance with the License. 20 * You may obtain a copy of the License at 21 * 22 * http://www.apache.org/licenses/LICENSE-2.0 23 * 24 * Unless required by applicable law or agreed to in writing, software 25 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 26 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 27 * See the License for the specific language governing permissions and 28 * limitations under the License. 29 * 30 * ********** 31 * 32 * ********** 33 * GNU General Public License v2.0 or later: 34 * 35 * This program is free software; you can redistribute it and/or modify 36 * it under the terms of the GNU General Public License as published by 37 * the Free Software Foundation; either version 2 of the License, or 38 * (at your option) any later version. 39 * 40 * This program is distributed in the hope that it will be useful, 41 * but WITHOUT ANY WARRANTY; without even the implied warranty of 42 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 43 * GNU General Public License for more details. 44 * 45 * You should have received a copy of the GNU General Public License along 46 * with this program; if not, write to the Free Software Foundation, Inc., 47 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 48 * 49 * ********** 50 */ 51 52 #ifndef MBEDTLS_MD_H 53 #define MBEDTLS_MD_H 54 55 #include <stddef.h> 56 57 #if !defined(MBEDTLS_CONFIG_FILE) 58 #include "config.h" 59 #else 60 #include MBEDTLS_CONFIG_FILE 61 #endif 62 63 #define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080 /**< The selected feature is not available. */ 64 #define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100 /**< Bad input parameters to function. */ 65 #define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180 /**< Failed to allocate memory. */ 66 #define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200 /**< Opening or reading of file failed. */ 67 68 /* MBEDTLS_ERR_MD_HW_ACCEL_FAILED is deprecated and should not be used. */ 69 #define MBEDTLS_ERR_MD_HW_ACCEL_FAILED -0x5280 /**< MD hardware accelerator failed. */ 70 71 #ifdef __cplusplus 72 extern "C" { 73 #endif 74 75 /** 76 * \brief Supported message digests. 77 * 78 * \warning MD2, MD4, MD5 and SHA-1 are considered weak message digests and 79 * their use constitutes a security risk. We recommend considering 80 * stronger message digests instead. 81 * 82 */ 83 typedef enum { 84 MBEDTLS_MD_NONE=0, /**< None. */ 85 MBEDTLS_MD_MD2, /**< The MD2 message digest. */ 86 MBEDTLS_MD_MD4, /**< The MD4 message digest. */ 87 MBEDTLS_MD_MD5, /**< The MD5 message digest. */ 88 MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */ 89 MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */ 90 MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */ 91 MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */ 92 MBEDTLS_MD_SHA512, /**< The SHA-512 message digest. */ 93 MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */ 94 } mbedtls_md_type_t; 95 96 #if defined(MBEDTLS_SHA512_C) 97 #define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */ 98 #else 99 #define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 or less */ 100 #endif 101 102 /** 103 * Opaque struct defined in md_internal.h. 104 */ 105 typedef struct mbedtls_md_info_t mbedtls_md_info_t; 106 107 /** 108 * The generic message-digest context. 109 */ 110 typedef struct mbedtls_md_context_t 111 { 112 /** Information about the associated message digest. */ 113 const mbedtls_md_info_t *md_info; 114 115 /** The digest-specific context. */ 116 void *md_ctx; 117 118 /** The HMAC part of the context. */ 119 void *hmac_ctx; 120 } mbedtls_md_context_t; 121 122 /** 123 * \brief This function returns the list of digests supported by the 124 * generic digest module. 125 * 126 * \note The list starts with the strongest available hashes. 127 * 128 * \return A statically allocated array of digests. Each element 129 * in the returned list is an integer belonging to the 130 * message-digest enumeration #mbedtls_md_type_t. 131 * The last entry is 0. 132 */ 133 const int *mbedtls_md_list( void ); 134 135 /** 136 * \brief This function returns the message-digest information 137 * associated with the given digest name. 138 * 139 * \param md_name The name of the digest to search for. 140 * 141 * \return The message-digest information associated with \p md_name. 142 * \return NULL if the associated message-digest information is not found. 143 */ 144 const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name ); 145 146 /** 147 * \brief This function returns the message-digest information 148 * associated with the given digest type. 149 * 150 * \param md_type The type of digest to search for. 151 * 152 * \return The message-digest information associated with \p md_type. 153 * \return NULL if the associated message-digest information is not found. 154 */ 155 const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type ); 156 157 /** 158 * \brief This function initializes a message-digest context without 159 * binding it to a particular message-digest algorithm. 160 * 161 * This function should always be called first. It prepares the 162 * context for mbedtls_md_setup() for binding it to a 163 * message-digest algorithm. 164 */ 165 void mbedtls_md_init( mbedtls_md_context_t *ctx ); 166 167 /** 168 * \brief This function clears the internal structure of \p ctx and 169 * frees any embedded internal structure, but does not free 170 * \p ctx itself. 171 * 172 * If you have called mbedtls_md_setup() on \p ctx, you must 173 * call mbedtls_md_free() when you are no longer using the 174 * context. 175 * Calling this function if you have previously 176 * called mbedtls_md_init() and nothing else is optional. 177 * You must not call this function if you have not called 178 * mbedtls_md_init(). 179 */ 180 void mbedtls_md_free( mbedtls_md_context_t *ctx ); 181 182 #if ! defined(MBEDTLS_DEPRECATED_REMOVED) 183 #if defined(MBEDTLS_DEPRECATED_WARNING) 184 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 185 #else 186 #define MBEDTLS_DEPRECATED 187 #endif 188 /** 189 * \brief This function selects the message digest algorithm to use, 190 * and allocates internal structures. 191 * 192 * It should be called after mbedtls_md_init() or mbedtls_md_free(). 193 * Makes it necessary to call mbedtls_md_free() later. 194 * 195 * \deprecated Superseded by mbedtls_md_setup() in 2.0.0 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 * 201 * \return \c 0 on success. 202 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 203 * failure. 204 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure. 205 */ 206 int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED; 207 #undef MBEDTLS_DEPRECATED 208 #endif /* MBEDTLS_DEPRECATED_REMOVED */ 209 210 /** 211 * \brief This function selects the message digest algorithm to use, 212 * and allocates internal structures. 213 * 214 * It should be called after mbedtls_md_init() or 215 * mbedtls_md_free(). Makes it necessary to call 216 * mbedtls_md_free() later. 217 * 218 * \param ctx The context to set up. 219 * \param md_info The information structure of the message-digest algorithm 220 * to use. 221 * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory), 222 * or non-zero: HMAC is used with this context. 223 * 224 * \return \c 0 on success. 225 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 226 * failure. 227 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure. 228 */ 229 int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac ); 230 231 /** 232 * \brief This function clones the state of an message-digest 233 * context. 234 * 235 * \note You must call mbedtls_md_setup() on \c dst before calling 236 * this function. 237 * 238 * \note The two contexts must have the same type, 239 * for example, both are SHA-256. 240 * 241 * \warning This function clones the message-digest state, not the 242 * HMAC state. 243 * 244 * \param dst The destination context. 245 * \param src The context to be cloned. 246 * 247 * \return \c 0 on success. 248 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure. 249 */ 250 int mbedtls_md_clone( mbedtls_md_context_t *dst, 251 const mbedtls_md_context_t *src ); 252 253 /** 254 * \brief This function extracts the message-digest size from the 255 * message-digest information structure. 256 * 257 * \param md_info The information structure of the message-digest algorithm 258 * to use. 259 * 260 * \return The size of the message-digest output in Bytes. 261 */ 262 unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info ); 263 264 /** 265 * \brief This function extracts the message-digest type from the 266 * message-digest information structure. 267 * 268 * \param md_info The information structure of the message-digest algorithm 269 * to use. 270 * 271 * \return The type of the message digest. 272 */ 273 mbedtls_md_type_t mbedtls_md_get_type( const mbedtls_md_info_t *md_info ); 274 275 /** 276 * \brief This function extracts the message-digest name from the 277 * message-digest information structure. 278 * 279 * \param md_info The information structure of the message-digest algorithm 280 * to use. 281 * 282 * \return The name of the message digest. 283 */ 284 const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info ); 285 286 /** 287 * \brief This function starts a message-digest computation. 288 * 289 * You must call this function after setting up the context 290 * with mbedtls_md_setup(), and before passing data with 291 * mbedtls_md_update(). 292 * 293 * \param ctx The generic message-digest context. 294 * 295 * \return \c 0 on success. 296 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 297 * failure. 298 */ 299 int mbedtls_md_starts( mbedtls_md_context_t *ctx ); 300 301 /** 302 * \brief This function feeds an input buffer into an ongoing 303 * message-digest computation. 304 * 305 * You must call mbedtls_md_starts() before calling this 306 * function. You may call this function multiple times. 307 * Afterwards, call mbedtls_md_finish(). 308 * 309 * \param ctx The generic message-digest context. 310 * \param input The buffer holding the input data. 311 * \param ilen The length of the input data. 312 * 313 * \return \c 0 on success. 314 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 315 * failure. 316 */ 317 int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen ); 318 319 /** 320 * \brief This function finishes the digest operation, 321 * and writes the result to the output buffer. 322 * 323 * Call this function after a call to mbedtls_md_starts(), 324 * followed by any number of calls to mbedtls_md_update(). 325 * Afterwards, you may either clear the context with 326 * mbedtls_md_free(), or call mbedtls_md_starts() to reuse 327 * the context for another digest operation with the same 328 * algorithm. 329 * 330 * \param ctx The generic message-digest context. 331 * \param output The buffer for the generic message-digest checksum result. 332 * 333 * \return \c 0 on success. 334 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 335 * failure. 336 */ 337 int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output ); 338 339 /** 340 * \brief This function calculates the message-digest of a buffer, 341 * with respect to a configurable message-digest algorithm 342 * in a single call. 343 * 344 * The result is calculated as 345 * Output = message_digest(input buffer). 346 * 347 * \param md_info The information structure of the message-digest algorithm 348 * to use. 349 * \param input The buffer holding the data. 350 * \param ilen The length of the input data. 351 * \param output The generic message-digest checksum result. 352 * 353 * \return \c 0 on success. 354 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 355 * failure. 356 */ 357 int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, 358 unsigned char *output ); 359 360 #if defined(MBEDTLS_FS_IO) 361 /** 362 * \brief This function calculates the message-digest checksum 363 * result of the contents of the provided file. 364 * 365 * The result is calculated as 366 * Output = message_digest(file contents). 367 * 368 * \param md_info The information structure of the message-digest algorithm 369 * to use. 370 * \param path The input file name. 371 * \param output The generic message-digest checksum result. 372 * 373 * \return \c 0 on success. 374 * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing 375 * the file pointed by \p path. 376 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL. 377 */ 378 int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path, 379 unsigned char *output ); 380 #endif /* MBEDTLS_FS_IO */ 381 382 /** 383 * \brief This function sets the HMAC key and prepares to 384 * authenticate a new message. 385 * 386 * Call this function after mbedtls_md_setup(), to use 387 * the MD context for an HMAC calculation, then call 388 * mbedtls_md_hmac_update() to provide the input data, and 389 * mbedtls_md_hmac_finish() to get the HMAC value. 390 * 391 * \param ctx The message digest context containing an embedded HMAC 392 * context. 393 * \param key The HMAC secret key. 394 * \param keylen The length of the HMAC key in Bytes. 395 * 396 * \return \c 0 on success. 397 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 398 * failure. 399 */ 400 int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key, 401 size_t keylen ); 402 403 /** 404 * \brief This function feeds an input buffer into an ongoing HMAC 405 * computation. 406 * 407 * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() 408 * before calling this function. 409 * You may call this function multiple times to pass the 410 * input piecewise. 411 * Afterwards, call mbedtls_md_hmac_finish(). 412 * 413 * \param ctx The message digest context containing an embedded HMAC 414 * context. 415 * \param input The buffer holding the input data. 416 * \param ilen The length of the input data. 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_update( mbedtls_md_context_t *ctx, const unsigned char *input, 423 size_t ilen ); 424 425 /** 426 * \brief This function finishes the HMAC operation, and writes 427 * the result to the output buffer. 428 * 429 * Call this function after mbedtls_md_hmac_starts() and 430 * mbedtls_md_hmac_update() to get the HMAC value. Afterwards 431 * you may either call mbedtls_md_free() to clear the context, 432 * or call mbedtls_md_hmac_reset() to reuse the context with 433 * the same HMAC key. 434 * 435 * \param ctx The message digest context containing an embedded HMAC 436 * context. 437 * \param output The generic HMAC checksum result. 438 * 439 * \return \c 0 on success. 440 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 441 * failure. 442 */ 443 int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output); 444 445 /** 446 * \brief This function prepares to authenticate a new message with 447 * the same key as the previous HMAC operation. 448 * 449 * You may call this function after mbedtls_md_hmac_finish(). 450 * Afterwards call mbedtls_md_hmac_update() to pass the new 451 * input. 452 * 453 * \param ctx The message digest context containing an embedded HMAC 454 * context. 455 * 456 * \return \c 0 on success. 457 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 458 * failure. 459 */ 460 int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx ); 461 462 /** 463 * \brief This function calculates the full generic HMAC 464 * on the input buffer with the provided key. 465 * 466 * The function allocates the context, performs the 467 * calculation, and frees the context. 468 * 469 * The HMAC result is calculated as 470 * output = generic HMAC(hmac key, input buffer). 471 * 472 * \param md_info The information structure of the message-digest algorithm 473 * to use. 474 * \param key The HMAC secret key. 475 * \param keylen The length of the HMAC secret key in Bytes. 476 * \param input The buffer holding the input data. 477 * \param ilen The length of the input data. 478 * \param output The generic HMAC result. 479 * 480 * \return \c 0 on success. 481 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification 482 * failure. 483 */ 484 int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, 485 const unsigned char *input, size_t ilen, 486 unsigned char *output ); 487 488 /* Internal use */ 489 int mbedtls_md_process( mbedtls_md_context_t *ctx, const unsigned char *data ); 490 491 #ifdef __cplusplus 492 } 493 #endif 494 495 #endif /* MBEDTLS_MD_H */ 496