blob: 7b4311307ce8179053770ac84f0954befb5ce42e [file] [log] [blame]
Gilles Peskine1b6c09a2023-01-11 14:52:35 +01001/**
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/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02009 * Copyright The Mbed TLS Contributors
Dave Rodgman7ff79652023-11-03 12:04:52 +000010 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Paul Bakker17373852011-01-06 14:20:01 +000011 */
Rose Zadik64feefb2018-01-25 22:01:10 +000012
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020013#ifndef MBEDTLS_MD_H
14#define MBEDTLS_MD_H
Paul Bakker17373852011-01-06 14:20:01 +000015
Rich Evans00ab4702015-02-06 13:43:58 +000016#include <stddef.h>
Paul Bakker23986e52011-04-24 08:57:21 +000017
Ron Eldorf231eaa2017-08-22 14:50:14 +030018#if !defined(MBEDTLS_CONFIG_FILE)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010019#include "mbedtls/config.h"
Ron Eldorf231eaa2017-08-22 14:50:14 +030020#else
21#include MBEDTLS_CONFIG_FILE
22#endif
Gilles Peskine2b3f21d2021-12-10 21:35:10 +010023#include "mbedtls/platform_util.h"
Ron Eldorf231eaa2017-08-22 14:50:14 +030024
Gilles Peskinea3974432021-07-26 18:48:10 +020025/** The selected feature is not available. */
26#define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080
27/** Bad input parameters to function. */
28#define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100
29/** Failed to allocate memory. */
30#define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180
31/** Opening or reading of file failed. */
32#define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200
Ron Eldor9924bdc2018-10-04 10:59:13 +030033
34/* MBEDTLS_ERR_MD_HW_ACCEL_FAILED is deprecated and should not be used. */
Gilles Peskinea3974432021-07-26 18:48:10 +020035/** MD hardware accelerator failed. */
36#define MBEDTLS_ERR_MD_HW_ACCEL_FAILED -0x5280
Paul Bakker335db3f2011-04-25 15:28:35 +000037
Paul Bakker407a0da2013-06-27 14:29:21 +020038#ifdef __cplusplus
39extern "C" {
40#endif
41
Hanno Beckerbbca8c52017-09-25 14:53:51 +010042/**
Rose Zadik8c9c7942018-03-27 11:52:58 +010043 * \brief Supported message digests.
Hanno Beckerbbca8c52017-09-25 14:53:51 +010044 *
45 * \warning MD2, MD4, MD5 and SHA-1 are considered weak message digests and
46 * their use constitutes a security risk. We recommend considering
47 * stronger message digests instead.
48 *
49 */
Paul Bakker17373852011-01-06 14:20:01 +000050typedef enum {
Rose Zadikf3e47362018-04-16 16:31:16 +010051 MBEDTLS_MD_NONE=0, /**< None. */
52 MBEDTLS_MD_MD2, /**< The MD2 message digest. */
53 MBEDTLS_MD_MD4, /**< The MD4 message digest. */
54 MBEDTLS_MD_MD5, /**< The MD5 message digest. */
55 MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */
56 MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */
57 MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */
58 MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */
59 MBEDTLS_MD_SHA512, /**< The SHA-512 message digest. */
Rose Zadik8c9c7942018-03-27 11:52:58 +010060 MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020061} mbedtls_md_type_t;
Paul Bakker17373852011-01-06 14:20:01 +000062
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020063#if defined(MBEDTLS_SHA512_C)
64#define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */
Paul Bakker7db01092013-09-10 11:10:57 +020065#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020066#define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 or less */
Paul Bakker7db01092013-09-10 11:10:57 +020067#endif
Paul Bakker1b57b062011-01-06 15:48:19 +000068
Hanno Becker2e24c3b2017-12-27 21:28:58 +000069#if defined(MBEDTLS_SHA512_C)
70#define MBEDTLS_MD_MAX_BLOCK_SIZE 128
71#else
72#define MBEDTLS_MD_MAX_BLOCK_SIZE 64
73#endif
74
Paul Bakker17373852011-01-06 14:20:01 +000075/**
Rose Zadik64feefb2018-01-25 22:01:10 +000076 * Opaque struct defined in md_internal.h.
Paul Bakker17373852011-01-06 14:20:01 +000077 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020078typedef struct mbedtls_md_info_t mbedtls_md_info_t;
Paul Bakker17373852011-01-06 14:20:01 +000079
80/**
Rose Zadik64feefb2018-01-25 22:01:10 +000081 * The generic message-digest context.
Paul Bakker17373852011-01-06 14:20:01 +000082 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010083typedef struct mbedtls_md_context_t {
Rose Zadik64feefb2018-01-25 22:01:10 +000084 /** Information about the associated message digest. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020085 const mbedtls_md_info_t *md_info;
Paul Bakker17373852011-01-06 14:20:01 +000086
Rose Zadik64feefb2018-01-25 22:01:10 +000087 /** The digest-specific context. */
Paul Bakker17373852011-01-06 14:20:01 +000088 void *md_ctx;
Manuel Pégourié-Gonnard8379a822015-03-24 16:48:22 +010089
Rose Zadik64feefb2018-01-25 22:01:10 +000090 /** The HMAC part of the context. */
Manuel Pégourié-Gonnarddfb3dc82015-03-25 11:49:07 +010091 void *hmac_ctx;
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020092} mbedtls_md_context_t;
Paul Bakker17373852011-01-06 14:20:01 +000093
Paul Bakker17373852011-01-06 14:20:01 +000094/**
Rose Zadik64feefb2018-01-25 22:01:10 +000095 * \brief This function returns the list of digests supported by the
96 * generic digest module.
Paul Bakker72f62662011-01-16 21:27:44 +000097 *
Manuel Pégourié-Gonnardc52a43c2020-05-22 12:12:36 +020098 * \note The list starts with the strongest available hashes.
99 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000100 * \return A statically allocated array of digests. Each element
101 * in the returned list is an integer belonging to the
102 * message-digest enumeration #mbedtls_md_type_t.
103 * The last entry is 0.
Paul Bakker72f62662011-01-16 21:27:44 +0000104 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100105const int *mbedtls_md_list(void);
Paul Bakker72f62662011-01-16 21:27:44 +0000106
107/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000108 * \brief This function returns the message-digest information
109 * associated with the given digest name.
Paul Bakker17373852011-01-06 14:20:01 +0000110 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000111 * \param md_name The name of the digest to search for.
Paul Bakker17373852011-01-06 14:20:01 +0000112 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100113 * \return The message-digest information associated with \p md_name.
114 * \return NULL if the associated message-digest information is not found.
Paul Bakker17373852011-01-06 14:20:01 +0000115 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100116const mbedtls_md_info_t *mbedtls_md_info_from_string(const char *md_name);
Paul Bakker17373852011-01-06 14:20:01 +0000117
118/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000119 * \brief This function returns the message-digest information
120 * associated with the given digest type.
Paul Bakker17373852011-01-06 14:20:01 +0000121 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000122 * \param md_type The type of digest to search for.
Paul Bakker17373852011-01-06 14:20:01 +0000123 *
Rose Zadik8c9c7942018-03-27 11:52:58 +0100124 * \return The message-digest information associated with \p md_type.
125 * \return NULL if the associated message-digest information is not found.
Paul Bakker17373852011-01-06 14:20:01 +0000126 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100127const mbedtls_md_info_t *mbedtls_md_info_from_type(mbedtls_md_type_t md_type);
Paul Bakker17373852011-01-06 14:20:01 +0000128
129/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000130 * \brief This function initializes a message-digest context without
131 * binding it to a particular message-digest algorithm.
132 *
133 * This function should always be called first. It prepares the
134 * context for mbedtls_md_setup() for binding it to a
135 * message-digest algorithm.
Paul Bakker84bbeb52014-07-01 14:53:22 +0200136 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100137void mbedtls_md_init(mbedtls_md_context_t *ctx);
Paul Bakker84bbeb52014-07-01 14:53:22 +0200138
139/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000140 * \brief This function clears the internal structure of \p ctx and
141 * frees any embedded internal structure, but does not free
142 * \p ctx itself.
143 *
144 * If you have called mbedtls_md_setup() on \p ctx, you must
145 * call mbedtls_md_free() when you are no longer using the
146 * context.
147 * Calling this function if you have previously
148 * called mbedtls_md_init() and nothing else is optional.
149 * You must not call this function if you have not called
150 * mbedtls_md_init().
Paul Bakker84bbeb52014-07-01 14:53:22 +0200151 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100152void mbedtls_md_free(mbedtls_md_context_t *ctx);
Paul Bakker84bbeb52014-07-01 14:53:22 +0200153
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100154#if !defined(MBEDTLS_DEPRECATED_REMOVED)
Manuel Pégourié-Gonnard93c08472021-04-15 12:23:55 +0200155#if defined(MBEDTLS_DEPRECATED_WARNING)
156#define MBEDTLS_DEPRECATED __attribute__((deprecated))
157#else
158#define MBEDTLS_DEPRECATED
159#endif
160/**
161 * \brief This function selects the message digest algorithm to use,
162 * and allocates internal structures.
163 *
164 * It should be called after mbedtls_md_init() or mbedtls_md_free().
165 * Makes it necessary to call mbedtls_md_free() later.
166 *
167 * \deprecated Superseded by mbedtls_md_setup() in 2.0.0
168 *
169 * \param ctx The context to set up.
170 * \param md_info The information structure of the message-digest algorithm
171 * to use.
172 *
173 * \return \c 0 on success.
174 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
175 * failure.
176 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
177 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100178int mbedtls_md_init_ctx(mbedtls_md_context_t *ctx,
179 const mbedtls_md_info_t *md_info) MBEDTLS_DEPRECATED;
Manuel Pégourié-Gonnard93c08472021-04-15 12:23:55 +0200180#undef MBEDTLS_DEPRECATED
181#endif /* MBEDTLS_DEPRECATED_REMOVED */
Manuel Pégourié-Gonnard147fa092015-03-25 16:43:14 +0100182
Paul Bakker84bbeb52014-07-01 14:53:22 +0200183/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000184 * \brief This function selects the message digest algorithm to use,
185 * and allocates internal structures.
Paul Bakker562535d2011-01-20 16:42:01 +0000186 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000187 * It should be called after mbedtls_md_init() or
188 * mbedtls_md_free(). Makes it necessary to call
189 * mbedtls_md_free() later.
190 *
191 * \param ctx The context to set up.
192 * \param md_info The information structure of the message-digest algorithm
193 * to use.
Rose Zadik8c9c7942018-03-27 11:52:58 +0100194 * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory),
195 * or non-zero: HMAC is used with this context.
Paul Bakker562535d2011-01-20 16:42:01 +0000196 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100197 * \return \c 0 on success.
198 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
199 * failure.
200 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
Paul Bakker562535d2011-01-20 16:42:01 +0000201 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100202MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100203int mbedtls_md_setup(mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac);
Paul Bakker562535d2011-01-20 16:42:01 +0000204
205/**
Tom Cosgrove5205c972022-07-28 06:12:08 +0100206 * \brief This function clones the state of a message-digest
Rose Zadik64feefb2018-01-25 22:01:10 +0000207 * context.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200208 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000209 * \note You must call mbedtls_md_setup() on \c dst before calling
210 * this function.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200211 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000212 * \note The two contexts must have the same type,
213 * for example, both are SHA-256.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200214 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000215 * \warning This function clones the message-digest state, not the
216 * HMAC state.
217 *
218 * \param dst The destination context.
219 * \param src The context to be cloned.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200220 *
Rose Zadik8c9c7942018-03-27 11:52:58 +0100221 * \return \c 0 on success.
Rose Zadikf3e47362018-04-16 16:31:16 +0100222 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200223 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100224MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100225int mbedtls_md_clone(mbedtls_md_context_t *dst,
226 const mbedtls_md_context_t *src);
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200227
228/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000229 * \brief This function extracts the message-digest size from the
230 * message-digest information structure.
Paul Bakker17373852011-01-06 14:20:01 +0000231 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000232 * \param md_info The information structure of the message-digest algorithm
233 * to use.
Paul Bakker17373852011-01-06 14:20:01 +0000234 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000235 * \return The size of the message-digest output in Bytes.
Paul Bakker17373852011-01-06 14:20:01 +0000236 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100237unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info);
Paul Bakker17373852011-01-06 14:20:01 +0000238
239/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000240 * \brief This function extracts the message-digest type from the
241 * message-digest information structure.
Paul Bakker17373852011-01-06 14:20:01 +0000242 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000243 * \param md_info The information structure of the message-digest algorithm
244 * to use.
Paul Bakker17373852011-01-06 14:20:01 +0000245 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000246 * \return The type of the message digest.
Paul Bakker17373852011-01-06 14:20:01 +0000247 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100248mbedtls_md_type_t mbedtls_md_get_type(const mbedtls_md_info_t *md_info);
Paul Bakker17373852011-01-06 14:20:01 +0000249
250/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000251 * \brief This function extracts the message-digest name from the
252 * message-digest information structure.
Paul Bakker17373852011-01-06 14:20:01 +0000253 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000254 * \param md_info The information structure of the message-digest algorithm
255 * to use.
Paul Bakker17373852011-01-06 14:20:01 +0000256 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000257 * \return The name of the message digest.
Paul Bakker17373852011-01-06 14:20:01 +0000258 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100259const char *mbedtls_md_get_name(const mbedtls_md_info_t *md_info);
Paul Bakker17373852011-01-06 14:20:01 +0000260
261/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000262 * \brief This function starts a message-digest computation.
Paul Bakker17373852011-01-06 14:20:01 +0000263 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000264 * You must call this function after setting up the context
265 * with mbedtls_md_setup(), and before passing data with
266 * mbedtls_md_update().
Paul Bakker17373852011-01-06 14:20:01 +0000267 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000268 * \param ctx The generic message-digest context.
269 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100270 * \return \c 0 on success.
271 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
272 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000273 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100274MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100275int mbedtls_md_starts(mbedtls_md_context_t *ctx);
Paul Bakker17373852011-01-06 14:20:01 +0000276
277/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000278 * \brief This function feeds an input buffer into an ongoing
279 * message-digest computation.
Paul Bakker17373852011-01-06 14:20:01 +0000280 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000281 * You must call mbedtls_md_starts() before calling this
282 * function. You may call this function multiple times.
283 * Afterwards, call mbedtls_md_finish().
Paul Bakker17373852011-01-06 14:20:01 +0000284 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000285 * \param ctx The generic message-digest context.
286 * \param input The buffer holding the input data.
287 * \param ilen The length of the input data.
288 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100289 * \return \c 0 on success.
290 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
291 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000292 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100293MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100294int mbedtls_md_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen);
Paul Bakker17373852011-01-06 14:20:01 +0000295
296/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000297 * \brief This function finishes the digest operation,
298 * and writes the result to the output buffer.
Paul Bakker17373852011-01-06 14:20:01 +0000299 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000300 * Call this function after a call to mbedtls_md_starts(),
301 * followed by any number of calls to mbedtls_md_update().
302 * Afterwards, you may either clear the context with
303 * mbedtls_md_free(), or call mbedtls_md_starts() to reuse
304 * the context for another digest operation with the same
305 * algorithm.
Paul Bakker17373852011-01-06 14:20:01 +0000306 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000307 * \param ctx The generic message-digest context.
308 * \param output The buffer for the generic message-digest checksum result.
309 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100310 * \return \c 0 on success.
311 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
312 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000313 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100314MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100315int mbedtls_md_finish(mbedtls_md_context_t *ctx, unsigned char *output);
Paul Bakker17373852011-01-06 14:20:01 +0000316
317/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000318 * \brief This function calculates the message-digest of a buffer,
319 * with respect to a configurable message-digest algorithm
320 * in a single call.
Paul Bakker17373852011-01-06 14:20:01 +0000321 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000322 * The result is calculated as
323 * Output = message_digest(input buffer).
Paul Bakker17373852011-01-06 14:20:01 +0000324 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000325 * \param md_info The information structure of the message-digest algorithm
326 * to use.
327 * \param input The buffer holding the data.
328 * \param ilen The length of the input data.
329 * \param output The generic message-digest checksum result.
330 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100331 * \return \c 0 on success.
332 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
333 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000334 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100335MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100336int mbedtls_md(const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
337 unsigned char *output);
Paul Bakker17373852011-01-06 14:20:01 +0000338
Manuel Pégourié-Gonnardbfffa902015-05-28 14:44:00 +0200339#if defined(MBEDTLS_FS_IO)
Paul Bakker17373852011-01-06 14:20:01 +0000340/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000341 * \brief This function calculates the message-digest checksum
342 * result of the contents of the provided file.
Paul Bakker17373852011-01-06 14:20:01 +0000343 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000344 * The result is calculated as
345 * Output = message_digest(file contents).
Paul Bakker17373852011-01-06 14:20:01 +0000346 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000347 * \param md_info The information structure of the message-digest algorithm
348 * to use.
349 * \param path The input file name.
350 * \param output The generic message-digest checksum result.
351 *
Rose Zadik8c9c7942018-03-27 11:52:58 +0100352 * \return \c 0 on success.
Rose Zadikf3e47362018-04-16 16:31:16 +0100353 * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing
354 * the file pointed by \p path.
355 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
Paul Bakker17373852011-01-06 14:20:01 +0000356 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100357MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100358int mbedtls_md_file(const mbedtls_md_info_t *md_info, const char *path,
359 unsigned char *output);
Manuel Pégourié-Gonnardbfffa902015-05-28 14:44:00 +0200360#endif /* MBEDTLS_FS_IO */
Paul Bakker17373852011-01-06 14:20:01 +0000361
362/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000363 * \brief This function sets the HMAC key and prepares to
364 * authenticate a new message.
Paul Bakker17373852011-01-06 14:20:01 +0000365 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000366 * Call this function after mbedtls_md_setup(), to use
367 * the MD context for an HMAC calculation, then call
368 * mbedtls_md_hmac_update() to provide the input data, and
369 * mbedtls_md_hmac_finish() to get the HMAC value.
Paul Bakker17373852011-01-06 14:20:01 +0000370 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000371 * \param ctx The message digest context containing an embedded HMAC
372 * context.
373 * \param key The HMAC secret key.
374 * \param keylen The length of the HMAC key in Bytes.
375 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100376 * \return \c 0 on success.
377 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
378 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000379 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100380MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100381int mbedtls_md_hmac_starts(mbedtls_md_context_t *ctx, const unsigned char *key,
382 size_t keylen);
Paul Bakker17373852011-01-06 14:20:01 +0000383
384/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000385 * \brief This function feeds an input buffer into an ongoing HMAC
386 * computation.
Paul Bakker17373852011-01-06 14:20:01 +0000387 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000388 * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
389 * before calling this function.
390 * You may call this function multiple times to pass the
391 * input piecewise.
392 * Afterwards, call mbedtls_md_hmac_finish().
Paul Bakker17373852011-01-06 14:20:01 +0000393 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000394 * \param ctx The message digest context containing an embedded HMAC
395 * context.
396 * \param input The buffer holding the input data.
397 * \param ilen The length of the input data.
398 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100399 * \return \c 0 on success.
400 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
401 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000402 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100403MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100404int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input,
405 size_t ilen);
Paul Bakker17373852011-01-06 14:20:01 +0000406
407/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000408 * \brief This function finishes the HMAC operation, and writes
409 * the result to the output buffer.
Paul Bakker17373852011-01-06 14:20:01 +0000410 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000411 * Call this function after mbedtls_md_hmac_starts() and
412 * mbedtls_md_hmac_update() to get the HMAC value. Afterwards
413 * you may either call mbedtls_md_free() to clear the context,
414 * or call mbedtls_md_hmac_reset() to reuse the context with
415 * the same HMAC key.
Paul Bakker17373852011-01-06 14:20:01 +0000416 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000417 * \param ctx The message digest context containing an embedded HMAC
418 * context.
419 * \param output The generic HMAC checksum result.
420 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100421 * \return \c 0 on success.
422 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
423 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000424 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100425MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100426int mbedtls_md_hmac_finish(mbedtls_md_context_t *ctx, unsigned char *output);
Paul Bakker17373852011-01-06 14:20:01 +0000427
428/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000429 * \brief This function prepares to authenticate a new message with
430 * the same key as the previous HMAC operation.
Paul Bakker17373852011-01-06 14:20:01 +0000431 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000432 * You may call this function after mbedtls_md_hmac_finish().
433 * Afterwards call mbedtls_md_hmac_update() to pass the new
434 * input.
Paul Bakker17373852011-01-06 14:20:01 +0000435 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000436 * \param ctx The message digest context containing an embedded HMAC
437 * context.
438 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100439 * \return \c 0 on success.
440 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
441 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000442 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100443MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100444int mbedtls_md_hmac_reset(mbedtls_md_context_t *ctx);
Paul Bakker17373852011-01-06 14:20:01 +0000445
446/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000447 * \brief This function calculates the full generic HMAC
448 * on the input buffer with the provided key.
Paul Bakker17373852011-01-06 14:20:01 +0000449 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000450 * The function allocates the context, performs the
451 * calculation, and frees the context.
Paul Bakker17373852011-01-06 14:20:01 +0000452 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000453 * The HMAC result is calculated as
454 * output = generic HMAC(hmac key, input buffer).
455 *
456 * \param md_info The information structure of the message-digest algorithm
457 * to use.
458 * \param key The HMAC secret key.
459 * \param keylen The length of the HMAC secret key in Bytes.
460 * \param input The buffer holding the input data.
461 * \param ilen The length of the input data.
462 * \param output The generic HMAC result.
463 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100464 * \return \c 0 on success.
465 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
466 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000467 */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100468MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100469int mbedtls_md_hmac(const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
470 const unsigned char *input, size_t ilen,
471 unsigned char *output);
Paul Bakker17373852011-01-06 14:20:01 +0000472
Paul Bakker1bd3ae82013-03-13 10:26:44 +0100473/* Internal use */
Gilles Peskine2b3f21d2021-12-10 21:35:10 +0100474MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100475int mbedtls_md_process(mbedtls_md_context_t *ctx, const unsigned char *data);
Paul Bakker1bd3ae82013-03-13 10:26:44 +0100476
Paul Bakker17373852011-01-06 14:20:01 +0000477#ifdef __cplusplus
478}
479#endif
480
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200481#endif /* MBEDTLS_MD_H */