1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
/**
* \file platform_util.h
*
* \brief Common and shared functions used by multiple modules in the Mbed TLS
* library.
*/
/*
* Copyright The Mbed TLS Contributors
* SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
*/
#ifndef MBEDTLS_PLATFORM_UTIL_H
#define MBEDTLS_PLATFORM_UTIL_H
#include "mbedtls/build_info.h"
#include <stddef.h>
#if defined(MBEDTLS_HAVE_TIME_DATE)
#include "mbedtls/platform_time.h"
#include <time.h>
#endif /* MBEDTLS_HAVE_TIME_DATE */
#ifdef __cplusplus
extern "C" {
#endif
/* Internal macros meant to be called only from within the library. */
#define MBEDTLS_INTERNAL_VALIDATE_RET(cond, ret) do { } while (0)
#define MBEDTLS_INTERNAL_VALIDATE(cond) do { } while (0)
/* Internal helper macros for deprecating API constants. */
#if !defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING)
#define MBEDTLS_DEPRECATED __attribute__((deprecated))
MBEDTLS_DEPRECATED typedef char const *mbedtls_deprecated_string_constant_t;
#define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL) \
((mbedtls_deprecated_string_constant_t) (VAL))
MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t;
#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(VAL) \
((mbedtls_deprecated_numeric_constant_t) (VAL))
#else /* MBEDTLS_DEPRECATED_WARNING */
#define MBEDTLS_DEPRECATED
#define MBEDTLS_DEPRECATED_STRING_CONSTANT(VAL) VAL
#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT(VAL) VAL
#endif /* MBEDTLS_DEPRECATED_WARNING */
#endif /* MBEDTLS_DEPRECATED_REMOVED */
/* Implementation of the check-return facility.
* See the user documentation in mbedtls_config.h.
*
* Do not use this macro directly to annotate function: instead,
* use one of MBEDTLS_CHECK_RETURN_CRITICAL or MBEDTLS_CHECK_RETURN_TYPICAL
* depending on how important it is to check the return value.
*/
#if !defined(MBEDTLS_CHECK_RETURN)
#if defined(__GNUC__)
#define MBEDTLS_CHECK_RETURN __attribute__((__warn_unused_result__))
#elif defined(_MSC_VER) && _MSC_VER >= 1700
#include <sal.h>
#define MBEDTLS_CHECK_RETURN _Check_return_
#else
#define MBEDTLS_CHECK_RETURN
#endif
#endif
/** Critical-failure function
*
* This macro appearing at the beginning of the declaration of a function
* indicates that its return value should be checked in all applications.
* Omitting the check is very likely to indicate a bug in the application
* and will result in a compile-time warning if #MBEDTLS_CHECK_RETURN
* is implemented for the compiler in use.
*
* \note The use of this macro is a work in progress.
* This macro may be added to more functions in the future.
* Such an extension is not considered an API break, provided that
* there are near-unavoidable circumstances under which the function
* can fail. For example, signature/MAC/AEAD verification functions,
* and functions that require a random generator, are considered
* return-check-critical.
*/
#define MBEDTLS_CHECK_RETURN_CRITICAL MBEDTLS_CHECK_RETURN
/** Ordinary-failure function
*
* This macro appearing at the beginning of the declaration of a function
* indicates that its return value should be generally be checked in portable
* applications. Omitting the check will result in a compile-time warning if
* #MBEDTLS_CHECK_RETURN is implemented for the compiler in use and
* #MBEDTLS_CHECK_RETURN_WARNING is enabled in the compile-time configuration.
*
* You can use #MBEDTLS_IGNORE_RETURN to explicitly ignore the return value
* of a function that is annotated with #MBEDTLS_CHECK_RETURN.
*
* \note The use of this macro is a work in progress.
* This macro will be added to more functions in the future.
* Eventually this should appear before most functions returning
* an error code (as \c int in the \c mbedtls_xxx API or
* as ::psa_status_t in the \c psa_xxx API).
*/
#if defined(MBEDTLS_CHECK_RETURN_WARNING)
#define MBEDTLS_CHECK_RETURN_TYPICAL MBEDTLS_CHECK_RETURN
#else
#define MBEDTLS_CHECK_RETURN_TYPICAL
#endif
/** Benign-failure function
*
* This macro appearing at the beginning of the declaration of a function
* indicates that it is rarely useful to check its return value.
*
* This macro has an empty expansion. It exists for documentation purposes:
* a #MBEDTLS_CHECK_RETURN_OPTIONAL annotation indicates that the function
* has been analyzed for return-check usefulness, whereas the lack of
* an annotation indicates that the function has not been analyzed and its
* return-check usefulness is unknown.
*/
#define MBEDTLS_CHECK_RETURN_OPTIONAL
/** \def MBEDTLS_IGNORE_RETURN
*
* Call this macro with one argument, a function call, to suppress a warning
* from #MBEDTLS_CHECK_RETURN due to that function call.
*/
#if !defined(MBEDTLS_IGNORE_RETURN)
/* GCC doesn't silence the warning with just (void)(result).
* (void)!(result) is known to work up at least up to GCC 10, as well
* as with Clang and MSVC.
*
* https://gcc.gnu.org/onlinedocs/gcc-3.4.6/gcc/Non_002dbugs.html
* https://stackoverflow.com/questions/40576003/ignoring-warning-wunused-result
* https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66425#c34
*/
#define MBEDTLS_IGNORE_RETURN(result) ((void) !(result))
#endif
/* If the following macro is defined, the library is being built by the test
* framework, and the framework is going to provide a replacement
* mbedtls_platform_zeroize() using a preprocessor macro, so the function
* declaration should be omitted. */
#if !defined(MBEDTLS_TEST_DEFINES_ZEROIZE) //no-check-names
/**
* \brief Securely zeroize a buffer
*
* The function is meant to wipe the data contained in a buffer so
* that it can no longer be recovered even if the program memory
* is later compromised. Call this function on sensitive data
* stored on the stack before returning from a function, and on
* sensitive data stored on the heap before freeing the heap
* object.
*
* It is extremely difficult to guarantee that calls to
* mbedtls_platform_zeroize() are not removed by aggressive
* compiler optimizations in a portable way. For this reason, Mbed
* TLS provides the configuration option
* MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure
* mbedtls_platform_zeroize() to use a suitable implementation for
* their platform and needs
*
* \param buf Buffer to be zeroized
* \param len Length of the buffer in bytes
*
*/
void mbedtls_platform_zeroize(void *buf, size_t len);
#endif
#if defined(MBEDTLS_HAVE_TIME_DATE)
/**
* \brief Platform-specific implementation of gmtime_r()
*
* The function is a thread-safe abstraction that behaves
* similarly to the gmtime_r() function from Unix/POSIX.
*
* Mbed TLS will try to identify the underlying platform and
* make use of an appropriate underlying implementation (e.g.
* gmtime_r() for POSIX and gmtime_s() for Windows). If this is
* not possible, then gmtime() will be used. In this case, calls
* from the library to gmtime() will be guarded by the mutex
* mbedtls_threading_gmtime_mutex if MBEDTLS_THREADING_C is
* enabled. It is recommended that calls from outside the library
* are also guarded by this mutex.
*
* If MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, then Mbed TLS will
* unconditionally use the alternative implementation for
* mbedtls_platform_gmtime_r() supplied by the user at compile time.
*
* \param tt Pointer to an object containing time (in seconds) since the
* epoch to be converted
* \param tm_buf Pointer to an object where the results will be stored
*
* \return Pointer to an object of type struct tm on success, otherwise
* NULL
*/
struct tm *mbedtls_platform_gmtime_r(const mbedtls_time_t *tt,
struct tm *tm_buf);
#endif /* MBEDTLS_HAVE_TIME_DATE */
#ifdef __cplusplus
}
#endif
#endif /* MBEDTLS_PLATFORM_UTIL_H */
|
