Mbed TLS v3.5.2
Loading...
Searching...
No Matches
md.h
Go to the documentation of this file.
1
9/*
10 * Copyright The Mbed TLS Contributors
11 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
12 */
13
14#ifndef MBEDTLS_MD_H
15#define MBEDTLS_MD_H
17
18#include <stddef.h>
19
20#include "mbedtls/build_info.h"
22
23#if defined(MBEDTLS_MD_LIGHT)
24
25/*
26 * - MBEDTLS_MD_CAN_xxx is defined if the md module can perform xxx.
27 * - MBEDTLS_MD_xxx_VIA_PSA is defined if the md module may perform xxx via PSA
28 * (see below).
29 * - MBEDTLS_MD_SOME_PSA is defined if at least one algorithm may be performed
30 * via PSA (see below).
31 * - MBEDTLS_MD_SOME_LEGACY is defined if at least one algorithm may be performed
32 * via a direct legacy call (see below).
33 *
34 * The md module performs an algorithm via PSA if there is a PSA hash
35 * accelerator and the PSA driver subsytem is initialized at the time the
36 * operation is started, and makes a direct legacy call otherwise.
37 */
38
39/* PSA accelerated implementations */
40#if defined(MBEDTLS_PSA_CRYPTO_C)
41#if defined(MBEDTLS_PSA_ACCEL_ALG_MD5)
42#define MBEDTLS_MD_CAN_MD5
43#define MBEDTLS_MD_MD5_VIA_PSA
44#define MBEDTLS_MD_SOME_PSA
45#endif
46#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_1)
47#define MBEDTLS_MD_CAN_SHA1
48#define MBEDTLS_MD_SHA1_VIA_PSA
49#define MBEDTLS_MD_SOME_PSA
50#endif
51#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_224)
52#define MBEDTLS_MD_CAN_SHA224
53#define MBEDTLS_MD_SHA224_VIA_PSA
54#define MBEDTLS_MD_SOME_PSA
55#endif
56#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_256)
57#define MBEDTLS_MD_CAN_SHA256
58#define MBEDTLS_MD_SHA256_VIA_PSA
59#define MBEDTLS_MD_SOME_PSA
60#endif
61#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_384)
62#define MBEDTLS_MD_CAN_SHA384
63#define MBEDTLS_MD_SHA384_VIA_PSA
64#define MBEDTLS_MD_SOME_PSA
65#endif
66#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_512)
67#define MBEDTLS_MD_CAN_SHA512
68#define MBEDTLS_MD_SHA512_VIA_PSA
69#define MBEDTLS_MD_SOME_PSA
70#endif
71#if defined(MBEDTLS_PSA_ACCEL_ALG_RIPEMD160)
72#define MBEDTLS_MD_CAN_RIPEMD160
73#define MBEDTLS_MD_RIPEMD160_VIA_PSA
74#define MBEDTLS_MD_SOME_PSA
75#endif
76#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_224)
77#define MBEDTLS_MD_CAN_SHA3_224
78#define MBEDTLS_MD_SHA3_224_VIA_PSA
79#define MBEDTLS_MD_SOME_PSA
80#endif
81#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_256)
82#define MBEDTLS_MD_CAN_SHA3_256
83#define MBEDTLS_MD_SHA3_256_VIA_PSA
84#define MBEDTLS_MD_SOME_PSA
85#endif
86#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_384)
87#define MBEDTLS_MD_CAN_SHA3_384
88#define MBEDTLS_MD_SHA3_384_VIA_PSA
89#define MBEDTLS_MD_SOME_PSA
90#endif
91#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_512)
92#define MBEDTLS_MD_CAN_SHA3_512
93#define MBEDTLS_MD_SHA3_512_VIA_PSA
94#define MBEDTLS_MD_SOME_PSA
95#endif
96#endif /* MBEDTLS_PSA_CRYPTO_C */
97
98/* Built-in implementations */
99#if defined(MBEDTLS_MD5_C)
100#define MBEDTLS_MD_CAN_MD5
101#define MBEDTLS_MD_SOME_LEGACY
102#endif
103#if defined(MBEDTLS_SHA1_C)
104#define MBEDTLS_MD_CAN_SHA1
105#define MBEDTLS_MD_SOME_LEGACY
106#endif
107#if defined(MBEDTLS_SHA224_C)
108#define MBEDTLS_MD_CAN_SHA224
109#define MBEDTLS_MD_SOME_LEGACY
110#endif
111#if defined(MBEDTLS_SHA256_C)
112#define MBEDTLS_MD_CAN_SHA256
113#define MBEDTLS_MD_SOME_LEGACY
114#endif
115#if defined(MBEDTLS_SHA384_C)
116#define MBEDTLS_MD_CAN_SHA384
117#define MBEDTLS_MD_SOME_LEGACY
118#endif
119#if defined(MBEDTLS_SHA512_C)
120#define MBEDTLS_MD_CAN_SHA512
121#define MBEDTLS_MD_SOME_LEGACY
122#endif
123#if defined(MBEDTLS_SHA3_C)
124#define MBEDTLS_MD_CAN_SHA3_224
125#define MBEDTLS_MD_CAN_SHA3_256
126#define MBEDTLS_MD_CAN_SHA3_384
127#define MBEDTLS_MD_CAN_SHA3_512
128#define MBEDTLS_MD_SOME_LEGACY
129#endif
130#if defined(MBEDTLS_RIPEMD160_C)
131#define MBEDTLS_MD_CAN_RIPEMD160
132#define MBEDTLS_MD_SOME_LEGACY
133#endif
134
135#endif /* MBEDTLS_MD_LIGHT */
136
138#define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080
140#define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100
142#define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180
144#define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200
145
146#ifdef __cplusplus
147extern "C" {
148#endif
149
158/* Note: these are aligned with the definitions of PSA_ALG_ macros for hashes,
159 * in order to enable an efficient implementation of conversion functions.
160 * This is tested by md_to_from_psa() in test_suite_md. */
175
176/* Note: this should always be >= PSA_HASH_MAX_SIZE
177 * in all builds with both CRYPTO_C and MD_LIGHT.
178 *
179 * This is to make things easier for modules such as TLS that may define a
180 * buffer size using MD_MAX_SIZE in a part of the code that's common to PSA
181 * and legacy, then assume the buffer's size is PSA_HASH_MAX_SIZE in another
182 * part of the code based on PSA.
183 */
184#if defined(MBEDTLS_MD_CAN_SHA512) || defined(MBEDTLS_MD_CAN_SHA3_512)
185#define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */
186#elif defined(MBEDTLS_MD_CAN_SHA384) || defined(MBEDTLS_MD_CAN_SHA3_384)
187#define MBEDTLS_MD_MAX_SIZE 48 /* longest known is SHA384 */
188#elif defined(MBEDTLS_MD_CAN_SHA256) || defined(MBEDTLS_MD_CAN_SHA3_256)
189#define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 */
190#elif defined(MBEDTLS_MD_CAN_SHA224) || defined(MBEDTLS_MD_CAN_SHA3_224)
191#define MBEDTLS_MD_MAX_SIZE 28 /* longest known is SHA224 */
192#else
193#define MBEDTLS_MD_MAX_SIZE 20 /* longest known is SHA1 or RIPE MD-160
194 or smaller (MD5 and earlier) */
195#endif
196
197#if defined(MBEDTLS_MD_CAN_SHA3_224)
198#define MBEDTLS_MD_MAX_BLOCK_SIZE 144 /* the longest known is SHA3-224 */
199#elif defined(MBEDTLS_MD_CAN_SHA3_256)
200#define MBEDTLS_MD_MAX_BLOCK_SIZE 136
201#elif defined(MBEDTLS_MD_CAN_SHA512) || defined(MBEDTLS_MD_CAN_SHA384)
202#define MBEDTLS_MD_MAX_BLOCK_SIZE 128
203#elif defined(MBEDTLS_MD_CAN_SHA3_384)
204#define MBEDTLS_MD_MAX_BLOCK_SIZE 104
205#elif defined(MBEDTLS_MD_CAN_SHA3_512)
206#define MBEDTLS_MD_MAX_BLOCK_SIZE 72
207#else
208#define MBEDTLS_MD_MAX_BLOCK_SIZE 64
209#endif
210
220/* Defined internally in library/md_wrap.h. */
222
232
236typedef struct mbedtls_md_context_t {
239
240#if defined(MBEDTLS_MD_SOME_PSA)
243#endif
244
246 void *MBEDTLS_PRIVATE(md_ctx);
247
248#if defined(MBEDTLS_MD_C)
250 void *MBEDTLS_PRIVATE(hmac_ctx);
251#endif
253
264
274
289
290
311int mbedtls_md_setup(mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac);
312
338 const mbedtls_md_context_t *src);
339
349unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info);
350
360static inline unsigned char mbedtls_md_get_size_from_type(mbedtls_md_type_t md_type)
361{
363}
364
375
391
409int mbedtls_md_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen);
410
430int mbedtls_md_finish(mbedtls_md_context_t *ctx, unsigned char *output);
431
451int mbedtls_md(const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
452 unsigned char *output);
453
465const int *mbedtls_md_list(void);
466
477
487const char *mbedtls_md_get_name(const mbedtls_md_info_t *md_info);
488
500 const mbedtls_md_context_t *ctx);
501
502#if defined(MBEDTLS_FS_IO)
521int mbedtls_md_file(const mbedtls_md_info_t *md_info, const char *path,
522 unsigned char *output);
523#endif /* MBEDTLS_FS_IO */
524
544int mbedtls_md_hmac_starts(mbedtls_md_context_t *ctx, const unsigned char *key,
545 size_t keylen);
546
567int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input,
568 size_t ilen);
569
589int mbedtls_md_hmac_finish(mbedtls_md_context_t *ctx, unsigned char *output);
590
608
632int mbedtls_md_hmac(const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
633 const unsigned char *input, size_t ilen,
634 unsigned char *output);
635
636#ifdef __cplusplus
637}
638#endif
639
640#endif /* MBEDTLS_MD_H */
Build-time configuration info.
const int * mbedtls_md_list(void)
This function returns the list of digests supported by the generic digest module.
int mbedtls_md_setup(mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac)
This function selects the message digest algorithm to use, and allocates internal structures.
mbedtls_md_type_t
Supported message digests.
Definition md.h:161
@ MBEDTLS_MD_SHA512
Definition md.h:169
@ MBEDTLS_MD_MD5
Definition md.h:163
@ MBEDTLS_MD_RIPEMD160
Definition md.h:164
@ MBEDTLS_MD_SHA384
Definition md.h:168
@ MBEDTLS_MD_SHA3_384
Definition md.h:172
@ MBEDTLS_MD_NONE
Definition md.h:162
@ MBEDTLS_MD_SHA3_512
Definition md.h:173
@ MBEDTLS_MD_SHA256
Definition md.h:167
@ MBEDTLS_MD_SHA224
Definition md.h:166
@ MBEDTLS_MD_SHA1
Definition md.h:165
@ MBEDTLS_MD_SHA3_224
Definition md.h:170
@ MBEDTLS_MD_SHA3_256
Definition md.h:171
int mbedtls_md_starts(mbedtls_md_context_t *ctx)
This function starts a message-digest computation.
int mbedtls_md_hmac(const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, const unsigned char *input, size_t ilen, unsigned char *output)
This function calculates the full generic HMAC on the input buffer with the provided key.
int mbedtls_md(const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, unsigned char *output)
This function calculates the message-digest of a buffer, with respect to a configurable message-diges...
int mbedtls_md_hmac_reset(mbedtls_md_context_t *ctx)
This function prepares to authenticate a new message with the same key as the previous HMAC operation...
const char * mbedtls_md_get_name(const mbedtls_md_info_t *md_info)
This function returns the name of the message digest for the message-digest information structure giv...
struct mbedtls_md_info_t mbedtls_md_info_t
Definition md.h:221
int mbedtls_md_clone(mbedtls_md_context_t *dst, const mbedtls_md_context_t *src)
This function clones the state of a message-digest context.
struct mbedtls_md_context_t mbedtls_md_context_t
mbedtls_md_type_t mbedtls_md_get_type(const mbedtls_md_info_t *md_info)
This function extracts the message-digest type from the message-digest information structure.
int mbedtls_md_hmac_finish(mbedtls_md_context_t *ctx, unsigned char *output)
This function finishes the HMAC operation, and writes the result to the output buffer.
int mbedtls_md_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen)
This function feeds an input buffer into an ongoing message-digest computation.
int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen)
This function feeds an input buffer into an ongoing HMAC computation.
int mbedtls_md_hmac_starts(mbedtls_md_context_t *ctx, const unsigned char *key, size_t keylen)
This function sets the HMAC key and prepares to authenticate a new message.
const mbedtls_md_info_t * mbedtls_md_info_from_type(mbedtls_md_type_t md_type)
This function returns the message-digest information associated with the given digest type.
static unsigned char mbedtls_md_get_size_from_type(mbedtls_md_type_t md_type)
This function gives the message-digest size associated to message-digest type.
Definition md.h:360
mbedtls_md_engine_t
Definition md.h:228
@ MBEDTLS_MD_ENGINE_LEGACY
Definition md.h:229
@ MBEDTLS_MD_ENGINE_PSA
Definition md.h:230
int mbedtls_md_file(const mbedtls_md_info_t *md_info, const char *path, unsigned char *output)
This function calculates the message-digest checksum result of the contents of the provided file.
void mbedtls_md_init(mbedtls_md_context_t *ctx)
This function initializes a message-digest context without binding it to a particular message-digest ...
int mbedtls_md_finish(mbedtls_md_context_t *ctx, unsigned char *output)
This function finishes the digest operation, and writes the result to the output buffer.
const mbedtls_md_info_t * mbedtls_md_info_from_string(const char *md_name)
This function returns the message-digest information associated with the given digest name.
unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info)
This function extracts the message-digest size from the message-digest information structure.
const mbedtls_md_info_t * mbedtls_md_info_from_ctx(const mbedtls_md_context_t *ctx)
This function returns the message-digest information from the given context.
void mbedtls_md_free(mbedtls_md_context_t *ctx)
This function clears the internal structure of ctx and frees any embedded internal structure,...
Common and shared functions used by multiple modules in the Mbed TLS library.
#define MBEDTLS_CHECK_RETURN_TYPICAL
Macro wrapper for struct's members.
#define MBEDTLS_PRIVATE(member)