Mbed TLS v3.5.0
md.h
Go to the documentation of this file.
1
9/*
10 * Copyright The Mbed TLS Contributors
11 * SPDX-License-Identifier: Apache-2.0
12 *
13 * Licensed under the Apache License, Version 2.0 (the "License"); you may
14 * not use this file except in compliance with the License.
15 * You may obtain a copy of the License at
16 *
17 * http://www.apache.org/licenses/LICENSE-2.0
18 *
19 * Unless required by applicable law or agreed to in writing, software
20 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
21 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22 * See the License for the specific language governing permissions and
23 * limitations under the License.
24 */
25
26#ifndef MBEDTLS_MD_H
27#define MBEDTLS_MD_H
29
30#include <stddef.h>
31
32#include "mbedtls/build_info.h"
34
35#if defined(MBEDTLS_MD_LIGHT)
36
37/*
38 * - MBEDTLS_MD_CAN_xxx is defined if the md module can perform xxx.
39 * - MBEDTLS_MD_xxx_VIA_PSA is defined if the md module may perform xxx via PSA
40 * (see below).
41 * - MBEDTLS_MD_SOME_PSA is defined if at least one algorithm may be performed
42 * via PSA (see below).
43 * - MBEDTLS_MD_SOME_LEGACY is defined if at least one algorithm may be performed
44 * via a direct legacy call (see below).
45 *
46 * The md module performs an algorithm via PSA if there is a PSA hash
47 * accelerator and the PSA driver subsytem is initialized at the time the
48 * operation is started, and makes a direct legacy call otherwise.
49 */
50
51/* PSA accelerated implementations */
52#if defined(MBEDTLS_PSA_CRYPTO_C)
53#if defined(MBEDTLS_PSA_ACCEL_ALG_MD5)
54#define MBEDTLS_MD_CAN_MD5
55#define MBEDTLS_MD_MD5_VIA_PSA
56#define MBEDTLS_MD_SOME_PSA
57#endif
58#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_1)
59#define MBEDTLS_MD_CAN_SHA1
60#define MBEDTLS_MD_SHA1_VIA_PSA
61#define MBEDTLS_MD_SOME_PSA
62#endif
63#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_224)
64#define MBEDTLS_MD_CAN_SHA224
65#define MBEDTLS_MD_SHA224_VIA_PSA
66#define MBEDTLS_MD_SOME_PSA
67#endif
68#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_256)
69#define MBEDTLS_MD_CAN_SHA256
70#define MBEDTLS_MD_SHA256_VIA_PSA
71#define MBEDTLS_MD_SOME_PSA
72#endif
73#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_384)
74#define MBEDTLS_MD_CAN_SHA384
75#define MBEDTLS_MD_SHA384_VIA_PSA
76#define MBEDTLS_MD_SOME_PSA
77#endif
78#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA_512)
79#define MBEDTLS_MD_CAN_SHA512
80#define MBEDTLS_MD_SHA512_VIA_PSA
81#define MBEDTLS_MD_SOME_PSA
82#endif
83#if defined(MBEDTLS_PSA_ACCEL_ALG_RIPEMD160)
84#define MBEDTLS_MD_CAN_RIPEMD160
85#define MBEDTLS_MD_RIPEMD160_VIA_PSA
86#define MBEDTLS_MD_SOME_PSA
87#endif
88#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_224)
89#define MBEDTLS_MD_CAN_SHA3_224
90#define MBEDTLS_MD_SHA3_224_VIA_PSA
91#define MBEDTLS_MD_SOME_PSA
92#endif
93#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_256)
94#define MBEDTLS_MD_CAN_SHA3_256
95#define MBEDTLS_MD_SHA3_256_VIA_PSA
96#define MBEDTLS_MD_SOME_PSA
97#endif
98#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_384)
99#define MBEDTLS_MD_CAN_SHA3_384
100#define MBEDTLS_MD_SHA3_384_VIA_PSA
101#define MBEDTLS_MD_SOME_PSA
102#endif
103#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_512)
104#define MBEDTLS_MD_CAN_SHA3_512
105#define MBEDTLS_MD_SHA3_512_VIA_PSA
106#define MBEDTLS_MD_SOME_PSA
107#endif
108#endif /* MBEDTLS_PSA_CRYPTO_C */
109
110/* Built-in implementations */
111#if defined(MBEDTLS_MD5_C)
112#define MBEDTLS_MD_CAN_MD5
113#define MBEDTLS_MD_SOME_LEGACY
114#endif
115#if defined(MBEDTLS_SHA1_C)
116#define MBEDTLS_MD_CAN_SHA1
117#define MBEDTLS_MD_SOME_LEGACY
118#endif
119#if defined(MBEDTLS_SHA224_C)
120#define MBEDTLS_MD_CAN_SHA224
121#define MBEDTLS_MD_SOME_LEGACY
122#endif
123#if defined(MBEDTLS_SHA256_C)
124#define MBEDTLS_MD_CAN_SHA256
125#define MBEDTLS_MD_SOME_LEGACY
126#endif
127#if defined(MBEDTLS_SHA384_C)
128#define MBEDTLS_MD_CAN_SHA384
129#define MBEDTLS_MD_SOME_LEGACY
130#endif
131#if defined(MBEDTLS_SHA512_C)
132#define MBEDTLS_MD_CAN_SHA512
133#define MBEDTLS_MD_SOME_LEGACY
134#endif
135#if defined(MBEDTLS_SHA3_C)
136#define MBEDTLS_MD_CAN_SHA3_224
137#define MBEDTLS_MD_CAN_SHA3_256
138#define MBEDTLS_MD_CAN_SHA3_384
139#define MBEDTLS_MD_CAN_SHA3_512
140#define MBEDTLS_MD_SOME_LEGACY
141#endif
142#if defined(MBEDTLS_RIPEMD160_C)
143#define MBEDTLS_MD_CAN_RIPEMD160
144#define MBEDTLS_MD_SOME_LEGACY
145#endif
146
147#endif /* MBEDTLS_MD_LIGHT */
148
150#define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080
152#define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100
154#define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180
156#define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200
157
158#ifdef __cplusplus
159extern "C" {
160#endif
161
170/* Note: these are aligned with the definitions of PSA_ALG_ macros for hashes,
171 * in order to enable an efficient implementation of conversion functions.
172 * This is tested by md_to_from_psa() in test_suite_md. */
173typedef enum {
187
188/* Note: this should always be >= PSA_HASH_MAX_SIZE
189 * in all builds with both CRYPTO_C and MD_LIGHT.
190 *
191 * This is to make things easier for modules such as TLS that may define a
192 * buffer size using MD_MAX_SIZE in a part of the code that's common to PSA
193 * and legacy, then assume the buffer's size is PSA_HASH_MAX_SIZE in another
194 * part of the code based on PSA.
195 */
196#if defined(MBEDTLS_MD_CAN_SHA512) || defined(MBEDTLS_MD_CAN_SHA3_512)
197#define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */
198#elif defined(MBEDTLS_MD_CAN_SHA384) || defined(MBEDTLS_MD_CAN_SHA3_384)
199#define MBEDTLS_MD_MAX_SIZE 48 /* longest known is SHA384 */
200#elif defined(MBEDTLS_MD_CAN_SHA256) || defined(MBEDTLS_MD_CAN_SHA3_256)
201#define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 */
202#elif defined(MBEDTLS_MD_CAN_SHA224) || defined(MBEDTLS_MD_CAN_SHA3_224)
203#define MBEDTLS_MD_MAX_SIZE 28 /* longest known is SHA224 */
204#else
205#define MBEDTLS_MD_MAX_SIZE 20 /* longest known is SHA1 or RIPE MD-160
206 or smaller (MD5 and earlier) */
207#endif
208
209#if defined(MBEDTLS_MD_CAN_SHA3_224)
210#define MBEDTLS_MD_MAX_BLOCK_SIZE 144 /* the longest known is SHA3-224 */
211#elif defined(MBEDTLS_MD_CAN_SHA3_256)
212#define MBEDTLS_MD_MAX_BLOCK_SIZE 136
213#elif defined(MBEDTLS_MD_CAN_SHA512) || defined(MBEDTLS_MD_CAN_SHA384)
214#define MBEDTLS_MD_MAX_BLOCK_SIZE 128
215#elif defined(MBEDTLS_MD_CAN_SHA3_384)
216#define MBEDTLS_MD_MAX_BLOCK_SIZE 104
217#elif defined(MBEDTLS_MD_CAN_SHA3_512)
218#define MBEDTLS_MD_MAX_BLOCK_SIZE 72
219#else
220#define MBEDTLS_MD_MAX_BLOCK_SIZE 64
221#endif
222
232/* Defined internally in library/md_wrap.h. */
234
240typedef enum {
244
248typedef struct mbedtls_md_context_t {
251
252#if defined(MBEDTLS_MD_SOME_PSA)
255#endif
256
258 void *MBEDTLS_PRIVATE(md_ctx);
259
260#if defined(MBEDTLS_MD_C)
262 void *MBEDTLS_PRIVATE(hmac_ctx);
263#endif
265
276
286
301
302
323int mbedtls_md_setup(mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac);
324
350 const mbedtls_md_context_t *src);
351
361unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info);
362
372static inline unsigned char mbedtls_md_get_size_from_type(mbedtls_md_type_t md_type)
373{
375}
376
387
403
421int mbedtls_md_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen);
422
442int mbedtls_md_finish(mbedtls_md_context_t *ctx, unsigned char *output);
443
463int mbedtls_md(const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
464 unsigned char *output);
465
477const int *mbedtls_md_list(void);
478
489
499const char *mbedtls_md_get_name(const mbedtls_md_info_t *md_info);
500
512 const mbedtls_md_context_t *ctx);
513
514#if defined(MBEDTLS_FS_IO)
533int mbedtls_md_file(const mbedtls_md_info_t *md_info, const char *path,
534 unsigned char *output);
535#endif /* MBEDTLS_FS_IO */
536
556int mbedtls_md_hmac_starts(mbedtls_md_context_t *ctx, const unsigned char *key,
557 size_t keylen);
558
579int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input,
580 size_t ilen);
581
601int mbedtls_md_hmac_finish(mbedtls_md_context_t *ctx, unsigned char *output);
602
620
644int mbedtls_md_hmac(const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
645 const unsigned char *input, size_t ilen,
646 unsigned char *output);
647
648#ifdef __cplusplus
649}
650#endif
651
652#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:173
@ MBEDTLS_MD_SHA512
Definition: md.h:181
@ MBEDTLS_MD_MD5
Definition: md.h:175
@ MBEDTLS_MD_RIPEMD160
Definition: md.h:176
@ MBEDTLS_MD_SHA384
Definition: md.h:180
@ MBEDTLS_MD_SHA3_384
Definition: md.h:184
@ MBEDTLS_MD_NONE
Definition: md.h:174
@ MBEDTLS_MD_SHA3_512
Definition: md.h:185
@ MBEDTLS_MD_SHA256
Definition: md.h:179
@ MBEDTLS_MD_SHA224
Definition: md.h:178
@ MBEDTLS_MD_SHA1
Definition: md.h:177
@ MBEDTLS_MD_SHA3_224
Definition: md.h:182
@ MBEDTLS_MD_SHA3_256
Definition: md.h:183
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:233
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:372
mbedtls_md_engine_t
Definition: md.h:240
@ MBEDTLS_MD_ENGINE_LEGACY
Definition: md.h:241
@ MBEDTLS_MD_ENGINE_PSA
Definition: md.h:242
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)