1 /** 2 * \file debug.h 3 * 4 * \brief Functions for controlling and providing debug output from the library. 5 */ 6 /* 7 * Copyright The Mbed TLS Contributors 8 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 9 */ 10 #ifndef MBEDTLS_DEBUG_H 11 #define MBEDTLS_DEBUG_H 12 13 #include "mbedtls/build_info.h" 14 15 #include "mbedtls/ssl.h" 16 17 #if defined(MBEDTLS_ECP_C) 18 #include "mbedtls/ecp.h" 19 #endif 20 21 #if defined(MBEDTLS_DEBUG_C) 22 23 #define MBEDTLS_DEBUG_STRIP_PARENS(...) __VA_ARGS__ 24 25 #define MBEDTLS_SSL_DEBUG_MSG(level, args) \ 26 mbedtls_debug_print_msg(ssl, level, __FILE__, __LINE__, \ 27 MBEDTLS_DEBUG_STRIP_PARENS args) 28 29 #define MBEDTLS_SSL_DEBUG_RET(level, text, ret) \ 30 mbedtls_debug_print_ret(ssl, level, __FILE__, __LINE__, text, ret) 31 32 #define MBEDTLS_SSL_DEBUG_BUF(level, text, buf, len) \ 33 mbedtls_debug_print_buf(ssl, level, __FILE__, __LINE__, text, buf, len) 34 35 #if defined(MBEDTLS_BIGNUM_C) 36 #define MBEDTLS_SSL_DEBUG_MPI(level, text, X) \ 37 mbedtls_debug_print_mpi(ssl, level, __FILE__, __LINE__, text, X) 38 #endif 39 40 #if defined(MBEDTLS_ECP_C) 41 #define MBEDTLS_SSL_DEBUG_ECP(level, text, X) \ 42 mbedtls_debug_print_ecp(ssl, level, __FILE__, __LINE__, text, X) 43 #endif 44 45 #if defined(MBEDTLS_X509_CRT_PARSE_C) 46 #if !defined(MBEDTLS_X509_REMOVE_INFO) 47 #define MBEDTLS_SSL_DEBUG_CRT(level, text, crt) \ 48 mbedtls_debug_print_crt(ssl, level, __FILE__, __LINE__, text, crt) 49 #else 50 #define MBEDTLS_SSL_DEBUG_CRT(level, text, crt) do { } while (0) 51 #endif /* MBEDTLS_X509_REMOVE_INFO */ 52 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 53 54 #if defined(MBEDTLS_ECDH_C) 55 #define MBEDTLS_SSL_DEBUG_ECDH(level, ecdh, attr) \ 56 mbedtls_debug_printf_ecdh(ssl, level, __FILE__, __LINE__, ecdh, attr) 57 #endif 58 59 #else /* MBEDTLS_DEBUG_C */ 60 61 #define MBEDTLS_SSL_DEBUG_MSG(level, args) do { } while (0) 62 #define MBEDTLS_SSL_DEBUG_RET(level, text, ret) do { } while (0) 63 #define MBEDTLS_SSL_DEBUG_BUF(level, text, buf, len) do { } while (0) 64 #define MBEDTLS_SSL_DEBUG_MPI(level, text, X) do { } while (0) 65 #define MBEDTLS_SSL_DEBUG_ECP(level, text, X) do { } while (0) 66 #define MBEDTLS_SSL_DEBUG_CRT(level, text, crt) do { } while (0) 67 #define MBEDTLS_SSL_DEBUG_ECDH(level, ecdh, attr) do { } while (0) 68 69 #endif /* MBEDTLS_DEBUG_C */ 70 71 /** 72 * \def MBEDTLS_PRINTF_ATTRIBUTE 73 * 74 * Mark a function as having printf attributes, and thus enable checking 75 * via -wFormat and other flags. This does nothing on builds with compilers 76 * that do not support the format attribute 77 * 78 * Module: library/debug.c 79 * Caller: 80 * 81 * This module provides debugging functions. 82 */ 83 #if defined(__has_attribute) 84 #if __has_attribute(format) 85 #if defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 1 86 #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check) \ 87 __attribute__((__format__(gnu_printf, string_index, first_to_check))) 88 #else /* defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 1 */ 89 #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check) \ 90 __attribute__((format(printf, string_index, first_to_check))) 91 #endif 92 #else /* __has_attribute(format) */ 93 #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check) 94 #endif /* __has_attribute(format) */ 95 #else /* defined(__has_attribute) */ 96 #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check) 97 #endif 98 99 /** 100 * \def MBEDTLS_PRINTF_SIZET 101 * 102 * MBEDTLS_PRINTF_xxx: Due to issues with older window compilers 103 * and MinGW we need to define the printf specifier for size_t 104 * and long long per platform. 105 * 106 * Module: library/debug.c 107 * Caller: 108 * 109 * This module provides debugging functions. 110 */ 111 #if (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) 112 #include <inttypes.h> 113 #define MBEDTLS_PRINTF_SIZET PRIuPTR 114 #define MBEDTLS_PRINTF_LONGLONG "I64d" 115 #else \ 116 /* (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */ 117 #define MBEDTLS_PRINTF_SIZET "zu" 118 #define MBEDTLS_PRINTF_LONGLONG "lld" 119 #endif \ 120 /* (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */ 121 122 #if !defined(MBEDTLS_PRINTF_MS_TIME) 123 #define MBEDTLS_PRINTF_MS_TIME PRId64 124 #endif /* MBEDTLS_PRINTF_MS_TIME */ 125 126 #ifdef __cplusplus 127 extern "C" { 128 #endif 129 130 /** 131 * \brief Set the threshold error level to handle globally all debug output. 132 * Debug messages that have a level over the threshold value are 133 * discarded. 134 * (Default value: 0 = No debug ) 135 * 136 * \param threshold threshold level of messages to filter on. Messages at a 137 * higher level will be discarded. 138 * - Debug levels 139 * - 0 No debug 140 * - 1 Error 141 * - 2 State change 142 * - 3 Informational 143 * - 4 Verbose 144 */ 145 void mbedtls_debug_set_threshold(int threshold); 146 147 /** 148 * \brief Print a message to the debug output. This function is always used 149 * through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl 150 * context, file and line number parameters. 151 * 152 * \param ssl SSL context 153 * \param level error level of the debug message 154 * \param file file the message has occurred in 155 * \param line line number the message has occurred at 156 * \param format format specifier, in printf format 157 * \param ... variables used by the format specifier 158 * 159 * \attention This function is intended for INTERNAL usage within the 160 * library only. 161 */ 162 void mbedtls_debug_print_msg(const mbedtls_ssl_context *ssl, int level, 163 const char *file, int line, 164 const char *format, ...) MBEDTLS_PRINTF_ATTRIBUTE(5, 6); 165 166 /** 167 * \brief Print the return value of a function to the debug output. This 168 * function is always used through the MBEDTLS_SSL_DEBUG_RET() macro, 169 * which supplies the ssl context, file and line number parameters. 170 * 171 * \param ssl SSL context 172 * \param level error level of the debug message 173 * \param file file the error has occurred in 174 * \param line line number the error has occurred in 175 * \param text the name of the function that returned the error 176 * \param ret the return code value 177 * 178 * \attention This function is intended for INTERNAL usage within the 179 * library only. 180 */ 181 void mbedtls_debug_print_ret(const mbedtls_ssl_context *ssl, int level, 182 const char *file, int line, 183 const char *text, int ret); 184 185 /** 186 * \brief Output a buffer of size len bytes to the debug output. This function 187 * is always used through the MBEDTLS_SSL_DEBUG_BUF() macro, 188 * which supplies the ssl context, file and line number parameters. 189 * 190 * \param ssl SSL context 191 * \param level error level of the debug message 192 * \param file file the error has occurred in 193 * \param line line number the error has occurred in 194 * \param text a name or label for the buffer being dumped. Normally the 195 * variable or buffer name 196 * \param buf the buffer to be outputted 197 * \param len length of the buffer 198 * 199 * \attention This function is intended for INTERNAL usage within the 200 * library only. 201 */ 202 void mbedtls_debug_print_buf(const mbedtls_ssl_context *ssl, int level, 203 const char *file, int line, const char *text, 204 const unsigned char *buf, size_t len); 205 206 #if defined(MBEDTLS_BIGNUM_C) 207 /** 208 * \brief Print a MPI variable to the debug output. This function is always 209 * used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the 210 * ssl context, file and line number parameters. 211 * 212 * \param ssl SSL context 213 * \param level error level of the debug message 214 * \param file file the error has occurred in 215 * \param line line number the error has occurred in 216 * \param text a name or label for the MPI being output. Normally the 217 * variable name 218 * \param X the MPI variable 219 * 220 * \attention This function is intended for INTERNAL usage within the 221 * library only. 222 */ 223 void mbedtls_debug_print_mpi(const mbedtls_ssl_context *ssl, int level, 224 const char *file, int line, 225 const char *text, const mbedtls_mpi *X); 226 #endif 227 228 #if defined(MBEDTLS_ECP_C) 229 /** 230 * \brief Print an ECP point to the debug output. This function is always 231 * used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the 232 * ssl context, file and line number parameters. 233 * 234 * \param ssl SSL context 235 * \param level error level of the debug message 236 * \param file file the error has occurred in 237 * \param line line number the error has occurred in 238 * \param text a name or label for the ECP point being output. Normally the 239 * variable name 240 * \param X the ECP point 241 * 242 * \attention This function is intended for INTERNAL usage within the 243 * library only. 244 */ 245 void mbedtls_debug_print_ecp(const mbedtls_ssl_context *ssl, int level, 246 const char *file, int line, 247 const char *text, const mbedtls_ecp_point *X); 248 #endif 249 250 #if defined(MBEDTLS_X509_CRT_PARSE_C) && !defined(MBEDTLS_X509_REMOVE_INFO) 251 /** 252 * \brief Print a X.509 certificate structure to the debug output. This 253 * function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro, 254 * which supplies the ssl context, file and line number parameters. 255 * 256 * \param ssl SSL context 257 * \param level error level of the debug message 258 * \param file file the error has occurred in 259 * \param line line number the error has occurred in 260 * \param text a name or label for the certificate being output 261 * \param crt X.509 certificate structure 262 * 263 * \attention This function is intended for INTERNAL usage within the 264 * library only. 265 */ 266 void mbedtls_debug_print_crt(const mbedtls_ssl_context *ssl, int level, 267 const char *file, int line, 268 const char *text, const mbedtls_x509_crt *crt); 269 #endif 270 271 /* Note: the MBEDTLS_ECDH_C guard here is mandatory because this debug function 272 only works for the built-in implementation. */ 273 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_ECDH_OR_ECDHE_ANY_ENABLED) && \ 274 defined(MBEDTLS_ECDH_C) 275 typedef enum { 276 MBEDTLS_DEBUG_ECDH_Q, 277 MBEDTLS_DEBUG_ECDH_QP, 278 MBEDTLS_DEBUG_ECDH_Z, 279 } mbedtls_debug_ecdh_attr; 280 281 /** 282 * \brief Print a field of the ECDH structure in the SSL context to the debug 283 * output. This function is always used through the 284 * MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file 285 * and line number parameters. 286 * 287 * \param ssl SSL context 288 * \param level error level of the debug message 289 * \param file file the error has occurred in 290 * \param line line number the error has occurred in 291 * \param ecdh the ECDH context 292 * \param attr the identifier of the attribute being output 293 * 294 * \attention This function is intended for INTERNAL usage within the 295 * library only. 296 */ 297 void mbedtls_debug_printf_ecdh(const mbedtls_ssl_context *ssl, int level, 298 const char *file, int line, 299 const mbedtls_ecdh_context *ecdh, 300 mbedtls_debug_ecdh_attr attr); 301 #endif /* MBEDTLS_KEY_EXCHANGE_SOME_ECDH_OR_ECDHE_ANY_ENABLED && 302 MBEDTLS_ECDH_C */ 303 304 #ifdef __cplusplus 305 } 306 #endif 307 308 #endif /* debug.h */ 309
