blob: 3b847b4a0a95d2dc29c06dac369e01b902043695 [file] [log] [blame]
Rose Zadik64feefb2018-01-25 22:01:10 +00001 /**
Simon Butcher5b331b92016-01-03 16:14:14 +00002 * \file md.h
Paul Bakker9af723c2014-05-01 13:03:14 +02003 *
Rose Zadik8c9c7942018-03-27 11:52:58 +01004 * \brief This file contains the generic message-digest wrapper.
Paul Bakker17373852011-01-06 14:20:01 +00005 *
6 * \author Adriaan de Jong <dejong@fox-it.com>
Darryl Greena40a1012018-01-05 15:33:17 +00007 */
8/*
Rose Zadik64feefb2018-01-25 22:01:10 +00009 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +020010 * 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 Bakker17373852011-01-06 14:20:01 +000023 *
Rose Zadik64feefb2018-01-25 22:01:10 +000024 * This file is part of Mbed TLS (https://tls.mbed.org)
Paul Bakker17373852011-01-06 14:20:01 +000025 */
Rose Zadik64feefb2018-01-25 22:01:10 +000026
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020027#ifndef MBEDTLS_MD_H
28#define MBEDTLS_MD_H
Paul Bakker17373852011-01-06 14:20:01 +000029
Rich Evans00ab4702015-02-06 13:43:58 +000030#include <stddef.h>
Paul Bakker23986e52011-04-24 08:57:21 +000031
Ron Eldorf231eaa2017-08-22 14:50:14 +030032#if !defined(MBEDTLS_CONFIG_FILE)
33#include "config.h"
34#else
35#include MBEDTLS_CONFIG_FILE
36#endif
37
Hanno Beckerc2908472019-09-04 16:56:11 +010038#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
39 !defined(inline) && !defined(__cplusplus)
40#define inline __inline
41#endif
42
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020043#define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080 /**< The selected feature is not available. */
44#define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100 /**< Bad input parameters to function. */
45#define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180 /**< Failed to allocate memory. */
46#define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200 /**< Opening or reading of file failed. */
Ron Eldor9924bdc2018-10-04 10:59:13 +030047
48/* MBEDTLS_ERR_MD_HW_ACCEL_FAILED is deprecated and should not be used. */
Gilles Peskine7ecab3d2018-01-26 17:56:38 +010049#define MBEDTLS_ERR_MD_HW_ACCEL_FAILED -0x5280 /**< MD hardware accelerator failed. */
Paul Bakker335db3f2011-04-25 15:28:35 +000050
Paul Bakker407a0da2013-06-27 14:29:21 +020051#ifdef __cplusplus
52extern "C" {
53#endif
54
Hanno Beckerbbca8c52017-09-25 14:53:51 +010055/**
Rose Zadik8c9c7942018-03-27 11:52:58 +010056 * \brief Supported message digests.
Hanno Beckerbbca8c52017-09-25 14:53:51 +010057 *
58 * \warning MD2, MD4, MD5 and SHA-1 are considered weak message digests and
59 * their use constitutes a security risk. We recommend considering
60 * stronger message digests instead.
61 *
62 */
Paul Bakker17373852011-01-06 14:20:01 +000063typedef enum {
Rose Zadikf3e47362018-04-16 16:31:16 +010064 MBEDTLS_MD_NONE=0, /**< None. */
65 MBEDTLS_MD_MD2, /**< The MD2 message digest. */
66 MBEDTLS_MD_MD4, /**< The MD4 message digest. */
67 MBEDTLS_MD_MD5, /**< The MD5 message digest. */
68 MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */
69 MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */
70 MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */
71 MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */
72 MBEDTLS_MD_SHA512, /**< The SHA-512 message digest. */
Rose Zadik8c9c7942018-03-27 11:52:58 +010073 MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020074} mbedtls_md_type_t;
Paul Bakker17373852011-01-06 14:20:01 +000075
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020076#if defined(MBEDTLS_SHA512_C)
77#define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */
Paul Bakker7db01092013-09-10 11:10:57 +020078#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020079#define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 or less */
Paul Bakker7db01092013-09-10 11:10:57 +020080#endif
Paul Bakker1b57b062011-01-06 15:48:19 +000081
Hanno Becker4c6876b2017-12-27 21:28:58 +000082#if defined(MBEDTLS_SHA512_C)
83#define MBEDTLS_MD_MAX_BLOCK_SIZE 128
84#else
85#define MBEDTLS_MD_MAX_BLOCK_SIZE 64
86#endif
87
Hanno Becker1292c352019-08-13 15:43:26 +010088#if !defined(MBEDTLS_MD_SINGLE_HASH)
89
Hanno Becker527f7c92019-09-04 12:46:07 +010090#define MBEDTLS_MD_INLINABLE_API
91
Paul Bakker17373852011-01-06 14:20:01 +000092/**
Hanno Beckerd03949e2019-07-26 14:38:44 +010093 * Opaque struct defined in md.c.
Paul Bakker17373852011-01-06 14:20:01 +000094 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020095typedef struct mbedtls_md_info_t mbedtls_md_info_t;
Paul Bakker17373852011-01-06 14:20:01 +000096
Hanno Beckera5cedbc2019-07-17 11:21:02 +010097
98typedef struct mbedtls_md_info_t const * mbedtls_md_handle_t;
99#define MBEDTLS_MD_INVALID_HANDLE ( (mbedtls_md_handle_t) NULL )
100
Hanno Becker1292c352019-08-13 15:43:26 +0100101#else /* !MBEDTLS_MD_SINGLE_HASH */
102
Hanno Becker527f7c92019-09-04 12:46:07 +0100103#define MBEDTLS_MD_INLINABLE_API MBEDTLS_ALWAYS_INLINE static inline
104
Hanno Becker1292c352019-08-13 15:43:26 +0100105typedef int mbedtls_md_handle_t;
106#define MBEDTLS_MD_INVALID_HANDLE ( (mbedtls_md_handle_t) 0 )
107#define MBEDTLS_MD_UNIQUE_VALID_HANDLE ( (mbedtls_md_handle_t) 1 )
108
109#endif /* !MBEDTLS_MD_SINGLE_HASH */
110
Hanno Becker52e36bc2019-09-05 13:02:52 +0100111#include "md_internal.h"
112
Paul Bakker17373852011-01-06 14:20:01 +0000113/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000114 * The generic message-digest context.
Paul Bakker17373852011-01-06 14:20:01 +0000115 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200116typedef struct mbedtls_md_context_t
117{
Hanno Beckerccb2b622019-09-03 13:19:14 +0100118#if !defined(MBEDTLS_MD_SINGLE_HASH)
Rose Zadik64feefb2018-01-25 22:01:10 +0000119 /** Information about the associated message digest. */
Hanno Beckera5cedbc2019-07-17 11:21:02 +0100120 mbedtls_md_handle_t md_info;
Hanno Beckerccb2b622019-09-03 13:19:14 +0100121#endif
Paul Bakker17373852011-01-06 14:20:01 +0000122
Hanno Becker52e36bc2019-09-05 13:02:52 +0100123#if !defined(MBEDTLS_MD_SINGLE_HASH)
Rose Zadik64feefb2018-01-25 22:01:10 +0000124 /** The digest-specific context. */
Paul Bakker17373852011-01-06 14:20:01 +0000125 void *md_ctx;
Manuel Pégourié-Gonnard8379a822015-03-24 16:48:22 +0100126
Rose Zadik64feefb2018-01-25 22:01:10 +0000127 /** The HMAC part of the context. */
Manuel Pégourié-Gonnarddfb3dc82015-03-25 11:49:07 +0100128 void *hmac_ctx;
Hanno Becker52e36bc2019-09-05 13:02:52 +0100129#else
130 unsigned char md_ctx[ sizeof( MBEDTLS_MD_INFO_CTX_TYPE(
131 MBEDTLS_MD_SINGLE_HASH ) ) ];
132
133 unsigned char hmac_ctx[ 2 * MBEDTLS_MD_INFO_BLOCKSIZE(
134 MBEDTLS_MD_SINGLE_HASH ) ];
135
136#endif /* MBEDTLS_MD_SINGLE_HASH */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200137} mbedtls_md_context_t;
Paul Bakker17373852011-01-06 14:20:01 +0000138
Hanno Beckerccb2b622019-09-03 13:19:14 +0100139#if !defined(MBEDTLS_MD_SINGLE_HASH)
Hanno Beckerd3827c72019-09-03 12:56:37 +0100140static inline mbedtls_md_handle_t mbedtls_md_get_handle(
141 struct mbedtls_md_context_t const *ctx )
142{
143 return( ctx->md_info );
144}
Hanno Beckerccb2b622019-09-03 13:19:14 +0100145#else /* !MBEDTLS_MD_SINGLE_HASH */
146static inline mbedtls_md_handle_t mbedtls_md_get_handle(
147 struct mbedtls_md_context_t const *ctx )
148{
149 ((void) ctx);
150 return( MBEDTLS_MD_UNIQUE_VALID_HANDLE );
151}
152#endif /* !MBEDTLS_MD_SINGLE_HASH */
Hanno Beckerd3827c72019-09-03 12:56:37 +0100153
Paul Bakker17373852011-01-06 14:20:01 +0000154/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000155 * \brief This function returns the list of digests supported by the
156 * generic digest module.
Paul Bakker72f62662011-01-16 21:27:44 +0000157 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000158 * \return A statically allocated array of digests. Each element
159 * in the returned list is an integer belonging to the
160 * message-digest enumeration #mbedtls_md_type_t.
161 * The last entry is 0.
Paul Bakker72f62662011-01-16 21:27:44 +0000162 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200163const int *mbedtls_md_list( void );
Paul Bakker72f62662011-01-16 21:27:44 +0000164
165/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000166 * \brief This function returns the message-digest information
167 * associated with the given digest name.
Paul Bakker17373852011-01-06 14:20:01 +0000168 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000169 * \param md_name The name of the digest to search for.
Paul Bakker17373852011-01-06 14:20:01 +0000170 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100171 * \return The message-digest information associated with \p md_name.
172 * \return NULL if the associated message-digest information is not found.
Paul Bakker17373852011-01-06 14:20:01 +0000173 */
Hanno Beckera5cedbc2019-07-17 11:21:02 +0100174mbedtls_md_handle_t mbedtls_md_info_from_string( const char *md_name );
Paul Bakker17373852011-01-06 14:20:01 +0000175
176/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000177 * \brief This function returns the message-digest information
178 * associated with the given digest type.
Paul Bakker17373852011-01-06 14:20:01 +0000179 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000180 * \param md_type The type of digest to search for.
Paul Bakker17373852011-01-06 14:20:01 +0000181 *
Rose Zadik8c9c7942018-03-27 11:52:58 +0100182 * \return The message-digest information associated with \p md_type.
183 * \return NULL if the associated message-digest information is not found.
Paul Bakker17373852011-01-06 14:20:01 +0000184 */
Hanno Beckera5cedbc2019-07-17 11:21:02 +0100185mbedtls_md_handle_t mbedtls_md_info_from_type( mbedtls_md_type_t md_type );
Paul Bakker17373852011-01-06 14:20:01 +0000186
187/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000188 * \brief This function initializes a message-digest context without
189 * binding it to a particular message-digest algorithm.
190 *
191 * This function should always be called first. It prepares the
192 * context for mbedtls_md_setup() for binding it to a
193 * message-digest algorithm.
Paul Bakker84bbeb52014-07-01 14:53:22 +0200194 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200195void mbedtls_md_init( mbedtls_md_context_t *ctx );
Paul Bakker84bbeb52014-07-01 14:53:22 +0200196
197/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000198 * \brief This function clears the internal structure of \p ctx and
199 * frees any embedded internal structure, but does not free
200 * \p ctx itself.
201 *
202 * If you have called mbedtls_md_setup() on \p ctx, you must
203 * call mbedtls_md_free() when you are no longer using the
204 * context.
205 * Calling this function if you have previously
206 * called mbedtls_md_init() and nothing else is optional.
207 * You must not call this function if you have not called
208 * mbedtls_md_init().
Paul Bakker84bbeb52014-07-01 14:53:22 +0200209 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200210void mbedtls_md_free( mbedtls_md_context_t *ctx );
Paul Bakker84bbeb52014-07-01 14:53:22 +0200211
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200212#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
213#if defined(MBEDTLS_DEPRECATED_WARNING)
214#define MBEDTLS_DEPRECATED __attribute__((deprecated))
Manuel Pégourié-Gonnard147fa092015-03-25 16:43:14 +0100215#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200216#define MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnard147fa092015-03-25 16:43:14 +0100217#endif
218/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000219 * \brief This function selects the message digest algorithm to use,
220 * and allocates internal structures.
221 *
222 * It should be called after mbedtls_md_init() or mbedtls_md_free().
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200223 * Makes it necessary to call mbedtls_md_free() later.
Manuel Pégourié-Gonnard147fa092015-03-25 16:43:14 +0100224 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200225 * \deprecated Superseded by mbedtls_md_setup() in 2.0.0
Manuel Pégourié-Gonnard147fa092015-03-25 16:43:14 +0100226 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000227 * \param ctx The context to set up.
228 * \param md_info The information structure of the message-digest algorithm
229 * to use.
Manuel Pégourié-Gonnard147fa092015-03-25 16:43:14 +0100230 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100231 * \return \c 0 on success.
232 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
233 * failure.
234 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
Manuel Pégourié-Gonnard147fa092015-03-25 16:43:14 +0100235 */
Hanno Beckera5cedbc2019-07-17 11:21:02 +0100236int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, mbedtls_md_handle_t md_info ) MBEDTLS_DEPRECATED;
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200237#undef MBEDTLS_DEPRECATED
238#endif /* MBEDTLS_DEPRECATED_REMOVED */
Manuel Pégourié-Gonnard147fa092015-03-25 16:43:14 +0100239
Paul Bakker84bbeb52014-07-01 14:53:22 +0200240/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000241 * \brief This function selects the message digest algorithm to use,
242 * and allocates internal structures.
Paul Bakker562535d2011-01-20 16:42:01 +0000243 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000244 * It should be called after mbedtls_md_init() or
245 * mbedtls_md_free(). Makes it necessary to call
246 * mbedtls_md_free() later.
247 *
248 * \param ctx The context to set up.
249 * \param md_info The information structure of the message-digest algorithm
250 * to use.
Rose Zadik8c9c7942018-03-27 11:52:58 +0100251 * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory),
252 * or non-zero: HMAC is used with this context.
Paul Bakker562535d2011-01-20 16:42:01 +0000253 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100254 * \return \c 0 on success.
255 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
256 * failure.
257 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
Paul Bakker562535d2011-01-20 16:42:01 +0000258 */
Hanno Becker64b06232019-09-05 13:02:32 +0100259MBEDTLS_MD_INLINABLE_API int mbedtls_md_setup( mbedtls_md_context_t *ctx,
260 mbedtls_md_handle_t md_info,
261 int hmac );
Paul Bakker562535d2011-01-20 16:42:01 +0000262
263/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000264 * \brief This function clones the state of an message-digest
265 * context.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200266 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000267 * \note You must call mbedtls_md_setup() on \c dst before calling
268 * this function.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200269 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000270 * \note The two contexts must have the same type,
271 * for example, both are SHA-256.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200272 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000273 * \warning This function clones the message-digest state, not the
274 * HMAC state.
275 *
276 * \param dst The destination context.
277 * \param src The context to be cloned.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200278 *
Rose Zadik8c9c7942018-03-27 11:52:58 +0100279 * \return \c 0 on success.
Rose Zadikf3e47362018-04-16 16:31:16 +0100280 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200281 */
282int mbedtls_md_clone( mbedtls_md_context_t *dst,
283 const mbedtls_md_context_t *src );
284
285/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000286 * \brief This function extracts the message-digest size from the
287 * message-digest information structure.
Paul Bakker17373852011-01-06 14:20:01 +0000288 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000289 * \param md_info The information structure of the message-digest algorithm
290 * to use.
Paul Bakker17373852011-01-06 14:20:01 +0000291 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000292 * \return The size of the message-digest output in Bytes.
Paul Bakker17373852011-01-06 14:20:01 +0000293 */
Hanno Beckera5cedbc2019-07-17 11:21:02 +0100294unsigned char mbedtls_md_get_size( mbedtls_md_handle_t md_info );
Paul Bakker17373852011-01-06 14:20:01 +0000295
296/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000297 * \brief This function extracts the message-digest type from the
298 * message-digest information structure.
Paul Bakker17373852011-01-06 14:20:01 +0000299 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000300 * \param md_info The information structure of the message-digest algorithm
301 * to use.
Paul Bakker17373852011-01-06 14:20:01 +0000302 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000303 * \return The type of the message digest.
Paul Bakker17373852011-01-06 14:20:01 +0000304 */
Hanno Beckera5cedbc2019-07-17 11:21:02 +0100305mbedtls_md_type_t mbedtls_md_get_type( mbedtls_md_handle_t md_info );
Paul Bakker17373852011-01-06 14:20:01 +0000306
307/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000308 * \brief This function extracts the message-digest name from the
309 * message-digest information structure.
Paul Bakker17373852011-01-06 14:20:01 +0000310 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000311 * \param md_info The information structure of the message-digest algorithm
312 * to use.
Paul Bakker17373852011-01-06 14:20:01 +0000313 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000314 * \return The name of the message digest.
Paul Bakker17373852011-01-06 14:20:01 +0000315 */
Hanno Beckera5cedbc2019-07-17 11:21:02 +0100316const char *mbedtls_md_get_name( mbedtls_md_handle_t md_info );
Paul Bakker17373852011-01-06 14:20:01 +0000317
318/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000319 * \brief This function starts a message-digest computation.
Paul Bakker17373852011-01-06 14:20:01 +0000320 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000321 * You must call this function after setting up the context
322 * with mbedtls_md_setup(), and before passing data with
323 * mbedtls_md_update().
Paul Bakker17373852011-01-06 14:20:01 +0000324 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000325 * \param ctx The generic message-digest context.
326 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100327 * \return \c 0 on success.
328 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
329 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000330 */
Hanno Becker527f7c92019-09-04 12:46:07 +0100331MBEDTLS_MD_INLINABLE_API int mbedtls_md_starts( mbedtls_md_context_t *ctx );
Paul Bakker17373852011-01-06 14:20:01 +0000332
333/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000334 * \brief This function feeds an input buffer into an ongoing
335 * message-digest computation.
Paul Bakker17373852011-01-06 14:20:01 +0000336 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000337 * You must call mbedtls_md_starts() before calling this
338 * function. You may call this function multiple times.
339 * Afterwards, call mbedtls_md_finish().
Paul Bakker17373852011-01-06 14:20:01 +0000340 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000341 * \param ctx The generic message-digest context.
342 * \param input The buffer holding the input data.
343 * \param ilen The length of the input data.
344 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100345 * \return \c 0 on success.
346 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
347 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000348 */
Hanno Beckerfdef5ac2019-09-04 13:20:05 +0100349MBEDTLS_MD_INLINABLE_API int mbedtls_md_update( mbedtls_md_context_t *ctx,
350 const unsigned char *input,
351 size_t ilen );
Paul Bakker17373852011-01-06 14:20:01 +0000352
353/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000354 * \brief This function finishes the digest operation,
355 * and writes the result to the output buffer.
Paul Bakker17373852011-01-06 14:20:01 +0000356 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000357 * Call this function after a call to mbedtls_md_starts(),
358 * followed by any number of calls to mbedtls_md_update().
359 * Afterwards, you may either clear the context with
360 * mbedtls_md_free(), or call mbedtls_md_starts() to reuse
361 * the context for another digest operation with the same
362 * algorithm.
Paul Bakker17373852011-01-06 14:20:01 +0000363 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000364 * \param ctx The generic message-digest context.
365 * \param output The buffer for the generic message-digest checksum result.
366 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100367 * \return \c 0 on success.
368 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
369 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000370 */
Hanno Becker993691d2019-09-04 13:24:44 +0100371MBEDTLS_MD_INLINABLE_API int mbedtls_md_finish( mbedtls_md_context_t *ctx,
372 unsigned char *output );
Paul Bakker17373852011-01-06 14:20:01 +0000373
374/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000375 * \brief This function calculates the message-digest of a buffer,
376 * with respect to a configurable message-digest algorithm
377 * in a single call.
Paul Bakker17373852011-01-06 14:20:01 +0000378 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000379 * The result is calculated as
380 * Output = message_digest(input buffer).
Paul Bakker17373852011-01-06 14:20:01 +0000381 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000382 * \param md_info The information structure of the message-digest algorithm
383 * to use.
384 * \param input The buffer holding the data.
385 * \param ilen The length of the input data.
386 * \param output The generic message-digest checksum result.
387 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100388 * \return \c 0 on success.
389 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
390 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000391 */
Hanno Becker993691d2019-09-04 13:24:44 +0100392MBEDTLS_MD_INLINABLE_API int mbedtls_md(
393 mbedtls_md_handle_t md_info,
394 const unsigned char *input,
395 size_t ilen,
396 unsigned char *output );
Paul Bakker17373852011-01-06 14:20:01 +0000397
Manuel Pégourié-Gonnardbfffa902015-05-28 14:44:00 +0200398#if defined(MBEDTLS_FS_IO)
Paul Bakker17373852011-01-06 14:20:01 +0000399/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000400 * \brief This function calculates the message-digest checksum
401 * result of the contents of the provided file.
Paul Bakker17373852011-01-06 14:20:01 +0000402 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000403 * The result is calculated as
404 * Output = message_digest(file contents).
Paul Bakker17373852011-01-06 14:20:01 +0000405 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000406 * \param md_info The information structure of the message-digest algorithm
407 * to use.
408 * \param path The input file name.
409 * \param output The generic message-digest checksum result.
410 *
Rose Zadik8c9c7942018-03-27 11:52:58 +0100411 * \return \c 0 on success.
Rose Zadikf3e47362018-04-16 16:31:16 +0100412 * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing
413 * the file pointed by \p path.
414 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
Paul Bakker17373852011-01-06 14:20:01 +0000415 */
Hanno Beckera5cedbc2019-07-17 11:21:02 +0100416int mbedtls_md_file( mbedtls_md_handle_t md_info, const char *path,
Manuel Pégourié-Gonnardbfffa902015-05-28 14:44:00 +0200417 unsigned char *output );
418#endif /* MBEDTLS_FS_IO */
Paul Bakker17373852011-01-06 14:20:01 +0000419
420/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000421 * \brief This function sets the HMAC key and prepares to
422 * authenticate a new message.
Paul Bakker17373852011-01-06 14:20:01 +0000423 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000424 * Call this function after mbedtls_md_setup(), to use
425 * the MD context for an HMAC calculation, then call
426 * mbedtls_md_hmac_update() to provide the input data, and
427 * mbedtls_md_hmac_finish() to get the HMAC value.
Paul Bakker17373852011-01-06 14:20:01 +0000428 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000429 * \param ctx The message digest context containing an embedded HMAC
430 * context.
431 * \param key The HMAC secret key.
432 * \param keylen The length of the HMAC key in Bytes.
433 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100434 * \return \c 0 on success.
435 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
436 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000437 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200438int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,
Paul Bakkerb9e4e2c2014-05-01 14:18:25 +0200439 size_t keylen );
Paul Bakker17373852011-01-06 14:20:01 +0000440
441/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000442 * \brief This function feeds an input buffer into an ongoing HMAC
443 * computation.
Paul Bakker17373852011-01-06 14:20:01 +0000444 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000445 * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
446 * before calling this function.
447 * You may call this function multiple times to pass the
448 * input piecewise.
449 * Afterwards, call mbedtls_md_hmac_finish().
Paul Bakker17373852011-01-06 14:20:01 +0000450 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000451 * \param ctx The message digest context containing an embedded HMAC
452 * context.
453 * \param input The buffer holding the input data.
454 * \param ilen The length of the input data.
455 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100456 * \return \c 0 on success.
457 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
458 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000459 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200460int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input,
Paul Bakkerb9e4e2c2014-05-01 14:18:25 +0200461 size_t ilen );
Paul Bakker17373852011-01-06 14:20:01 +0000462
463/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000464 * \brief This function finishes the HMAC operation, and writes
465 * the result to the output buffer.
Paul Bakker17373852011-01-06 14:20:01 +0000466 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000467 * Call this function after mbedtls_md_hmac_starts() and
468 * mbedtls_md_hmac_update() to get the HMAC value. Afterwards
469 * you may either call mbedtls_md_free() to clear the context,
470 * or call mbedtls_md_hmac_reset() to reuse the context with
471 * the same HMAC key.
Paul Bakker17373852011-01-06 14:20:01 +0000472 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000473 * \param ctx The message digest context containing an embedded HMAC
474 * context.
475 * \param output The generic HMAC checksum result.
476 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100477 * \return \c 0 on success.
478 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
479 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000480 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200481int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);
Paul Bakker17373852011-01-06 14:20:01 +0000482
483/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000484 * \brief This function prepares to authenticate a new message with
485 * the same key as the previous HMAC operation.
Paul Bakker17373852011-01-06 14:20:01 +0000486 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000487 * You may call this function after mbedtls_md_hmac_finish().
488 * Afterwards call mbedtls_md_hmac_update() to pass the new
489 * input.
Paul Bakker17373852011-01-06 14:20:01 +0000490 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000491 * \param ctx The message digest context containing an embedded HMAC
492 * context.
493 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100494 * \return \c 0 on success.
495 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
496 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000497 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200498int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );
Paul Bakker17373852011-01-06 14:20:01 +0000499
500/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000501 * \brief This function calculates the full generic HMAC
502 * on the input buffer with the provided key.
Paul Bakker17373852011-01-06 14:20:01 +0000503 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000504 * The function allocates the context, performs the
505 * calculation, and frees the context.
Paul Bakker17373852011-01-06 14:20:01 +0000506 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000507 * The HMAC result is calculated as
508 * output = generic HMAC(hmac key, input buffer).
509 *
510 * \param md_info The information structure of the message-digest algorithm
511 * to use.
512 * \param key The HMAC secret key.
513 * \param keylen The length of the HMAC secret key in Bytes.
514 * \param input The buffer holding the input data.
515 * \param ilen The length of the input data.
516 * \param output The generic HMAC result.
517 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100518 * \return \c 0 on success.
519 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
520 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000521 */
Hanno Beckera5cedbc2019-07-17 11:21:02 +0100522int mbedtls_md_hmac( mbedtls_md_handle_t md_info, const unsigned char *key, size_t keylen,
Paul Bakker23986e52011-04-24 08:57:21 +0000523 const unsigned char *input, size_t ilen,
Paul Bakker17373852011-01-06 14:20:01 +0000524 unsigned char *output );
525
Paul Bakker1bd3ae82013-03-13 10:26:44 +0100526/* Internal use */
Hanno Becker53ade9f2019-09-04 13:44:51 +0100527MBEDTLS_MD_INLINABLE_API int mbedtls_md_process( mbedtls_md_context_t *ctx,
528 const unsigned char *data );
Paul Bakker1bd3ae82013-03-13 10:26:44 +0100529
Hanno Becker527f7c92019-09-04 12:46:07 +0100530/*
531 * Internal wrapper functions for those MD API functions which should be
532 * inlined in some but not all configurations. The actual MD API will be
533 * implemented either here or in md.c, and forward to the wrappers.
534 */
535
Hanno Becker64b06232019-09-05 13:02:32 +0100536MBEDTLS_ALWAYS_INLINE static inline int mbedtls_md_setup_internal(
537 mbedtls_md_context_t *ctx, mbedtls_md_handle_t md_info, int hmac )
538{
539 if( md_info == MBEDTLS_MD_INVALID_HANDLE || ctx == NULL )
540 return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
541
542#if !defined(MBEDTLS_MD_SINGLE_HASH)
543 ctx->md_ctx = mbedtls_md_info_ctx_alloc( md_info );
544 if( ctx->md_ctx == NULL )
545 return( MBEDTLS_ERR_MD_ALLOC_FAILED );
546
547 if( hmac != 0 )
548 {
549 ctx->hmac_ctx = mbedtls_calloc( 2,
550 mbedtls_md_info_block_size( md_info ) );
551 if( ctx->hmac_ctx == NULL )
552 {
553 mbedtls_md_info_ctx_free( md_info, ctx->md_ctx);
554 return( MBEDTLS_ERR_MD_ALLOC_FAILED );
555 }
556 }
557
558 ctx->md_info = md_info;
559#else
560 ((void) hmac);
561#endif /* MBEDTLS_MD_SINGLE_HASH */
562
563 return( 0 );
564}
565
Hanno Becker527f7c92019-09-04 12:46:07 +0100566MBEDTLS_ALWAYS_INLINE static inline int mbedtls_md_starts_internal(
567 mbedtls_md_context_t *ctx )
568{
569 mbedtls_md_handle_t md_info;
570 if( ctx == NULL )
571 return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
572
573 md_info = mbedtls_md_get_handle( ctx );
574 if( md_info == MBEDTLS_MD_INVALID_HANDLE )
575 return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
576
577 return( mbedtls_md_info_starts( md_info, ctx->md_ctx ) );
578}
579
Hanno Beckerfdef5ac2019-09-04 13:20:05 +0100580MBEDTLS_ALWAYS_INLINE static inline int mbedtls_md_update_internal(
581 mbedtls_md_context_t *ctx,
582 const unsigned char *input,
583 size_t ilen )
584{
585 mbedtls_md_handle_t md_info;
586 if( ctx == NULL )
587 return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
588
589 md_info = mbedtls_md_get_handle( ctx );
590 if( md_info == MBEDTLS_MD_INVALID_HANDLE )
591 return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
592
593 return( mbedtls_md_info_update( md_info, ctx->md_ctx,
594 input, ilen ) );
595}
596
Hanno Becker993691d2019-09-04 13:24:44 +0100597MBEDTLS_ALWAYS_INLINE static inline int mbedtls_md_finish_internal(
598 mbedtls_md_context_t *ctx, unsigned char *output )
599{
600 mbedtls_md_handle_t md_info;
601 if( ctx == NULL )
602 return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
603
604 md_info = mbedtls_md_get_handle( ctx );
605 if( md_info == MBEDTLS_MD_INVALID_HANDLE )
606 return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
607
608 return( mbedtls_md_info_finish( md_info, ctx->md_ctx,
609 output ) );
610}
611
612MBEDTLS_ALWAYS_INLINE static inline int mbedtls_md_internal(
613 mbedtls_md_handle_t md_info,
614 const unsigned char *input,
615 size_t ilen,
616 unsigned char *output )
617{
618 if( md_info == MBEDTLS_MD_INVALID_HANDLE )
619 return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
620
621 return( mbedtls_md_info_digest( md_info, input,
622 ilen, output) );
623}
624
Hanno Becker53ade9f2019-09-04 13:44:51 +0100625MBEDTLS_ALWAYS_INLINE static inline int mbedtls_md_process_internal(
626 mbedtls_md_context_t *ctx, const unsigned char *data )
627{
628 mbedtls_md_handle_t md_info;
629 if( ctx == NULL )
630 return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
631
632 md_info = mbedtls_md_get_handle( ctx );
633 if( md_info == MBEDTLS_MD_INVALID_HANDLE )
634 return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
635
636 return( mbedtls_md_info_process( md_info, ctx->md_ctx, data ) );
637}
638
Hanno Becker527f7c92019-09-04 12:46:07 +0100639#if defined(MBEDTLS_MD_SINGLE_HASH)
Hanno Becker64b06232019-09-05 13:02:32 +0100640
641MBEDTLS_MD_INLINABLE_API int mbedtls_md_setup(
642 mbedtls_md_context_t *ctx, mbedtls_md_handle_t md_info, int hmac )
643{
644 return( mbedtls_md_setup_internal( ctx, md_info, hmac ) );
645}
646
Hanno Becker527f7c92019-09-04 12:46:07 +0100647MBEDTLS_MD_INLINABLE_API int mbedtls_md_starts(
648 mbedtls_md_context_t *ctx )
649{
650 return( mbedtls_md_starts_internal( ctx ) );
651}
Hanno Beckerfdef5ac2019-09-04 13:20:05 +0100652
653MBEDTLS_MD_INLINABLE_API int mbedtls_md_update(
654 mbedtls_md_context_t *ctx,
655 const unsigned char *input,
656 size_t ilen )
657{
658 return( mbedtls_md_update_internal( ctx, input, ilen ) );
659}
Hanno Becker993691d2019-09-04 13:24:44 +0100660
661MBEDTLS_MD_INLINABLE_API int mbedtls_md_finish(
662 mbedtls_md_context_t *ctx, unsigned char *output )
663{
664 return( mbedtls_md_finish_internal( ctx, output ) );
665}
666
667MBEDTLS_MD_INLINABLE_API int mbedtls_md(
668 mbedtls_md_handle_t md_info,
669 const unsigned char *input,
670 size_t ilen,
671 unsigned char *output )
672{
673 return( mbedtls_md_internal( md_info, input, ilen, output ) );
674}
675
Hanno Becker53ade9f2019-09-04 13:44:51 +0100676MBEDTLS_MD_INLINABLE_API int mbedtls_md_process(
677 mbedtls_md_context_t *ctx, const unsigned char *data )
678{
679 return( mbedtls_md_process_internal( ctx, data ) );
680}
681
Hanno Becker527f7c92019-09-04 12:46:07 +0100682#endif /* MBEDTLS_MD_SINGLE_HASH */
683
Paul Bakker17373852011-01-06 14:20:01 +0000684#ifdef __cplusplus
685}
686#endif
687
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200688#endif /* MBEDTLS_MD_H */