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