Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 1 | /** |
Simon Butcher | 5b331b9 | 2016-01-03 16:14:14 +0000 | [diff] [blame] | 2 | * \file md.h |
Paul Bakker | 9af723c | 2014-05-01 13:03:14 +0200 | [diff] [blame] | 3 | * |
Rose Zadik | 8c9c794 | 2018-03-27 11:52:58 +0100 | [diff] [blame] | 4 | * \brief This file contains the generic message-digest wrapper. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 5 | * |
| 6 | * \author Adriaan de Jong <dejong@fox-it.com> |
Darryl Green | a40a101 | 2018-01-05 15:33:17 +0000 | [diff] [blame] | 7 | */ |
| 8 | /* |
Bence Szépkúti | 1e14827 | 2020-08-07 13:07:28 +0200 | [diff] [blame] | 9 | * Copyright The Mbed TLS Contributors |
Manuel Pégourié-Gonnard | 37ff140 | 2015-09-04 14:21:07 +0200 | [diff] [blame] | 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. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 23 | */ |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 24 | |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 25 | #ifndef MBEDTLS_MD_H |
| 26 | #define MBEDTLS_MD_H |
Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 27 | #include "mbedtls/private_access.h" |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 28 | |
Rich Evans | 00ab470 | 2015-02-06 13:43:58 +0000 | [diff] [blame] | 29 | #include <stddef.h> |
Paul Bakker | 23986e5 | 2011-04-24 08:57:21 +0000 | [diff] [blame] | 30 | |
Bence Szépkúti | c662b36 | 2021-05-27 11:25:03 +0200 | [diff] [blame] | 31 | #include "mbedtls/build_info.h" |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 32 | #include "mbedtls/platform_util.h" |
Ron Eldor | f231eaa | 2017-08-22 14:50:14 +0300 | [diff] [blame] | 33 | |
Gilles Peskine | d297157 | 2021-07-26 18:48:10 +0200 | [diff] [blame] | 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 |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 42 | |
Paul Bakker | 407a0da | 2013-06-27 14:29:21 +0200 | [diff] [blame] | 43 | #ifdef __cplusplus |
| 44 | extern "C" { |
| 45 | #endif |
| 46 | |
Hanno Becker | bbca8c5 | 2017-09-25 14:53:51 +0100 | [diff] [blame] | 47 | /** |
Rose Zadik | 8c9c794 | 2018-03-27 11:52:58 +0100 | [diff] [blame] | 48 | * \brief Supported message digests. |
Hanno Becker | bbca8c5 | 2017-09-25 14:53:51 +0100 | [diff] [blame] | 49 | * |
TRodziewicz | 10e8cf5 | 2021-05-31 17:58:57 +0200 | [diff] [blame] | 50 | * \warning MD5 and SHA-1 are considered weak message digests and |
Hanno Becker | bbca8c5 | 2017-09-25 14:53:51 +0100 | [diff] [blame] | 51 | * their use constitutes a security risk. We recommend considering |
| 52 | * stronger message digests instead. |
| 53 | * |
| 54 | */ |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 55 | typedef enum { |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 56 | MBEDTLS_MD_NONE=0, /**< None. */ |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 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. */ |
Rose Zadik | 8c9c794 | 2018-03-27 11:52:58 +0100 | [diff] [blame] | 63 | MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 64 | } mbedtls_md_type_t; |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 65 | |
Valerio Setti | d55cb5b | 2022-12-22 14:26:55 +0100 | [diff] [blame] | 66 | #if defined(MBEDTLS_SHA512_C) |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 67 | #define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */ |
Valerio Setti | d55cb5b | 2022-12-22 14:26:55 +0100 | [diff] [blame] | 68 | #elif defined(MBEDTLS_SHA384_C) |
| 69 | #define MBEDTLS_MD_MAX_SIZE 48 /* longest known is SHA384 */ |
| 70 | #elif defined(MBEDTLS_SHA256_C) |
| 71 | #define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 */ |
| 72 | #elif defined(MBEDTLS_SHA224_C) |
| 73 | #define MBEDTLS_MD_MAX_SIZE 28 /* longest known is SHA224 */ |
Paul Bakker | 7db0109 | 2013-09-10 11:10:57 +0200 | [diff] [blame] | 74 | #else |
Valerio Setti | d55cb5b | 2022-12-22 14:26:55 +0100 | [diff] [blame] | 75 | #define MBEDTLS_MD_MAX_SIZE 20 /* longest known is SHA1 or RIPE MD-160 */ |
Paul Bakker | 7db0109 | 2013-09-10 11:10:57 +0200 | [diff] [blame] | 76 | #endif |
Paul Bakker | 1b57b06 | 2011-01-06 15:48:19 +0000 | [diff] [blame] | 77 | |
Hanno Becker | 2e24c3b | 2017-12-27 21:28:58 +0000 | [diff] [blame] | 78 | #if defined(MBEDTLS_SHA512_C) |
| 79 | #define MBEDTLS_MD_MAX_BLOCK_SIZE 128 |
| 80 | #else |
| 81 | #define MBEDTLS_MD_MAX_BLOCK_SIZE 64 |
| 82 | #endif |
| 83 | |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 84 | /** |
Chris Jones | 3848e31 | 2021-03-11 16:17:59 +0000 | [diff] [blame] | 85 | * Opaque struct. |
| 86 | * |
| 87 | * Constructed using either #mbedtls_md_info_from_string or |
| 88 | * #mbedtls_md_info_from_type. |
| 89 | * |
| 90 | * Fields can be accessed with #mbedtls_md_get_size, |
| 91 | * #mbedtls_md_get_type and #mbedtls_md_get_name. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 92 | */ |
Chris Jones | 3848e31 | 2021-03-11 16:17:59 +0000 | [diff] [blame] | 93 | /* Defined internally in library/md_wrap.h. */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 94 | typedef struct mbedtls_md_info_t mbedtls_md_info_t; |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 95 | |
| 96 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 97 | * The generic message-digest context. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 98 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 99 | typedef struct mbedtls_md_context_t { |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 100 | /** Information about the associated message digest. */ |
Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 101 | const mbedtls_md_info_t *MBEDTLS_PRIVATE(md_info); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 102 | |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 103 | /** The digest-specific context. */ |
Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 104 | void *MBEDTLS_PRIVATE(md_ctx); |
Manuel Pégourié-Gonnard | 8379a82 | 2015-03-24 16:48:22 +0100 | [diff] [blame] | 105 | |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 106 | /** The HMAC part of the context. */ |
Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 107 | void *MBEDTLS_PRIVATE(hmac_ctx); |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 108 | } mbedtls_md_context_t; |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 109 | |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 110 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 111 | * \brief This function returns the list of digests supported by the |
| 112 | * generic digest module. |
Paul Bakker | 72f6266 | 2011-01-16 21:27:44 +0000 | [diff] [blame] | 113 | * |
Manuel Pégourié-Gonnard | c52a43c | 2020-05-22 12:12:36 +0200 | [diff] [blame] | 114 | * \note The list starts with the strongest available hashes. |
| 115 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 116 | * \return A statically allocated array of digests. Each element |
| 117 | * in the returned list is an integer belonging to the |
| 118 | * message-digest enumeration #mbedtls_md_type_t. |
| 119 | * The last entry is 0. |
Paul Bakker | 72f6266 | 2011-01-16 21:27:44 +0000 | [diff] [blame] | 120 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 121 | const int *mbedtls_md_list(void); |
Paul Bakker | 72f6266 | 2011-01-16 21:27:44 +0000 | [diff] [blame] | 122 | |
| 123 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 124 | * \brief This function returns the message-digest information |
| 125 | * associated with the given digest name. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 126 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 127 | * \param md_name The name of the digest to search for. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 128 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 129 | * \return The message-digest information associated with \p md_name. |
| 130 | * \return NULL if the associated message-digest information is not found. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 131 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 132 | const mbedtls_md_info_t *mbedtls_md_info_from_string(const char *md_name); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 133 | |
| 134 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 135 | * \brief This function returns the message-digest information |
| 136 | * associated with the given digest type. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 137 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 138 | * \param md_type The type of digest to search for. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 139 | * |
Rose Zadik | 8c9c794 | 2018-03-27 11:52:58 +0100 | [diff] [blame] | 140 | * \return The message-digest information associated with \p md_type. |
| 141 | * \return NULL if the associated message-digest information is not found. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 142 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 143 | const mbedtls_md_info_t *mbedtls_md_info_from_type(mbedtls_md_type_t md_type); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 144 | |
| 145 | /** |
Max Fillinger | 0bb3833 | 2021-12-28 16:32:00 +0100 | [diff] [blame] | 146 | * \brief This function returns the message-digest information |
| 147 | * from the given context. |
| 148 | * |
| 149 | * \param ctx The context from which to extract the information. |
| 150 | * This must be initialized (or \c NULL). |
| 151 | * |
| 152 | * \return The message-digest information associated with \p ctx. |
| 153 | * \return \c NULL if \p ctx is \c NULL. |
| 154 | */ |
| 155 | const mbedtls_md_info_t *mbedtls_md_info_from_ctx( |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 156 | const mbedtls_md_context_t *ctx); |
Max Fillinger | 0bb3833 | 2021-12-28 16:32:00 +0100 | [diff] [blame] | 157 | |
Max Fillinger | 0bb3833 | 2021-12-28 16:32:00 +0100 | [diff] [blame] | 158 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 159 | * \brief This function initializes a message-digest context without |
| 160 | * binding it to a particular message-digest algorithm. |
| 161 | * |
| 162 | * This function should always be called first. It prepares the |
| 163 | * context for mbedtls_md_setup() for binding it to a |
| 164 | * message-digest algorithm. |
Paul Bakker | 84bbeb5 | 2014-07-01 14:53:22 +0200 | [diff] [blame] | 165 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 166 | void mbedtls_md_init(mbedtls_md_context_t *ctx); |
Paul Bakker | 84bbeb5 | 2014-07-01 14:53:22 +0200 | [diff] [blame] | 167 | |
| 168 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 169 | * \brief This function clears the internal structure of \p ctx and |
| 170 | * frees any embedded internal structure, but does not free |
| 171 | * \p ctx itself. |
| 172 | * |
| 173 | * If you have called mbedtls_md_setup() on \p ctx, you must |
| 174 | * call mbedtls_md_free() when you are no longer using the |
| 175 | * context. |
| 176 | * Calling this function if you have previously |
| 177 | * called mbedtls_md_init() and nothing else is optional. |
| 178 | * You must not call this function if you have not called |
| 179 | * mbedtls_md_init(). |
Paul Bakker | 84bbeb5 | 2014-07-01 14:53:22 +0200 | [diff] [blame] | 180 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 181 | void mbedtls_md_free(mbedtls_md_context_t *ctx); |
Paul Bakker | 84bbeb5 | 2014-07-01 14:53:22 +0200 | [diff] [blame] | 182 | |
Manuel Pégourié-Gonnard | 147fa09 | 2015-03-25 16:43:14 +0100 | [diff] [blame] | 183 | |
Paul Bakker | 84bbeb5 | 2014-07-01 14:53:22 +0200 | [diff] [blame] | 184 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 185 | * \brief This function selects the message digest algorithm to use, |
| 186 | * and allocates internal structures. |
Paul Bakker | 562535d | 2011-01-20 16:42:01 +0000 | [diff] [blame] | 187 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 188 | * It should be called after mbedtls_md_init() or |
| 189 | * mbedtls_md_free(). Makes it necessary to call |
| 190 | * mbedtls_md_free() later. |
| 191 | * |
| 192 | * \param ctx The context to set up. |
| 193 | * \param md_info The information structure of the message-digest algorithm |
| 194 | * to use. |
Rose Zadik | 8c9c794 | 2018-03-27 11:52:58 +0100 | [diff] [blame] | 195 | * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory), |
| 196 | * or non-zero: HMAC is used with this context. |
Paul Bakker | 562535d | 2011-01-20 16:42:01 +0000 | [diff] [blame] | 197 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 198 | * \return \c 0 on success. |
| 199 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification |
| 200 | * failure. |
| 201 | * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure. |
Paul Bakker | 562535d | 2011-01-20 16:42:01 +0000 | [diff] [blame] | 202 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 203 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 204 | int mbedtls_md_setup(mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac); |
Paul Bakker | 562535d | 2011-01-20 16:42:01 +0000 | [diff] [blame] | 205 | |
| 206 | /** |
Tom Cosgrove | ce7f18c | 2022-07-28 05:50:56 +0100 | [diff] [blame] | 207 | * \brief This function clones the state of a message-digest |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 208 | * context. |
Manuel Pégourié-Gonnard | 052a6c9 | 2015-07-06 16:06:02 +0200 | [diff] [blame] | 209 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 210 | * \note You must call mbedtls_md_setup() on \c dst before calling |
| 211 | * this function. |
Manuel Pégourié-Gonnard | 052a6c9 | 2015-07-06 16:06:02 +0200 | [diff] [blame] | 212 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 213 | * \note The two contexts must have the same type, |
| 214 | * for example, both are SHA-256. |
Manuel Pégourié-Gonnard | 052a6c9 | 2015-07-06 16:06:02 +0200 | [diff] [blame] | 215 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 216 | * \warning This function clones the message-digest state, not the |
| 217 | * HMAC state. |
| 218 | * |
| 219 | * \param dst The destination context. |
| 220 | * \param src The context to be cloned. |
Manuel Pégourié-Gonnard | 052a6c9 | 2015-07-06 16:06:02 +0200 | [diff] [blame] | 221 | * |
Rose Zadik | 8c9c794 | 2018-03-27 11:52:58 +0100 | [diff] [blame] | 222 | * \return \c 0 on success. |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 223 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure. |
Manuel Pégourié-Gonnard | 052a6c9 | 2015-07-06 16:06:02 +0200 | [diff] [blame] | 224 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 225 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 226 | int mbedtls_md_clone(mbedtls_md_context_t *dst, |
| 227 | const mbedtls_md_context_t *src); |
Manuel Pégourié-Gonnard | 052a6c9 | 2015-07-06 16:06:02 +0200 | [diff] [blame] | 228 | |
| 229 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 230 | * \brief This function extracts the message-digest size from the |
| 231 | * message-digest information structure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 232 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 233 | * \param md_info The information structure of the message-digest algorithm |
| 234 | * to use. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 235 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 236 | * \return The size of the message-digest output in Bytes. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 237 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 238 | unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 239 | |
| 240 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 241 | * \brief This function extracts the message-digest type from the |
| 242 | * message-digest information structure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 243 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 244 | * \param md_info The information structure of the message-digest algorithm |
| 245 | * to use. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 246 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 247 | * \return The type of the message digest. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 248 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 249 | mbedtls_md_type_t mbedtls_md_get_type(const mbedtls_md_info_t *md_info); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 250 | |
| 251 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 252 | * \brief This function extracts the message-digest name from the |
| 253 | * message-digest information structure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 254 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 255 | * \param md_info The information structure of the message-digest algorithm |
| 256 | * to use. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 257 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 258 | * \return The name of the message digest. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 259 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 260 | const char *mbedtls_md_get_name(const mbedtls_md_info_t *md_info); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 261 | |
| 262 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 263 | * \brief This function starts a message-digest computation. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 264 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 265 | * You must call this function after setting up the context |
| 266 | * with mbedtls_md_setup(), and before passing data with |
| 267 | * mbedtls_md_update(). |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 268 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 269 | * \param ctx The generic message-digest context. |
| 270 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 271 | * \return \c 0 on success. |
| 272 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification |
| 273 | * failure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 274 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 275 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 276 | int mbedtls_md_starts(mbedtls_md_context_t *ctx); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 277 | |
| 278 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 279 | * \brief This function feeds an input buffer into an ongoing |
| 280 | * message-digest computation. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 281 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 282 | * You must call mbedtls_md_starts() before calling this |
| 283 | * function. You may call this function multiple times. |
| 284 | * Afterwards, call mbedtls_md_finish(). |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 285 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 286 | * \param ctx The generic message-digest context. |
| 287 | * \param input The buffer holding the input data. |
| 288 | * \param ilen The length of the input data. |
| 289 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 290 | * \return \c 0 on success. |
| 291 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification |
| 292 | * failure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 293 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 294 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 295 | int mbedtls_md_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 296 | |
| 297 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 298 | * \brief This function finishes the digest operation, |
| 299 | * and writes the result to the output buffer. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 300 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 301 | * Call this function after a call to mbedtls_md_starts(), |
| 302 | * followed by any number of calls to mbedtls_md_update(). |
| 303 | * Afterwards, you may either clear the context with |
| 304 | * mbedtls_md_free(), or call mbedtls_md_starts() to reuse |
| 305 | * the context for another digest operation with the same |
| 306 | * algorithm. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 307 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 308 | * \param ctx The generic message-digest context. |
| 309 | * \param output The buffer for the generic message-digest checksum result. |
| 310 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 311 | * \return \c 0 on success. |
| 312 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification |
| 313 | * failure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 314 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 315 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 316 | int mbedtls_md_finish(mbedtls_md_context_t *ctx, unsigned char *output); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 317 | |
| 318 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 319 | * \brief This function calculates the message-digest of a buffer, |
| 320 | * with respect to a configurable message-digest algorithm |
| 321 | * in a single call. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 322 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 323 | * The result is calculated as |
| 324 | * Output = message_digest(input buffer). |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 325 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 326 | * \param md_info The information structure of the message-digest algorithm |
| 327 | * to use. |
| 328 | * \param input The buffer holding the data. |
| 329 | * \param ilen The length of the input data. |
| 330 | * \param output The generic message-digest checksum result. |
| 331 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 332 | * \return \c 0 on success. |
| 333 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification |
| 334 | * failure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 335 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 336 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 337 | int mbedtls_md(const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, |
| 338 | unsigned char *output); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 339 | |
Manuel Pégourié-Gonnard | bfffa90 | 2015-05-28 14:44:00 +0200 | [diff] [blame] | 340 | #if defined(MBEDTLS_FS_IO) |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 341 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 342 | * \brief This function calculates the message-digest checksum |
| 343 | * result of the contents of the provided file. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 344 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 345 | * The result is calculated as |
| 346 | * Output = message_digest(file contents). |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 347 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 348 | * \param md_info The information structure of the message-digest algorithm |
| 349 | * to use. |
| 350 | * \param path The input file name. |
| 351 | * \param output The generic message-digest checksum result. |
| 352 | * |
Rose Zadik | 8c9c794 | 2018-03-27 11:52:58 +0100 | [diff] [blame] | 353 | * \return \c 0 on success. |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 354 | * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing |
| 355 | * the file pointed by \p path. |
| 356 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 357 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 358 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 359 | int mbedtls_md_file(const mbedtls_md_info_t *md_info, const char *path, |
| 360 | unsigned char *output); |
Manuel Pégourié-Gonnard | bfffa90 | 2015-05-28 14:44:00 +0200 | [diff] [blame] | 361 | #endif /* MBEDTLS_FS_IO */ |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 362 | |
| 363 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 364 | * \brief This function sets the HMAC key and prepares to |
| 365 | * authenticate a new message. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 366 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 367 | * Call this function after mbedtls_md_setup(), to use |
| 368 | * the MD context for an HMAC calculation, then call |
| 369 | * mbedtls_md_hmac_update() to provide the input data, and |
| 370 | * mbedtls_md_hmac_finish() to get the HMAC value. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 371 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 372 | * \param ctx The message digest context containing an embedded HMAC |
| 373 | * context. |
| 374 | * \param key The HMAC secret key. |
| 375 | * \param keylen The length of the HMAC key in Bytes. |
| 376 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 377 | * \return \c 0 on success. |
| 378 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification |
| 379 | * failure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 380 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 381 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 382 | int mbedtls_md_hmac_starts(mbedtls_md_context_t *ctx, const unsigned char *key, |
| 383 | size_t keylen); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 384 | |
| 385 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 386 | * \brief This function feeds an input buffer into an ongoing HMAC |
| 387 | * computation. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 388 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 389 | * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() |
| 390 | * before calling this function. |
| 391 | * You may call this function multiple times to pass the |
| 392 | * input piecewise. |
| 393 | * Afterwards, call mbedtls_md_hmac_finish(). |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 394 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 395 | * \param ctx The message digest context containing an embedded HMAC |
| 396 | * context. |
| 397 | * \param input The buffer holding the input data. |
| 398 | * \param ilen The length of the input data. |
| 399 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 400 | * \return \c 0 on success. |
| 401 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification |
| 402 | * failure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 403 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 404 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 405 | int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input, |
| 406 | size_t ilen); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 407 | |
| 408 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 409 | * \brief This function finishes the HMAC operation, and writes |
| 410 | * the result to the output buffer. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 411 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 412 | * Call this function after mbedtls_md_hmac_starts() and |
| 413 | * mbedtls_md_hmac_update() to get the HMAC value. Afterwards |
| 414 | * you may either call mbedtls_md_free() to clear the context, |
| 415 | * or call mbedtls_md_hmac_reset() to reuse the context with |
| 416 | * the same HMAC key. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 417 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 418 | * \param ctx The message digest context containing an embedded HMAC |
| 419 | * context. |
| 420 | * \param output The generic HMAC checksum result. |
| 421 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 422 | * \return \c 0 on success. |
| 423 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification |
| 424 | * failure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 425 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 426 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 427 | int mbedtls_md_hmac_finish(mbedtls_md_context_t *ctx, unsigned char *output); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 428 | |
| 429 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 430 | * \brief This function prepares to authenticate a new message with |
| 431 | * the same key as the previous HMAC operation. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 432 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 433 | * You may call this function after mbedtls_md_hmac_finish(). |
| 434 | * Afterwards call mbedtls_md_hmac_update() to pass the new |
| 435 | * input. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 436 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 437 | * \param ctx The message digest context containing an embedded HMAC |
| 438 | * context. |
| 439 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 440 | * \return \c 0 on success. |
| 441 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification |
| 442 | * failure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 443 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 444 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 445 | int mbedtls_md_hmac_reset(mbedtls_md_context_t *ctx); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 446 | |
| 447 | /** |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 448 | * \brief This function calculates the full generic HMAC |
| 449 | * on the input buffer with the provided key. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 450 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 451 | * The function allocates the context, performs the |
| 452 | * calculation, and frees the context. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 453 | * |
Rose Zadik | 64feefb | 2018-01-25 22:01:10 +0000 | [diff] [blame] | 454 | * The HMAC result is calculated as |
| 455 | * output = generic HMAC(hmac key, input buffer). |
| 456 | * |
| 457 | * \param md_info The information structure of the message-digest algorithm |
| 458 | * to use. |
| 459 | * \param key The HMAC secret key. |
| 460 | * \param keylen The length of the HMAC secret key in Bytes. |
| 461 | * \param input The buffer holding the input data. |
| 462 | * \param ilen The length of the input data. |
| 463 | * \param output The generic HMAC result. |
| 464 | * |
Rose Zadik | f3e4736 | 2018-04-16 16:31:16 +0100 | [diff] [blame] | 465 | * \return \c 0 on success. |
| 466 | * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification |
| 467 | * failure. |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 468 | */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 469 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 470 | int mbedtls_md_hmac(const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, |
| 471 | const unsigned char *input, size_t ilen, |
| 472 | unsigned char *output); |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 473 | |
Paul Bakker | 1bd3ae8 | 2013-03-13 10:26:44 +0100 | [diff] [blame] | 474 | /* Internal use */ |
Gilles Peskine | ecf6beb | 2021-12-10 21:35:10 +0100 | [diff] [blame] | 475 | MBEDTLS_CHECK_RETURN_TYPICAL |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame^] | 476 | int mbedtls_md_process(mbedtls_md_context_t *ctx, const unsigned char *data); |
Paul Bakker | 1bd3ae8 | 2013-03-13 10:26:44 +0100 | [diff] [blame] | 477 | |
Paul Bakker | 1737385 | 2011-01-06 14:20:01 +0000 | [diff] [blame] | 478 | #ifdef __cplusplus |
| 479 | } |
| 480 | #endif |
| 481 | |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 482 | #endif /* MBEDTLS_MD_H */ |