mbed TLS v3.4.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 #endif /* MBEDTLS_PSA_CRYPTO_C */
89 
90 /* Built-in implementations */
91 #if defined(MBEDTLS_MD5_C)
92 #define MBEDTLS_MD_CAN_MD5
93 #define MBEDTLS_MD_SOME_LEGACY
94 #endif
95 #if defined(MBEDTLS_SHA1_C)
96 #define MBEDTLS_MD_CAN_SHA1
97 #define MBEDTLS_MD_SOME_LEGACY
98 #endif
99 #if defined(MBEDTLS_SHA224_C)
100 #define MBEDTLS_MD_CAN_SHA224
101 #define MBEDTLS_MD_SOME_LEGACY
102 #endif
103 #if defined(MBEDTLS_SHA256_C)
104 #define MBEDTLS_MD_CAN_SHA256
105 #define MBEDTLS_MD_SOME_LEGACY
106 #endif
107 #if defined(MBEDTLS_SHA384_C)
108 #define MBEDTLS_MD_CAN_SHA384
109 #define MBEDTLS_MD_SOME_LEGACY
110 #endif
111 #if defined(MBEDTLS_SHA512_C)
112 #define MBEDTLS_MD_CAN_SHA512
113 #define MBEDTLS_MD_SOME_LEGACY
114 #endif
115 #if defined(MBEDTLS_RIPEMD160_C)
116 #define MBEDTLS_MD_CAN_RIPEMD160
117 #define MBEDTLS_MD_SOME_LEGACY
118 #endif
119 
120 #endif /* MBEDTLS_MD_LIGHT */
121 
123 #define MBEDTLS_ERR_MD_FEATURE_UNAVAILABLE -0x5080
124 
125 #define MBEDTLS_ERR_MD_BAD_INPUT_DATA -0x5100
126 
127 #define MBEDTLS_ERR_MD_ALLOC_FAILED -0x5180
128 
129 #define MBEDTLS_ERR_MD_FILE_IO_ERROR -0x5200
130 
131 #ifdef __cplusplus
132 extern "C" {
133 #endif
134 
143 typedef enum {
153 
154 #if defined(MBEDTLS_MD_CAN_SHA512)
155 #define MBEDTLS_MD_MAX_SIZE 64 /* longest known is SHA512 */
156 #elif defined(MBEDTLS_MD_CAN_SHA384)
157 #define MBEDTLS_MD_MAX_SIZE 48 /* longest known is SHA384 */
158 #elif defined(MBEDTLS_MD_CAN_SHA256)
159 #define MBEDTLS_MD_MAX_SIZE 32 /* longest known is SHA256 */
160 #elif defined(MBEDTLS_MD_CAN_SHA224)
161 #define MBEDTLS_MD_MAX_SIZE 28 /* longest known is SHA224 */
162 #else
163 #define MBEDTLS_MD_MAX_SIZE 20 /* longest known is SHA1 or RIPE MD-160
164  or smaller (MD5 and earlier) */
165 #endif
166 
167 #if defined(MBEDTLS_MD_CAN_SHA512)
168 #define MBEDTLS_MD_MAX_BLOCK_SIZE 128
169 #else
170 #define MBEDTLS_MD_MAX_BLOCK_SIZE 64
171 #endif
172 
182 /* Defined internally in library/md_wrap.h. */
184 
190 typedef enum {
194 
198 typedef struct mbedtls_md_context_t {
201 
202 #if defined(MBEDTLS_MD_SOME_PSA)
203 
205 #endif
206 
208  void *MBEDTLS_PRIVATE(md_ctx);
209 
210 #if defined(MBEDTLS_MD_C)
211 
212  void *MBEDTLS_PRIVATE(hmac_ctx);
213 #endif
215 
226 
236 
251 
252 
273 int mbedtls_md_setup(mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac);
274 
300  const mbedtls_md_context_t *src);
301 
311 unsigned char mbedtls_md_get_size(const mbedtls_md_info_t *md_info);
312 
323 
339 
357 int mbedtls_md_update(mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen);
358 
378 int mbedtls_md_finish(mbedtls_md_context_t *ctx, unsigned char *output);
379 
399 int mbedtls_md(const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
400  unsigned char *output);
401 
413 const int *mbedtls_md_list(void);
414 
424 const mbedtls_md_info_t *mbedtls_md_info_from_string(const char *md_name);
425 
435 const char *mbedtls_md_get_name(const mbedtls_md_info_t *md_info);
436 
448  const mbedtls_md_context_t *ctx);
449 
450 #if defined(MBEDTLS_FS_IO)
451 
469 int mbedtls_md_file(const mbedtls_md_info_t *md_info, const char *path,
470  unsigned char *output);
471 #endif /* MBEDTLS_FS_IO */
472 
492 int mbedtls_md_hmac_starts(mbedtls_md_context_t *ctx, const unsigned char *key,
493  size_t keylen);
494 
515 int mbedtls_md_hmac_update(mbedtls_md_context_t *ctx, const unsigned char *input,
516  size_t ilen);
517 
537 int mbedtls_md_hmac_finish(mbedtls_md_context_t *ctx, unsigned char *output);
538 
556 
580 int mbedtls_md_hmac(const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
581  const unsigned char *input, size_t ilen,
582  unsigned char *output);
583 
584 #ifdef __cplusplus
585 }
586 #endif
587 
588 #endif /* MBEDTLS_MD_H */
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...
MBEDTLS_CHECK_RETURN_TYPICAL int mbedtls_md_starts(mbedtls_md_context_t *ctx)
This function starts a message-digest computation.
#define MBEDTLS_CHECK_RETURN_TYPICAL
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.
mbedtls_md_engine_t
Definition: md.h:190
MBEDTLS_CHECK_RETURN_TYPICAL 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.
void mbedtls_md_free(mbedtls_md_context_t *ctx)
This function clears the internal structure of ctx and frees any embedded internal structure...
void mbedtls_md_init(mbedtls_md_context_t *ctx)
This function initializes a message-digest context without binding it to a particular message-digest ...
#define MBEDTLS_PRIVATE(member)
MBEDTLS_CHECK_RETURN_TYPICAL 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.
MBEDTLS_CHECK_RETURN_TYPICAL 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...
Common and shared functions used by multiple modules in the Mbed TLS library.
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...
MBEDTLS_CHECK_RETURN_TYPICAL 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...
MBEDTLS_CHECK_RETURN_TYPICAL 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.
MBEDTLS_CHECK_RETURN_TYPICAL 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...
MBEDTLS_CHECK_RETURN_TYPICAL 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.
Macro wrapper for struct's members.
const char * mbedtls_md_get_name(const mbedtls_md_info_t *md_info)
This function extracts the message-digest name from the message-digest information structure...
struct mbedtls_md_context_t mbedtls_md_context_t
Build-time configuration info.
const int * mbedtls_md_list(void)
This function returns the list of digests supported by the generic digest module. ...
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...
MBEDTLS_CHECK_RETURN_TYPICAL 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.
MBEDTLS_CHECK_RETURN_TYPICAL 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...
MBEDTLS_CHECK_RETURN_TYPICAL 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.
struct mbedtls_md_info_t mbedtls_md_info_t
Definition: md.h:183
mbedtls_md_type_t
Supported message digests.
Definition: md.h:143
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...
MBEDTLS_CHECK_RETURN_TYPICAL 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...