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
28 #include "mbedtls/private_access.h"
29 
30 #include <stddef.h>
31 
32 #include "mbedtls/build_info.h"
33 #include "mbedtls/platform_util.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
159 extern "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. */
173 typedef 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. */
233 typedef struct mbedtls_md_info_t mbedtls_md_info_t;
234 
240 typedef enum {
244 
248 typedef 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 
323 int 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 
361 unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info);
362 
372 static inline unsigned char mbedtls_md_get_size_from_type(mbedtls_md_type_t md_type)
373 {
375 }
376 
387 
403 
421 int mbedtls_md_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen);
422 
442 int mbedtls_md_finish(mbedtls_md_context_t *ctx, unsigned char *output);
443 
463 int mbedtls_md(const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
464  unsigned char *output);
465 
477 const int *mbedtls_md_list(void);
478 
488 const mbedtls_md_info_t *mbedtls_md_info_from_string(const char *md_name);
489 
499 const 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)
533 int mbedtls_md_file(const mbedtls_md_info_t *md_info, const char *path,
534  unsigned char *output);
535 #endif /* MBEDTLS_FS_IO */
536 
556 int mbedtls_md_hmac_starts(mbedtls_md_context_t *ctx, const unsigned char *key,
557  size_t keylen);
558 
579 int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input,
580  size_t ilen);
581 
601 int mbedtls_md_hmac_finish(mbedtls_md_context_t *ctx, unsigned char *output);
602 
620 
644 int 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.
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...
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.
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.
const int * mbedtls_md_list(void)
This function returns the list of digests supported by the generic digest module.
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.
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
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.
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.
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.
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.
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)