1 /** 2 * \file debug.h 3 * 4 * \brief Functions for controlling and providing debug output from the library. 5 */ 6 /* 7 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 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 * This file is part of mbed TLS (https://tls.mbed.org) 23 */ 24 #ifndef MBEDTLS_DEBUG_H 25 #define MBEDTLS_DEBUG_H 26 27 #if !defined(MBEDTLS_CONFIG_FILE) 28 #include "config.h" 29 #else 30 #include MBEDTLS_CONFIG_FILE 31 #endif 32 33 #include "ssl.h" 34 35 #if defined(MBEDTLS_ECP_C) 36 #include "ecp.h" 37 #endif 38 39 #if defined(MBEDTLS_DEBUG_C) 40 41 #define MBEDTLS_DEBUG_STRIP_PARENS( ... ) __VA_ARGS__ 42 43 #define MBEDTLS_SSL_DEBUG_MSG( level, args ) \ 44 mbedtls_debug_print_msg( ssl, level, __FILE__, __LINE__, \ 45 MBEDTLS_DEBUG_STRIP_PARENS args ) 46 47 #define MBEDTLS_SSL_DEBUG_RET( level, text, ret ) \ 48 mbedtls_debug_print_ret( ssl, level, __FILE__, __LINE__, text, ret ) 49 50 #define MBEDTLS_SSL_DEBUG_BUF( level, text, buf, len ) \ 51 mbedtls_debug_print_buf( ssl, level, __FILE__, __LINE__, text, buf, len ) 52 53 #if defined(MBEDTLS_BIGNUM_C) 54 #define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) \ 55 mbedtls_debug_print_mpi( ssl, level, __FILE__, __LINE__, text, X ) 56 #endif 57 58 #if defined(MBEDTLS_ECP_C) 59 #define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) \ 60 mbedtls_debug_print_ecp( ssl, level, __FILE__, __LINE__, text, X ) 61 #endif 62 63 #if defined(MBEDTLS_X509_CRT_PARSE_C) 64 #define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) \ 65 mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt ) 66 #endif 67 68 #if defined(MBEDTLS_ECDH_C) 69 #define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) \ 70 mbedtls_debug_printf_ecdh( ssl, level, __FILE__, __LINE__, ecdh, attr ) 71 #endif 72 73 #else /* MBEDTLS_DEBUG_C */ 74 75 #define MBEDTLS_SSL_DEBUG_MSG( level, args ) do { } while( 0 ) 76 #define MBEDTLS_SSL_DEBUG_RET( level, text, ret ) do { } while( 0 ) 77 #define MBEDTLS_SSL_DEBUG_BUF( level, text, buf, len ) do { } while( 0 ) 78 #define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) do { } while( 0 ) 79 #define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) do { } while( 0 ) 80 #define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) do { } while( 0 ) 81 #define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) do { } while( 0 ) 82 83 #endif /* MBEDTLS_DEBUG_C */ 84 85 #ifdef __cplusplus 86 extern "C" { 87 #endif 88 89 /** 90 * \brief Set the threshold error level to handle globally all debug output. 91 * Debug messages that have a level over the threshold value are 92 * discarded. 93 * (Default value: 0 = No debug ) 94 * 95 * \param threshold theshold level of messages to filter on. Messages at a 96 * higher level will be discarded. 97 * - Debug levels 98 * - 0 No debug 99 * - 1 Error 100 * - 2 State change 101 * - 3 Informational 102 * - 4 Verbose 103 */ 104 void mbedtls_debug_set_threshold( int threshold ); 105 106 /** 107 * \brief Print a message to the debug output. This function is always used 108 * through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl 109 * context, file and line number parameters. 110 * 111 * \param ssl SSL context 112 * \param level error level of the debug message 113 * \param file file the message has occurred in 114 * \param line line number the message has occurred at 115 * \param format format specifier, in printf format 116 * \param ... variables used by the format specifier 117 * 118 * \attention This function is intended for INTERNAL usage within the 119 * library only. 120 */ 121 void mbedtls_debug_print_msg( const mbedtls_ssl_context *ssl, int level, 122 const char *file, int line, 123 const char *format, ... ); 124 125 /** 126 * \brief Print the return value of a function to the debug output. This 127 * function is always used through the MBEDTLS_SSL_DEBUG_RET() macro, 128 * which supplies the ssl context, file and line number parameters. 129 * 130 * \param ssl SSL context 131 * \param level error level of the debug message 132 * \param file file the error has occurred in 133 * \param line line number the error has occurred in 134 * \param text the name of the function that returned the error 135 * \param ret the return code value 136 * 137 * \attention This function is intended for INTERNAL usage within the 138 * library only. 139 */ 140 void mbedtls_debug_print_ret( const mbedtls_ssl_context *ssl, int level, 141 const char *file, int line, 142 const char *text, int ret ); 143 144 /** 145 * \brief Output a buffer of size len bytes to the debug output. This function 146 * is always used through the MBEDTLS_SSL_DEBUG_BUF() macro, 147 * which supplies the ssl context, file and line number parameters. 148 * 149 * \param ssl SSL context 150 * \param level error level of the debug message 151 * \param file file the error has occurred in 152 * \param line line number the error has occurred in 153 * \param text a name or label for the buffer being dumped. Normally the 154 * variable or buffer name 155 * \param buf the buffer to be outputted 156 * \param len length of the buffer 157 * 158 * \attention This function is intended for INTERNAL usage within the 159 * library only. 160 */ 161 void mbedtls_debug_print_buf( const mbedtls_ssl_context *ssl, int level, 162 const char *file, int line, const char *text, 163 const unsigned char *buf, size_t len ); 164 165 #if defined(MBEDTLS_BIGNUM_C) 166 /** 167 * \brief Print a MPI variable to the debug output. This function is always 168 * used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the 169 * 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 a name or label for the MPI being output. Normally the 176 * variable name 177 * \param X the MPI variable 178 * 179 * \attention This function is intended for INTERNAL usage within the 180 * library only. 181 */ 182 void mbedtls_debug_print_mpi( const mbedtls_ssl_context *ssl, int level, 183 const char *file, int line, 184 const char *text, const mbedtls_mpi *X ); 185 #endif 186 187 #if defined(MBEDTLS_ECP_C) 188 /** 189 * \brief Print an ECP point to the debug output. This function is always 190 * used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the 191 * ssl context, file and line number parameters. 192 * 193 * \param ssl SSL context 194 * \param level error level of the debug message 195 * \param file file the error has occurred in 196 * \param line line number the error has occurred in 197 * \param text a name or label for the ECP point being output. Normally the 198 * variable name 199 * \param X the ECP point 200 * 201 * \attention This function is intended for INTERNAL usage within the 202 * library only. 203 */ 204 void mbedtls_debug_print_ecp( const mbedtls_ssl_context *ssl, int level, 205 const char *file, int line, 206 const char *text, const mbedtls_ecp_point *X ); 207 #endif 208 209 #if defined(MBEDTLS_X509_CRT_PARSE_C) 210 /** 211 * \brief Print a X.509 certificate structure to the debug output. This 212 * function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro, 213 * which supplies the ssl context, file and line number parameters. 214 * 215 * \param ssl SSL context 216 * \param level error level of the debug message 217 * \param file file the error has occurred in 218 * \param line line number the error has occurred in 219 * \param text a name or label for the certificate being output 220 * \param crt X.509 certificate structure 221 * 222 * \attention This function is intended for INTERNAL usage within the 223 * library only. 224 */ 225 void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level, 226 const char *file, int line, 227 const char *text, const mbedtls_x509_crt *crt ); 228 #endif 229 230 #if defined(MBEDTLS_ECDH_C) 231 typedef enum 232 { 233 MBEDTLS_DEBUG_ECDH_Q, 234 MBEDTLS_DEBUG_ECDH_QP, 235 MBEDTLS_DEBUG_ECDH_Z, 236 } mbedtls_debug_ecdh_attr; 237 238 /** 239 * \brief Print a field of the ECDH structure in the SSL context to the debug 240 * output. This function is always used through the 241 * MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file 242 * and line number parameters. 243 * 244 * \param ssl SSL context 245 * \param level error level of the debug message 246 * \param file file the error has occurred in 247 * \param line line number the error has occurred in 248 * \param ecdh the ECDH context 249 * \param attr the identifier of the attribute being output 250 * 251 * \attention This function is intended for INTERNAL usage within the 252 * library only. 253 */ 254 void mbedtls_debug_printf_ecdh( const mbedtls_ssl_context *ssl, int level, 255 const char *file, int line, 256 const mbedtls_ecdh_context *ecdh, 257 mbedtls_debug_ecdh_attr attr ); 258 #endif 259 260 #ifdef __cplusplus 261 } 262 #endif 263 264 #endif /* debug.h */ 265 266