blob: 478e9f7667010fcea4f3b77a78b06af269c34b45 [file] [log] [blame]
Gilles Peskine449bd832023-01-11 14:50:10 +01001/**
Simon Butcher5b331b92016-01-03 16:14:14 +00002 * \file md.h
Paul Bakker9af723c2014-05-01 13:03:14 +02003 *
Manuel Pégourié-Gonnardb9b630d2023-02-16 19:07:31 +01004 * \brief This file contains the generic functions for message-digest
5 * (hashing) and HMAC.
Paul Bakker17373852011-01-06 14:20:01 +00006 *
7 * \author Adriaan de Jong <dejong@fox-it.com>
Darryl Greena40a1012018-01-05 15:33:17 +00008 */
9/*
Bence Szépkúti1e148272020-08-07 13:07:28 +020010 * Copyright The Mbed TLS Contributors
Dave Rodgman16799db2023-11-02 19:47:20 +000011 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Paul Bakker17373852011-01-06 14:20:01 +000012 */
Rose Zadik64feefb2018-01-25 22:01:10 +000013
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020014#ifndef MBEDTLS_MD_H
15#define MBEDTLS_MD_H
Mateusz Starzyk846f0212021-05-19 19:44:07 +020016#include "mbedtls/private_access.h"
Paul Bakker17373852011-01-06 14:20:01 +000017
Rich Evans00ab4702015-02-06 13:43:58 +000018#include <stddef.h>
Paul Bakker23986e52011-04-24 08:57:21 +000019
Bence Szépkútic662b362021-05-27 11:25:03 +020020#include "mbedtls/build_info.h"
Gilles Peskineecf6beb2021-12-10 21:35:10 +010021#include "mbedtls/platform_util.h"
Ron Eldorf231eaa2017-08-22 14:50:14 +030022
Gilles Peskined2971572021-07-26 18:48:10 +020023/** The selected feature is not available. */
24#define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080
25/** Bad input parameters to function. */
26#define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100
27/** Failed to allocate memory. */
28#define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180
29/** Opening or reading of file failed. */
30#define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200
Ron Eldor9924bdc2018-10-04 10:59:13 +030031
Paul Bakker407a0da2013-06-27 14:29:21 +020032#ifdef __cplusplus
33extern "C" {
34#endif
35
Hanno Beckerbbca8c52017-09-25 14:53:51 +010036/**
Rose Zadik8c9c7942018-03-27 11:52:58 +010037 * \brief Supported message digests.
Hanno Beckerbbca8c52017-09-25 14:53:51 +010038 *
TRodziewicz10e8cf52021-05-31 17:58:57 +020039 * \warning MD5 and SHA-1 are considered weak message digests and
Hanno Beckerbbca8c52017-09-25 14:53:51 +010040 * their use constitutes a security risk. We recommend considering
41 * stronger message digests instead.
42 *
43 */
Manuel Pégourié-Gonnard1f6d2e32023-06-06 12:34:45 +020044/* Note: these are aligned with the definitions of PSA_ALG_ macros for hashes,
45 * in order to enable an efficient implementation of conversion functions.
46 * This is tested by md_to_from_psa() in test_suite_md. */
Paul Bakker17373852011-01-06 14:20:01 +000047typedef enum {
Rose Zadikf3e47362018-04-16 16:31:16 +010048 MBEDTLS_MD_NONE=0, /**< None. */
Manuel Pégourié-Gonnard9b763182023-05-31 10:54:08 +020049 MBEDTLS_MD_MD5=0x03, /**< The MD5 message digest. */
50 MBEDTLS_MD_RIPEMD160=0x04, /**< The RIPEMD-160 message digest. */
51 MBEDTLS_MD_SHA1=0x05, /**< The SHA-1 message digest. */
52 MBEDTLS_MD_SHA224=0x08, /**< The SHA-224 message digest. */
53 MBEDTLS_MD_SHA256=0x09, /**< The SHA-256 message digest. */
54 MBEDTLS_MD_SHA384=0x0a, /**< The SHA-384 message digest. */
55 MBEDTLS_MD_SHA512=0x0b, /**< The SHA-512 message digest. */
56 MBEDTLS_MD_SHA3_224=0x10, /**< The SHA3-224 message digest. */
57 MBEDTLS_MD_SHA3_256=0x11, /**< The SHA3-256 message digest. */
58 MBEDTLS_MD_SHA3_384=0x12, /**< The SHA3-384 message digest. */
59 MBEDTLS_MD_SHA3_512=0x13, /**< The SHA3-512 message digest. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020060} mbedtls_md_type_t;
Paul Bakker17373852011-01-06 14:20:01 +000061
Dave Rodgman93041862023-06-08 10:13:22 +010062/* Note: this should always be >= PSA_HASH_MAX_SIZE
63 * in all builds with both CRYPTO_C and MD_LIGHT.
64 *
65 * This is to make things easier for modules such as TLS that may define a
66 * buffer size using MD_MAX_SIZE in a part of the code that's common to PSA
67 * and legacy, then assume the buffer's size is PSA_HASH_MAX_SIZE in another
68 * part of the code based on PSA.
69 */
Dave Rodgman0442e1b2023-06-08 16:03:33 +010070#if defined(MBEDTLS_MD_CAN_SHA512) || defined(MBEDTLS_MD_CAN_SHA3_512)
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020071#define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */
Dave Rodgman0442e1b2023-06-08 16:03:33 +010072#elif defined(MBEDTLS_MD_CAN_SHA384) || defined(MBEDTLS_MD_CAN_SHA3_384)
Valerio Settid55cb5b2022-12-22 14:26:55 +010073#define MBEDTLS_MD_MAX_SIZE 48 /* longest known is SHA384 */
Dave Rodgman0442e1b2023-06-08 16:03:33 +010074#elif defined(MBEDTLS_MD_CAN_SHA256) || defined(MBEDTLS_MD_CAN_SHA3_256)
Valerio Settid55cb5b2022-12-22 14:26:55 +010075#define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 */
Dave Rodgman0442e1b2023-06-08 16:03:33 +010076#elif defined(MBEDTLS_MD_CAN_SHA224) || defined(MBEDTLS_MD_CAN_SHA3_224)
Valerio Settid55cb5b2022-12-22 14:26:55 +010077#define MBEDTLS_MD_MAX_SIZE 28 /* longest known is SHA224 */
Paul Bakker7db01092013-09-10 11:10:57 +020078#else
Gilles Peskine83d9e092022-10-22 18:32:43 +020079#define MBEDTLS_MD_MAX_SIZE 20 /* longest known is SHA1 or RIPE MD-160
80 or smaller (MD5 and earlier) */
Paul Bakker7db01092013-09-10 11:10:57 +020081#endif
Paul Bakker1b57b062011-01-06 15:48:19 +000082
Dave Rodgmanff45d442023-06-08 10:11:34 +010083#if defined(MBEDTLS_MD_CAN_SHA3_224)
Pol Henarejos4712d4c2022-05-20 14:17:14 +020084#define MBEDTLS_MD_MAX_BLOCK_SIZE 144 /* the longest known is SHA3-224 */
Dave Rodgman0442e1b2023-06-08 16:03:33 +010085#elif defined(MBEDTLS_MD_CAN_SHA3_256)
86#define MBEDTLS_MD_MAX_BLOCK_SIZE 136
Dave Rodgmanf9563122023-06-11 16:04:29 +010087#elif defined(MBEDTLS_MD_CAN_SHA512) || defined(MBEDTLS_MD_CAN_SHA384)
Hanno Becker2e24c3b2017-12-27 21:28:58 +000088#define MBEDTLS_MD_MAX_BLOCK_SIZE 128
Dave Rodgman0442e1b2023-06-08 16:03:33 +010089#elif defined(MBEDTLS_MD_CAN_SHA3_384)
90#define MBEDTLS_MD_MAX_BLOCK_SIZE 104
91#elif defined(MBEDTLS_MD_CAN_SHA3_512)
92#define MBEDTLS_MD_MAX_BLOCK_SIZE 72
Hanno Becker2e24c3b2017-12-27 21:28:58 +000093#else
94#define MBEDTLS_MD_MAX_BLOCK_SIZE 64
95#endif
96
Paul Bakker17373852011-01-06 14:20:01 +000097/**
Chris Jones3848e312021-03-11 16:17:59 +000098 * Opaque struct.
99 *
100 * Constructed using either #mbedtls_md_info_from_string or
101 * #mbedtls_md_info_from_type.
102 *
103 * Fields can be accessed with #mbedtls_md_get_size,
104 * #mbedtls_md_get_type and #mbedtls_md_get_name.
Paul Bakker17373852011-01-06 14:20:01 +0000105 */
Chris Jones3848e312021-03-11 16:17:59 +0000106/* Defined internally in library/md_wrap.h. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200107typedef struct mbedtls_md_info_t mbedtls_md_info_t;
Paul Bakker17373852011-01-06 14:20:01 +0000108
109/**
Manuel Pégourié-Gonnardd8ea37f2023-03-09 10:46:22 +0100110 * Used internally to indicate whether a context uses legacy or PSA.
111 *
112 * Internal use only.
113 */
114typedef enum {
115 MBEDTLS_MD_ENGINE_LEGACY = 0,
116 MBEDTLS_MD_ENGINE_PSA,
117} mbedtls_md_engine_t;
118
119/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000120 * The generic message-digest context.
Paul Bakker17373852011-01-06 14:20:01 +0000121 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100122typedef struct mbedtls_md_context_t {
Rose Zadik64feefb2018-01-25 22:01:10 +0000123 /** Information about the associated message digest. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200124 const mbedtls_md_info_t *MBEDTLS_PRIVATE(md_info);
Paul Bakker17373852011-01-06 14:20:01 +0000125
Manuel Pégourié-Gonnardd8ea37f2023-03-09 10:46:22 +0100126#if defined(MBEDTLS_MD_SOME_PSA)
127 /** Are hash operations dispatched to PSA or legacy? */
128 mbedtls_md_engine_t MBEDTLS_PRIVATE(engine);
129#endif
130
131 /** The digest-specific context (legacy) or the PSA operation. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200132 void *MBEDTLS_PRIVATE(md_ctx);
Manuel Pégourié-Gonnard8379a822015-03-24 16:48:22 +0100133
Manuel Pégourié-Gonnard39a376a2023-03-09 17:21:40 +0100134#if defined(MBEDTLS_MD_C)
Rose Zadik64feefb2018-01-25 22:01:10 +0000135 /** The HMAC part of the context. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200136 void *MBEDTLS_PRIVATE(hmac_ctx);
Manuel Pégourié-Gonnard39a376a2023-03-09 17:21:40 +0100137#endif
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200138} mbedtls_md_context_t;
Paul Bakker17373852011-01-06 14:20:01 +0000139
Paul Bakker17373852011-01-06 14:20:01 +0000140/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000141 * \brief This function returns the message-digest information
142 * associated with the given digest type.
Paul Bakker17373852011-01-06 14:20:01 +0000143 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000144 * \param md_type The type of digest to search for.
Paul Bakker17373852011-01-06 14:20:01 +0000145 *
Rose Zadik8c9c7942018-03-27 11:52:58 +0100146 * \return The message-digest information associated with \p md_type.
147 * \return NULL if the associated message-digest information is not found.
Paul Bakker17373852011-01-06 14:20:01 +0000148 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100149const mbedtls_md_info_t *mbedtls_md_info_from_type(mbedtls_md_type_t md_type);
Paul Bakker17373852011-01-06 14:20:01 +0000150
151/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000152 * \brief This function initializes a message-digest context without
153 * binding it to a particular message-digest algorithm.
154 *
155 * This function should always be called first. It prepares the
156 * context for mbedtls_md_setup() for binding it to a
157 * message-digest algorithm.
Paul Bakker84bbeb52014-07-01 14:53:22 +0200158 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100159void mbedtls_md_init(mbedtls_md_context_t *ctx);
Paul Bakker84bbeb52014-07-01 14:53:22 +0200160
161/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000162 * \brief This function clears the internal structure of \p ctx and
163 * frees any embedded internal structure, but does not free
164 * \p ctx itself.
165 *
166 * If you have called mbedtls_md_setup() on \p ctx, you must
167 * call mbedtls_md_free() when you are no longer using the
168 * context.
169 * Calling this function if you have previously
170 * called mbedtls_md_init() and nothing else is optional.
171 * You must not call this function if you have not called
172 * mbedtls_md_init().
Paul Bakker84bbeb52014-07-01 14:53:22 +0200173 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100174void mbedtls_md_free(mbedtls_md_context_t *ctx);
Paul Bakker84bbeb52014-07-01 14:53:22 +0200175
Manuel Pégourié-Gonnard147fa092015-03-25 16:43:14 +0100176
Paul Bakker84bbeb52014-07-01 14:53:22 +0200177/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000178 * \brief This function selects the message digest algorithm to use,
179 * and allocates internal structures.
Paul Bakker562535d2011-01-20 16:42:01 +0000180 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000181 * It should be called after mbedtls_md_init() or
182 * mbedtls_md_free(). Makes it necessary to call
183 * mbedtls_md_free() later.
184 *
185 * \param ctx The context to set up.
186 * \param md_info The information structure of the message-digest algorithm
187 * to use.
Rose Zadik8c9c7942018-03-27 11:52:58 +0100188 * \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory),
189 * or non-zero: HMAC is used with this context.
Paul Bakker562535d2011-01-20 16:42:01 +0000190 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100191 * \return \c 0 on success.
192 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
193 * failure.
194 * \return #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
Paul Bakker562535d2011-01-20 16:42:01 +0000195 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100196MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100197int mbedtls_md_setup(mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac);
Paul Bakker562535d2011-01-20 16:42:01 +0000198
199/**
Tom Cosgrovece7f18c2022-07-28 05:50:56 +0100200 * \brief This function clones the state of a message-digest
Rose Zadik64feefb2018-01-25 22:01:10 +0000201 * context.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200202 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000203 * \note You must call mbedtls_md_setup() on \c dst before calling
204 * this function.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200205 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000206 * \note The two contexts must have the same type,
207 * for example, both are SHA-256.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200208 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000209 * \warning This function clones the message-digest state, not the
210 * HMAC state.
211 *
212 * \param dst The destination context.
213 * \param src The context to be cloned.
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200214 *
Rose Zadik8c9c7942018-03-27 11:52:58 +0100215 * \return \c 0 on success.
Rose Zadikf3e47362018-04-16 16:31:16 +0100216 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.
Manuel Pégourié-Gonnard9b146392023-03-09 15:56:14 +0100217 * \return #MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE if both contexts are
218 * not using the same engine. This can be avoided by moving
219 * the call to psa_crypto_init() before the first call to
220 * mbedtls_md_setup().
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200221 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100222MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100223int mbedtls_md_clone(mbedtls_md_context_t *dst,
224 const mbedtls_md_context_t *src);
Manuel Pégourié-Gonnard052a6c92015-07-06 16:06:02 +0200225
226/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000227 * \brief This function extracts the message-digest size from the
228 * message-digest information structure.
Paul Bakker17373852011-01-06 14:20:01 +0000229 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000230 * \param md_info The information structure of the message-digest algorithm
231 * to use.
Paul Bakker17373852011-01-06 14:20:01 +0000232 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000233 * \return The size of the message-digest output in Bytes.
Paul Bakker17373852011-01-06 14:20:01 +0000234 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100235unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info);
Paul Bakker17373852011-01-06 14:20:01 +0000236
237/**
Manuel Pégourié-Gonnard1ef26e22023-01-27 11:47:05 +0100238 * \brief This function gives the message-digest size associated to
239 * message-digest type.
240 *
241 * \param md_type The message-digest type.
242 *
243 * \return The size of the message-digest output in Bytes,
244 * or 0 if the message-digest type is not known.
245 */
246static inline unsigned char mbedtls_md_get_size_from_type(mbedtls_md_type_t md_type)
247{
248 return mbedtls_md_get_size(mbedtls_md_info_from_type(md_type));
249}
250
251/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000252 * \brief This function extracts the message-digest type from the
253 * message-digest information structure.
Paul Bakker17373852011-01-06 14:20:01 +0000254 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000255 * \param md_info The information structure of the message-digest algorithm
256 * to use.
Paul Bakker17373852011-01-06 14:20:01 +0000257 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000258 * \return The type of the message digest.
Paul Bakker17373852011-01-06 14:20:01 +0000259 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100260mbedtls_md_type_t mbedtls_md_get_type(const mbedtls_md_info_t *md_info);
Paul Bakker17373852011-01-06 14:20:01 +0000261
262/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000263 * \brief This function starts a message-digest computation.
Paul Bakker17373852011-01-06 14:20:01 +0000264 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000265 * 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 Bakker17373852011-01-06 14:20:01 +0000268 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000269 * \param ctx The generic message-digest context.
270 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100271 * \return \c 0 on success.
272 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
273 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000274 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100275MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100276int mbedtls_md_starts(mbedtls_md_context_t *ctx);
Paul Bakker17373852011-01-06 14:20:01 +0000277
278/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000279 * \brief This function feeds an input buffer into an ongoing
280 * message-digest computation.
Paul Bakker17373852011-01-06 14:20:01 +0000281 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000282 * 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 Bakker17373852011-01-06 14:20:01 +0000285 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000286 * \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 Zadikf3e47362018-04-16 16:31:16 +0100290 * \return \c 0 on success.
291 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
292 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000293 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100294MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100295int mbedtls_md_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen);
Paul Bakker17373852011-01-06 14:20:01 +0000296
297/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000298 * \brief This function finishes the digest operation,
299 * and writes the result to the output buffer.
Paul Bakker17373852011-01-06 14:20:01 +0000300 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000301 * 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 Bakker17373852011-01-06 14:20:01 +0000307 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000308 * \param ctx The generic message-digest context.
309 * \param output The buffer for the generic message-digest checksum result.
310 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100311 * \return \c 0 on success.
312 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
313 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000314 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100315MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100316int mbedtls_md_finish(mbedtls_md_context_t *ctx, unsigned char *output);
Paul Bakker17373852011-01-06 14:20:01 +0000317
318/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000319 * \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 Bakker17373852011-01-06 14:20:01 +0000322 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000323 * The result is calculated as
324 * Output = message_digest(input buffer).
Paul Bakker17373852011-01-06 14:20:01 +0000325 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000326 * \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 Zadikf3e47362018-04-16 16:31:16 +0100332 * \return \c 0 on success.
333 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
334 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000335 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100336MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100337int mbedtls_md(const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
338 unsigned char *output);
Paul Bakker17373852011-01-06 14:20:01 +0000339
Manuel Pégourié-Gonnard82a43942023-02-23 09:36:29 +0100340/**
341 * \brief This function returns the list of digests supported by the
342 * generic digest module.
343 *
344 * \note The list starts with the strongest available hashes.
345 *
346 * \return A statically allocated array of digests. Each element
347 * in the returned list is an integer belonging to the
348 * message-digest enumeration #mbedtls_md_type_t.
349 * The last entry is 0.
350 */
351const int *mbedtls_md_list(void);
352
353/**
354 * \brief This function returns the message-digest information
355 * associated with the given digest name.
356 *
357 * \param md_name The name of the digest to search for.
358 *
359 * \return The message-digest information associated with \p md_name.
360 * \return NULL if the associated message-digest information is not found.
361 */
362const mbedtls_md_info_t *mbedtls_md_info_from_string(const char *md_name);
363
364/**
Manuel Pégourié-Gonnard0fda0d22023-07-27 12:22:52 +0200365 * \brief This function returns the name of the message digest for
366 * the message-digest information structure given.
Manuel Pégourié-Gonnard82a43942023-02-23 09:36:29 +0100367 *
368 * \param md_info The information structure of the message-digest algorithm
369 * to use.
370 *
371 * \return The name of the message digest.
372 */
373const char *mbedtls_md_get_name(const mbedtls_md_info_t *md_info);
374
375/**
376 * \brief This function returns the message-digest information
377 * from the given context.
378 *
379 * \param ctx The context from which to extract the information.
380 * This must be initialized (or \c NULL).
381 *
382 * \return The message-digest information associated with \p ctx.
383 * \return \c NULL if \p ctx is \c NULL.
384 */
385const mbedtls_md_info_t *mbedtls_md_info_from_ctx(
386 const mbedtls_md_context_t *ctx);
387
Manuel Pégourié-Gonnardbfffa902015-05-28 14:44:00 +0200388#if defined(MBEDTLS_FS_IO)
Paul Bakker17373852011-01-06 14:20:01 +0000389/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000390 * \brief This function calculates the message-digest checksum
391 * result of the contents of the provided file.
Paul Bakker17373852011-01-06 14:20:01 +0000392 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000393 * The result is calculated as
394 * Output = message_digest(file contents).
Paul Bakker17373852011-01-06 14:20:01 +0000395 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000396 * \param md_info The information structure of the message-digest algorithm
397 * to use.
398 * \param path The input file name.
399 * \param output The generic message-digest checksum result.
400 *
Rose Zadik8c9c7942018-03-27 11:52:58 +0100401 * \return \c 0 on success.
Rose Zadikf3e47362018-04-16 16:31:16 +0100402 * \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing
403 * the file pointed by \p path.
404 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
Paul Bakker17373852011-01-06 14:20:01 +0000405 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100406MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100407int mbedtls_md_file(const mbedtls_md_info_t *md_info, const char *path,
408 unsigned char *output);
Manuel Pégourié-Gonnardbfffa902015-05-28 14:44:00 +0200409#endif /* MBEDTLS_FS_IO */
Paul Bakker17373852011-01-06 14:20:01 +0000410
411/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000412 * \brief This function sets the HMAC key and prepares to
413 * authenticate a new message.
Paul Bakker17373852011-01-06 14:20:01 +0000414 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000415 * Call this function after mbedtls_md_setup(), to use
416 * the MD context for an HMAC calculation, then call
417 * mbedtls_md_hmac_update() to provide the input data, and
418 * mbedtls_md_hmac_finish() to get the HMAC value.
Paul Bakker17373852011-01-06 14:20:01 +0000419 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000420 * \param ctx The message digest context containing an embedded HMAC
421 * context.
422 * \param key The HMAC secret key.
423 * \param keylen The length of the HMAC key in Bytes.
424 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100425 * \return \c 0 on success.
426 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
427 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000428 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100429MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100430int mbedtls_md_hmac_starts(mbedtls_md_context_t *ctx, const unsigned char *key,
431 size_t keylen);
Paul Bakker17373852011-01-06 14:20:01 +0000432
433/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000434 * \brief This function feeds an input buffer into an ongoing HMAC
435 * computation.
Paul Bakker17373852011-01-06 14:20:01 +0000436 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000437 * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
438 * before calling this function.
439 * You may call this function multiple times to pass the
440 * input piecewise.
441 * Afterwards, call mbedtls_md_hmac_finish().
Paul Bakker17373852011-01-06 14:20:01 +0000442 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000443 * \param ctx The message digest context containing an embedded HMAC
444 * context.
445 * \param input The buffer holding the input data.
446 * \param ilen The length of the input data.
447 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100448 * \return \c 0 on success.
449 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
450 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000451 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100452MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100453int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input,
454 size_t ilen);
Paul Bakker17373852011-01-06 14:20:01 +0000455
456/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000457 * \brief This function finishes the HMAC operation, and writes
458 * the result to the output buffer.
Paul Bakker17373852011-01-06 14:20:01 +0000459 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000460 * Call this function after mbedtls_md_hmac_starts() and
461 * mbedtls_md_hmac_update() to get the HMAC value. Afterwards
462 * you may either call mbedtls_md_free() to clear the context,
463 * or call mbedtls_md_hmac_reset() to reuse the context with
464 * the same HMAC key.
Paul Bakker17373852011-01-06 14:20:01 +0000465 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000466 * \param ctx The message digest context containing an embedded HMAC
467 * context.
468 * \param output The generic HMAC checksum result.
469 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100470 * \return \c 0 on success.
471 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
472 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000473 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100474MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100475int mbedtls_md_hmac_finish(mbedtls_md_context_t *ctx, unsigned char *output);
Paul Bakker17373852011-01-06 14:20:01 +0000476
477/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000478 * \brief This function prepares to authenticate a new message with
479 * the same key as the previous HMAC operation.
Paul Bakker17373852011-01-06 14:20:01 +0000480 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000481 * You may call this function after mbedtls_md_hmac_finish().
482 * Afterwards call mbedtls_md_hmac_update() to pass the new
483 * input.
Paul Bakker17373852011-01-06 14:20:01 +0000484 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000485 * \param ctx The message digest context containing an embedded HMAC
486 * context.
487 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100488 * \return \c 0 on success.
489 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
490 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000491 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100492MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100493int mbedtls_md_hmac_reset(mbedtls_md_context_t *ctx);
Paul Bakker17373852011-01-06 14:20:01 +0000494
495/**
Rose Zadik64feefb2018-01-25 22:01:10 +0000496 * \brief This function calculates the full generic HMAC
497 * on the input buffer with the provided key.
Paul Bakker17373852011-01-06 14:20:01 +0000498 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000499 * The function allocates the context, performs the
500 * calculation, and frees the context.
Paul Bakker17373852011-01-06 14:20:01 +0000501 *
Rose Zadik64feefb2018-01-25 22:01:10 +0000502 * The HMAC result is calculated as
503 * output = generic HMAC(hmac key, input buffer).
504 *
505 * \param md_info The information structure of the message-digest algorithm
506 * to use.
507 * \param key The HMAC secret key.
508 * \param keylen The length of the HMAC secret key in Bytes.
509 * \param input The buffer holding the input data.
510 * \param ilen The length of the input data.
511 * \param output The generic HMAC result.
512 *
Rose Zadikf3e47362018-04-16 16:31:16 +0100513 * \return \c 0 on success.
514 * \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
515 * failure.
Paul Bakker17373852011-01-06 14:20:01 +0000516 */
Gilles Peskineecf6beb2021-12-10 21:35:10 +0100517MBEDTLS_CHECK_RETURN_TYPICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100518int mbedtls_md_hmac(const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
519 const unsigned char *input, size_t ilen,
520 unsigned char *output);
Paul Bakker17373852011-01-06 14:20:01 +0000521
Paul Bakker17373852011-01-06 14:20:01 +0000522#ifdef __cplusplus
523}
524#endif
525
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200526#endif /* MBEDTLS_MD_H */