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 #ifdef __cplusplus 84 extern "C" { 85 #endif 86 87 /** 88 * \brief Set the threshold error level to handle globally all debug output. 89 * Debug messages that have a level over the threshold value are 90 * discarded. 91 * (Default value: 0 = No debug ) 92 * 93 * \param threshold theshold level of messages to filter on. Messages at a 94 * higher level will be discarded. 95 * - Debug levels 96 * - 0 No debug 97 * - 1 Error 98 * - 2 State change 99 * - 3 Informational 100 * - 4 Verbose 101 */ 102 void mbedtls_debug_set_threshold( int threshold ); 103 104 /** 105 * \brief Print a message to the debug output. This function is always used 106 * through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl 107 * context, file and line number parameters. 108 * 109 * \param ssl SSL context 110 * \param level error level of the debug message 111 * \param file file the message has occurred in 112 * \param line line number the message has occurred at 113 * \param format format specifier, in printf format 114 * \param ... variables used by the format specifier 115 * 116 * \attention This function is intended for INTERNAL usage within the 117 * library only. 118 */ 119 void mbedtls_debug_print_msg( const mbedtls_ssl_context *ssl, int level, 120 const char *file, int line, 121 const char *format, ... ); 122 123 /** 124 * \brief Print the return value of a function to the debug output. This 125 * function is always used through the MBEDTLS_SSL_DEBUG_RET() macro, 126 * which supplies the ssl context, file and line number parameters. 127 * 128 * \param ssl SSL context 129 * \param level error level of the debug message 130 * \param file file the error has occurred in 131 * \param line line number the error has occurred in 132 * \param text the name of the function that returned the error 133 * \param ret the return code value 134 * 135 * \attention This function is intended for INTERNAL usage within the 136 * library only. 137 */ 138 void mbedtls_debug_print_ret( const mbedtls_ssl_context *ssl, int level, 139 const char *file, int line, 140 const char *text, int ret ); 141 142 /** 143 * \brief Output a buffer of size len bytes to the debug output. This function 144 * is always used through the MBEDTLS_SSL_DEBUG_BUF() macro, 145 * which supplies the ssl context, file and line number parameters. 146 * 147 * \param ssl SSL context 148 * \param level error level of the debug message 149 * \param file file the error has occurred in 150 * \param line line number the error has occurred in 151 * \param text a name or label for the buffer being dumped. Normally the 152 * variable or buffer name 153 * \param buf the buffer to be outputted 154 * \param len length of the buffer 155 * 156 * \attention This function is intended for INTERNAL usage within the 157 * library only. 158 */ 159 void mbedtls_debug_print_buf( const mbedtls_ssl_context *ssl, int level, 160 const char *file, int line, const char *text, 161 const unsigned char *buf, size_t len ); 162 163 #if defined(MBEDTLS_BIGNUM_C) 164 /** 165 * \brief Print a MPI variable to the debug output. This function is always 166 * used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the 167 * ssl context, file and line number parameters. 168 * 169 * \param ssl SSL context 170 * \param level error level of the debug message 171 * \param file file the error has occurred in 172 * \param line line number the error has occurred in 173 * \param text a name or label for the MPI being output. Normally the 174 * variable name 175 * \param X the MPI variable 176 * 177 * \attention This function is intended for INTERNAL usage within the 178 * library only. 179 */ 180 void mbedtls_debug_print_mpi( const mbedtls_ssl_context *ssl, int level, 181 const char *file, int line, 182 const char *text, const mbedtls_mpi *X ); 183 #endif 184 185 #if defined(MBEDTLS_ECP_C) 186 /** 187 * \brief Print an ECP point to the debug output. This function is always 188 * used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the 189 * ssl context, file and line number parameters. 190 * 191 * \param ssl SSL context 192 * \param level error level of the debug message 193 * \param file file the error has occurred in 194 * \param line line number the error has occurred in 195 * \param text a name or label for the ECP point being output. Normally the 196 * variable name 197 * \param X the ECP point 198 * 199 * \attention This function is intended for INTERNAL usage within the 200 * library only. 201 */ 202 void mbedtls_debug_print_ecp( const mbedtls_ssl_context *ssl, int level, 203 const char *file, int line, 204 const char *text, const mbedtls_ecp_point *X ); 205 #endif 206 207 #if defined(MBEDTLS_X509_CRT_PARSE_C) 208 /** 209 * \brief Print a X.509 certificate structure to the debug output. This 210 * function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro, 211 * which supplies the ssl context, file and line number parameters. 212 * 213 * \param ssl SSL context 214 * \param level error level of the debug message 215 * \param file file the error has occurred in 216 * \param line line number the error has occurred in 217 * \param text a name or label for the certificate being output 218 * \param crt X.509 certificate structure 219 * 220 * \attention This function is intended for INTERNAL usage within the 221 * library only. 222 */ 223 void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level, 224 const char *file, int line, 225 const char *text, const mbedtls_x509_crt *crt ); 226 #endif 227 228 #if defined(MBEDTLS_ECDH_C) 229 typedef enum 230 { 231 MBEDTLS_DEBUG_ECDH_Q, 232 MBEDTLS_DEBUG_ECDH_QP, 233 MBEDTLS_DEBUG_ECDH_Z, 234 } mbedtls_debug_ecdh_attr; 235 236 /** 237 * \brief Print a field of the ECDH structure in the SSL context to the debug 238 * output. This function is always used through the 239 * MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file 240 * 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 ecdh the ECDH context 247 * \param attr the identifier of the attribute being output 248 * 249 * \attention This function is intended for INTERNAL usage within the 250 * library only. 251 */ 252 void mbedtls_debug_printf_ecdh( const mbedtls_ssl_context *ssl, int level, 253 const char *file, int line, 254 const mbedtls_ecdh_context *ecdh, 255 mbedtls_debug_ecdh_attr attr ); 256 #endif 257 258 #ifdef __cplusplus 259 } 260 #endif 261 262 #endif /* debug.h */ 263