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 /** \brief The type of custom random generator (RNG) callbacks. 163 * 164 * Many Mbed TLS functions take two parameters 165 * `mbedtls_f_rng_t *f_rng, void *p_rng`. The 166 * library will call \c f_rng to generate 167 * random values. 168 * 169 * \note This is typically one of the following: 170 * - mbedtls_ctr_drbg_random() with \c p_rng 171 * pointing to a #mbedtls_ctr_drbg_context; 172 * - mbedtls_hmac_drbg_random() with \c p_rng 173 * pointing to a #mbedtls_hmac_drbg_context; 174 * - mbedtls_psa_get_random() with 175 * `prng = MBEDTLS_PSA_RANDOM_STATE`. 176 * 177 * \note Generally, given a call 178 * `mbedtls_foo(f_rng, p_rng, ....)`, the RNG callback 179 * and the context only need to remain valid until 180 * the call to `mbedtls_foo` returns. However, there 181 * are a few exceptions where the callback is stored 182 * in for future use. Check the documentation of 183 * the calling function. 184 * 185 * \warning In a multithreaded environment, calling the 186 * function should be thread-safe. The standard 187 * functions provided by the library are thread-safe 188 * when #MBEDTLS_THREADING_C is enabled. 189 * 190 * \warning This function must either provide as many 191 * bytes as requested of **cryptographic quality** 192 * random data, or return a negative error code. 193 * 194 * \param p_rng The \c p_rng argument that was passed along \c f_rng. 195 * The library always passes \c p_rng unchanged. 196 * This is typically a pointer to the random generator 197 * state, or \c NULL if the custom random generator 198 * doesn't need a context-specific state. 199 * \param[out] output On success, this must be filled with \p output_size 200 * bytes of cryptographic-quality random data. 201 * \param output_size The number of bytes to output. 202 * 203 * \return \c 0 on success, or a negative error code on failure. 204 * Library functions will generally propagate this 205 * error code, so \c MBEDTLS_ERR_xxx values are 206 * recommended. #MBEDTLS_ERR_ENTROPY_SOURCE_FAILED is 207 * typically sensible for RNG failures. 208 */ 209 typedef int mbedtls_f_rng_t(void *p_rng, 210 unsigned char *output, size_t output_size); 211 212 #if defined(MBEDTLS_HAVE_TIME_DATE) 213 /** 214 * \brief Platform-specific implementation of gmtime_r() 215 * 216 * The function is a thread-safe abstraction that behaves 217 * similarly to the gmtime_r() function from Unix/POSIX. 218 * 219 * Mbed TLS will try to identify the underlying platform and 220 * make use of an appropriate underlying implementation (e.g. 221 * gmtime_r() for POSIX and gmtime_s() for Windows). If this is 222 * not possible, then gmtime() will be used. In this case, calls 223 * from the library to gmtime() will be guarded by the mutex 224 * mbedtls_threading_gmtime_mutex if MBEDTLS_THREADING_C is 225 * enabled. It is recommended that calls from outside the library 226 * are also guarded by this mutex. 227 * 228 * If MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, then Mbed TLS will 229 * unconditionally use the alternative implementation for 230 * mbedtls_platform_gmtime_r() supplied by the user at compile time. 231 * 232 * \param tt Pointer to an object containing time (in seconds) since the 233 * epoch to be converted 234 * \param tm_buf Pointer to an object where the results will be stored 235 * 236 * \return Pointer to an object of type struct tm on success, otherwise 237 * NULL 238 */ 239 struct tm *mbedtls_platform_gmtime_r(const mbedtls_time_t *tt, 240 struct tm *tm_buf); 241 #endif /* MBEDTLS_HAVE_TIME_DATE */ 242 243 #ifdef __cplusplus 244 } 245 #endif 246 247 #endif /* MBEDTLS_PLATFORM_UTIL_H */ 248