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