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 #if !defined(MBEDTLS_CONFIG_FILE) 26 #include "mbedtls/config.h" 27 #else 28 #include MBEDTLS_CONFIG_FILE 29 #endif 30 31 #include "mbedtls/ssl.h" 32 33 #if defined(MBEDTLS_ECP_C) 34 #include "mbedtls/ecp.h" 35 #endif 36 37 #if defined(MBEDTLS_DEBUG_C) 38 39 #define MBEDTLS_DEBUG_STRIP_PARENS( ... ) __VA_ARGS__ 40 41 #define MBEDTLS_SSL_DEBUG_MSG( level, args ) \ 42 mbedtls_debug_print_msg( ssl, level, __FILE__, __LINE__, \ 43 MBEDTLS_DEBUG_STRIP_PARENS args ) 44 45 #define MBEDTLS_SSL_DEBUG_RET( level, text, ret ) \ 46 mbedtls_debug_print_ret( ssl, level, __FILE__, __LINE__, text, ret ) 47 48 #define MBEDTLS_SSL_DEBUG_BUF( level, text, buf, len ) \ 49 mbedtls_debug_print_buf( ssl, level, __FILE__, __LINE__, text, buf, len ) 50 51 #if defined(MBEDTLS_BIGNUM_C) 52 #define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) \ 53 mbedtls_debug_print_mpi( ssl, level, __FILE__, __LINE__, text, X ) 54 #endif 55 56 #if defined(MBEDTLS_ECP_C) 57 #define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) \ 58 mbedtls_debug_print_ecp( ssl, level, __FILE__, __LINE__, text, X ) 59 #endif 60 61 #if defined(MBEDTLS_X509_CRT_PARSE_C) 62 #define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) \ 63 mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt ) 64 #endif 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 /* (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */ 128 #define MBEDTLS_PRINTF_SIZET "zu" 129 #define MBEDTLS_PRINTF_LONGLONG "lld" 130 #endif /* (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */ 131 132 #ifdef __cplusplus 133 extern "C" { 134 #endif 135 136 /** 137 * \brief Set the threshold error level to handle globally all debug output. 138 * Debug messages that have a level over the threshold value are 139 * discarded. 140 * (Default value: 0 = No debug ) 141 * 142 * \param threshold theshold level of messages to filter on. Messages at a 143 * higher level will be discarded. 144 * - Debug levels 145 * - 0 No debug 146 * - 1 Error 147 * - 2 State change 148 * - 3 Informational 149 * - 4 Verbose 150 */ 151 void mbedtls_debug_set_threshold( int threshold ); 152 153 /** 154 * \brief Print a message to the debug output. This function is always used 155 * through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl 156 * context, file and line number parameters. 157 * 158 * \param ssl SSL context 159 * \param level error level of the debug message 160 * \param file file the message has occurred in 161 * \param line line number the message has occurred at 162 * \param format format specifier, in printf format 163 * \param ... variables used by the format specifier 164 * 165 * \attention This function is intended for INTERNAL usage within the 166 * library only. 167 */ 168 void mbedtls_debug_print_msg( const mbedtls_ssl_context *ssl, int level, 169 const char *file, int line, 170 const char *format, ... ) MBEDTLS_PRINTF_ATTRIBUTE(5, 6); 171 172 /** 173 * \brief Print the return value of a function to the debug output. This 174 * function is always used through the MBEDTLS_SSL_DEBUG_RET() macro, 175 * which supplies the ssl context, file and line number parameters. 176 * 177 * \param ssl SSL context 178 * \param level error level of the debug message 179 * \param file file the error has occurred in 180 * \param line line number the error has occurred in 181 * \param text the name of the function that returned the error 182 * \param ret the return code value 183 * 184 * \attention This function is intended for INTERNAL usage within the 185 * library only. 186 */ 187 void mbedtls_debug_print_ret( const mbedtls_ssl_context *ssl, int level, 188 const char *file, int line, 189 const char *text, int ret ); 190 191 /** 192 * \brief Output a buffer of size len bytes to the debug output. This function 193 * is always used through the MBEDTLS_SSL_DEBUG_BUF() macro, 194 * which supplies the ssl context, file and line number parameters. 195 * 196 * \param ssl SSL context 197 * \param level error level of the debug message 198 * \param file file the error has occurred in 199 * \param line line number the error has occurred in 200 * \param text a name or label for the buffer being dumped. Normally the 201 * variable or buffer name 202 * \param buf the buffer to be outputted 203 * \param len length of the buffer 204 * 205 * \attention This function is intended for INTERNAL usage within the 206 * library only. 207 */ 208 void mbedtls_debug_print_buf( const mbedtls_ssl_context *ssl, int level, 209 const char *file, int line, const char *text, 210 const unsigned char *buf, size_t len ); 211 212 #if defined(MBEDTLS_BIGNUM_C) 213 /** 214 * \brief Print a MPI variable to the debug output. This function is always 215 * used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the 216 * ssl context, file and line number parameters. 217 * 218 * \param ssl SSL context 219 * \param level error level of the debug message 220 * \param file file the error has occurred in 221 * \param line line number the error has occurred in 222 * \param text a name or label for the MPI being output. Normally the 223 * variable name 224 * \param X the MPI variable 225 * 226 * \attention This function is intended for INTERNAL usage within the 227 * library only. 228 */ 229 void mbedtls_debug_print_mpi( const mbedtls_ssl_context *ssl, int level, 230 const char *file, int line, 231 const char *text, const mbedtls_mpi *X ); 232 #endif 233 234 #if defined(MBEDTLS_ECP_C) 235 /** 236 * \brief Print an ECP point to the debug output. This function is always 237 * used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the 238 * ssl context, file and line number parameters. 239 * 240 * \param ssl SSL context 241 * \param level error level of the debug message 242 * \param file file the error has occurred in 243 * \param line line number the error has occurred in 244 * \param text a name or label for the ECP point being output. Normally the 245 * variable name 246 * \param X the ECP point 247 * 248 * \attention This function is intended for INTERNAL usage within the 249 * library only. 250 */ 251 void mbedtls_debug_print_ecp( const mbedtls_ssl_context *ssl, int level, 252 const char *file, int line, 253 const char *text, const mbedtls_ecp_point *X ); 254 #endif 255 256 #if defined(MBEDTLS_X509_CRT_PARSE_C) 257 /** 258 * \brief Print a X.509 certificate structure to the debug output. This 259 * function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro, 260 * which supplies the ssl context, file and line number parameters. 261 * 262 * \param ssl SSL context 263 * \param level error level of the debug message 264 * \param file file the error has occurred in 265 * \param line line number the error has occurred in 266 * \param text a name or label for the certificate being output 267 * \param crt X.509 certificate structure 268 * 269 * \attention This function is intended for INTERNAL usage within the 270 * library only. 271 */ 272 void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level, 273 const char *file, int line, 274 const char *text, const mbedtls_x509_crt *crt ); 275 #endif 276 277 #if defined(MBEDTLS_ECDH_C) 278 typedef enum 279 { 280 MBEDTLS_DEBUG_ECDH_Q, 281 MBEDTLS_DEBUG_ECDH_QP, 282 MBEDTLS_DEBUG_ECDH_Z, 283 } mbedtls_debug_ecdh_attr; 284 285 /** 286 * \brief Print a field of the ECDH structure in the SSL context to the debug 287 * output. This function is always used through the 288 * MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file 289 * and line number parameters. 290 * 291 * \param ssl SSL context 292 * \param level error level of the debug message 293 * \param file file the error has occurred in 294 * \param line line number the error has occurred in 295 * \param ecdh the ECDH context 296 * \param attr the identifier of the attribute being output 297 * 298 * \attention This function is intended for INTERNAL usage within the 299 * library only. 300 */ 301 void mbedtls_debug_printf_ecdh( const mbedtls_ssl_context *ssl, int level, 302 const char *file, int line, 303 const mbedtls_ecdh_context *ecdh, 304 mbedtls_debug_ecdh_attr attr ); 305 #endif 306 307 #ifdef __cplusplus 308 } 309 #endif 310 311 #endif /* debug.h */ 312