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