1 /** 2 * \file md.h 3 * 4 * \brief Generic message digest wrapper 5 * 6 * \author Adriaan de Jong <dejong@fox-it.com> 7 * 8 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 9 * SPDX-License-Identifier: Apache-2.0 10 * 11 * Licensed under the Apache License, Version 2.0 (the "License"); you may 12 * not use this file except in compliance with the License. 13 * You may obtain a copy of the License at 14 * 15 * http://www.apache.org/licenses/LICENSE-2.0 16 * 17 * Unless required by applicable law or agreed to in writing, software 18 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 19 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 * See the License for the specific language governing permissions and 21 * limitations under the License. 22 * 23 * This file is part of mbed TLS (https://tls.mbed.org) 24 */ 25 #ifndef MBEDTLS_MD_H 26 #define MBEDTLS_MD_H 27 28 #include <stddef.h> 29 30 #define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080 /**< The selected feature is not available. */ 31 #define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100 /**< Bad input parameters to function. */ 32 #define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180 /**< Failed to allocate memory. */ 33 #define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200 /**< Opening or reading of file failed. */ 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 typedef enum { 40 MBEDTLS_MD_NONE=0, 41 MBEDTLS_MD_MD2, 42 MBEDTLS_MD_MD4, 43 MBEDTLS_MD_MD5, 44 MBEDTLS_MD_SHA1, 45 MBEDTLS_MD_SHA224, 46 MBEDTLS_MD_SHA256, 47 MBEDTLS_MD_SHA384, 48 MBEDTLS_MD_SHA512, 49 MBEDTLS_MD_RIPEMD160, 50 } mbedtls_md_type_t; 51 52 #if defined(MBEDTLS_SHA512_C) 53 #define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */ 54 #else 55 #define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 or less */ 56 #endif 57 58 /** 59 * Opaque struct defined in md_internal.h 60 */ 61 typedef struct mbedtls_md_info_t mbedtls_md_info_t; 62 63 /** 64 * Generic message digest context. 65 */ 66 typedef struct { 67 /** Information about the associated message digest */ 68 const mbedtls_md_info_t *md_info; 69 70 /** Digest-specific context */ 71 void *md_ctx; 72 73 /** HMAC part of the context */ 74 void *hmac_ctx; 75 } mbedtls_md_context_t; 76 77 /** 78 * \brief Returns the list of digests supported by the generic digest module. 79 * 80 * \return a statically allocated array of digests, the last entry 81 * is 0. 82 */ 83 const int *mbedtls_md_list( void ); 84 85 /** 86 * \brief Returns the message digest information associated with the 87 * given digest name. 88 * 89 * \param md_name Name of the digest to search for. 90 * 91 * \return The message digest information associated with md_name or 92 * NULL if not found. 93 */ 94 const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name ); 95 96 /** 97 * \brief Returns the message digest information associated with the 98 * given digest type. 99 * 100 * \param md_type type of digest to search for. 101 * 102 * \return The message digest information associated with md_type or 103 * NULL if not found. 104 */ 105 const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type ); 106 107 /** 108 * \brief Initialize a md_context (as NONE) 109 * This should always be called first. 110 * Prepares the context for mbedtls_md_setup() or mbedtls_md_free(). 111 */ 112 void mbedtls_md_init( mbedtls_md_context_t *ctx ); 113 114 /** 115 * \brief Free and clear the internal structures of ctx. 116 * Can be called at any time after mbedtls_md_init(). 117 * Mandatory once mbedtls_md_setup() has been called. 118 */ 119 void mbedtls_md_free( mbedtls_md_context_t *ctx ); 120 121 #if ! defined(MBEDTLS_DEPRECATED_REMOVED) 122 #if defined(MBEDTLS_DEPRECATED_WARNING) 123 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 124 #else 125 #define MBEDTLS_DEPRECATED 126 #endif 127 /** 128 * \brief Select MD to use and allocate internal structures. 129 * Should be called after mbedtls_md_init() or mbedtls_md_free(). 130 * Makes it necessary to call mbedtls_md_free() later. 131 * 132 * \deprecated Superseded by mbedtls_md_setup() in 2.0.0 133 * 134 * \param ctx Context to set up. 135 * \param md_info Message digest to use. 136 * 137 * \returns \c 0 on success, 138 * \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, 139 * \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. 140 */ 141 int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED; 142 #undef MBEDTLS_DEPRECATED 143 #endif /* MBEDTLS_DEPRECATED_REMOVED */ 144 145 /** 146 * \brief Select MD to use and allocate internal structures. 147 * Should be called after mbedtls_md_init() or mbedtls_md_free(). 148 * Makes it necessary to call mbedtls_md_free() later. 149 * 150 * \param ctx Context to set up. 151 * \param md_info Message digest to use. 152 * \param hmac 0 to save some memory if HMAC will not be used, 153 * non-zero is HMAC is going to be used with this context. 154 * 155 * \returns \c 0 on success, 156 * \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, 157 * \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. 158 */ 159 int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac ); 160 161 /** 162 * \brief Clone the state of an MD context 163 * 164 * \note The two contexts must have been setup to the same type 165 * (cloning from SHA-256 to SHA-512 make no sense). 166 * 167 * \warning Only clones the MD state, not the HMAC state! (for now) 168 * 169 * \param dst The destination context 170 * \param src The context to be cloned 171 * 172 * \return \c 0 on success, 173 * \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure. 174 */ 175 int mbedtls_md_clone( mbedtls_md_context_t *dst, 176 const mbedtls_md_context_t *src ); 177 178 /** 179 * \brief Returns the size of the message digest output. 180 * 181 * \param md_info message digest info 182 * 183 * \return size of the message digest output in bytes. 184 */ 185 unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info ); 186 187 /** 188 * \brief Returns the type of the message digest output. 189 * 190 * \param md_info message digest info 191 * 192 * \return type of the message digest output. 193 */ 194 mbedtls_md_type_t mbedtls_md_get_type( const mbedtls_md_info_t *md_info ); 195 196 /** 197 * \brief Returns the name of the message digest output. 198 * 199 * \param md_info message digest info 200 * 201 * \return name of the message digest output. 202 */ 203 const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info ); 204 205 /** 206 * \brief Prepare the context to digest a new message. 207 * Generally called after mbedtls_md_setup() or mbedtls_md_finish(). 208 * Followed by mbedtls_md_update(). 209 * 210 * \param ctx generic message digest context. 211 * 212 * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter 213 * verification fails. 214 */ 215 int mbedtls_md_starts( mbedtls_md_context_t *ctx ); 216 217 /** 218 * \brief Generic message digest process buffer 219 * Called between mbedtls_md_starts() and mbedtls_md_finish(). 220 * May be called repeatedly. 221 * 222 * \param ctx Generic message digest context 223 * \param input buffer holding the datal 224 * \param ilen length of the input data 225 * 226 * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter 227 * verification fails. 228 */ 229 int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen ); 230 231 /** 232 * \brief Generic message digest final digest 233 * Called after mbedtls_md_update(). 234 * Usually followed by mbedtls_md_free() or mbedtls_md_starts(). 235 * 236 * \param ctx Generic message digest context 237 * \param output Generic message digest checksum result 238 * 239 * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter 240 * verification fails. 241 */ 242 int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output ); 243 244 /** 245 * \brief Output = message_digest( input buffer ) 246 * 247 * \param md_info message digest info 248 * \param input buffer holding the data 249 * \param ilen length of the input data 250 * \param output Generic message digest checksum result 251 * 252 * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter 253 * verification fails. 254 */ 255 int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, 256 unsigned char *output ); 257 258 #if defined(MBEDTLS_FS_IO) 259 /** 260 * \brief Output = message_digest( file contents ) 261 * 262 * \param md_info message digest info 263 * \param path input file name 264 * \param output generic message digest checksum result 265 * 266 * \return 0 if successful, 267 * MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, 268 * MBEDTLS_ERR_MD_BAD_INPUT_DATA if md_info was NULL. 269 */ 270 int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path, 271 unsigned char *output ); 272 #endif /* MBEDTLS_FS_IO */ 273 274 /** 275 * \brief Set HMAC key and prepare to authenticate a new message. 276 * Usually called after mbedtls_md_setup() or mbedtls_md_hmac_finish(). 277 * 278 * \param ctx HMAC context 279 * \param key HMAC secret key 280 * \param keylen length of the HMAC key in bytes 281 * 282 * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter 283 * verification fails. 284 */ 285 int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key, 286 size_t keylen ); 287 288 /** 289 * \brief Generic HMAC process buffer. 290 * Called between mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() 291 * and mbedtls_md_hmac_finish(). 292 * May be called repeatedly. 293 * 294 * \param ctx HMAC context 295 * \param input buffer holding the data 296 * \param ilen length of the input data 297 * 298 * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter 299 * verification fails. 300 */ 301 int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input, 302 size_t ilen ); 303 304 /** 305 * \brief Output HMAC. 306 * Called after mbedtls_md_hmac_update(). 307 * Usually followed by mbedtls_md_hmac_reset(), 308 * mbedtls_md_hmac_starts(), or mbedtls_md_free(). 309 * 310 * \param ctx HMAC context 311 * \param output Generic HMAC checksum result 312 * 313 * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter 314 * verification fails. 315 */ 316 int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output); 317 318 /** 319 * \brief Prepare to authenticate a new message with the same key. 320 * Called after mbedtls_md_hmac_finish() and before 321 * mbedtls_md_hmac_update(). 322 * 323 * \param ctx HMAC context to be reset 324 * 325 * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter 326 * verification fails. 327 */ 328 int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx ); 329 330 /** 331 * \brief Output = Generic_HMAC( hmac key, input buffer ) 332 * 333 * \param md_info message digest info 334 * \param key HMAC secret key 335 * \param keylen length of the HMAC key in bytes 336 * \param input buffer holding the data 337 * \param ilen length of the input data 338 * \param output Generic HMAC-result 339 * 340 * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter 341 * verification fails. 342 */ 343 int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, 344 const unsigned char *input, size_t ilen, 345 unsigned char *output ); 346 347 /* Internal use */ 348 int mbedtls_md_process( mbedtls_md_context_t *ctx, const unsigned char *data ); 349 350 #ifdef __cplusplus 351 } 352 #endif 353 354 #endif /* MBEDTLS_MD_H */ 355
