1 /** 2 * \file debug.h 3 * 4 * \brief Functions for controlling and providing debug output from the library. 5 * 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 7 * SPDX-License-Identifier: Apache-2.0 8 * 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may 10 * not use this file except in compliance with the License. 11 * You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, software 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18 * See the License for the specific language governing permissions and 19 * limitations under the License. 20 * 21 * This file is part of mbed TLS (https://tls.mbed.org) 22 */ 23 #ifndef MBEDTLS_DEBUG_H 24 #define MBEDTLS_DEBUG_H 25 26 #if !defined(MBEDTLS_CONFIG_FILE) 27 #include "config.h" 28 #else 29 #include MBEDTLS_CONFIG_FILE 30 #endif 31 32 #include "ssl.h" 33 34 #if defined(MBEDTLS_ECP_C) 35 #include "ecp.h" 36 #endif 37 38 #if defined(MBEDTLS_DEBUG_C) 39 40 #define MBEDTLS_DEBUG_STRIP_PARENS( ... ) __VA_ARGS__ 41 42 #define MBEDTLS_SSL_DEBUG_MSG( level, args ) \ 43 mbedtls_debug_print_msg( ssl, level, __FILE__, __LINE__, \ 44 MBEDTLS_DEBUG_STRIP_PARENS args ) 45 46 #define MBEDTLS_SSL_DEBUG_RET( level, text, ret ) \ 47 mbedtls_debug_print_ret( ssl, level, __FILE__, __LINE__, text, ret ) 48 49 #define MBEDTLS_SSL_DEBUG_BUF( level, text, buf, len ) \ 50 mbedtls_debug_print_buf( ssl, level, __FILE__, __LINE__, text, buf, len ) 51 52 #if defined(MBEDTLS_BIGNUM_C) 53 #define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) \ 54 mbedtls_debug_print_mpi( ssl, level, __FILE__, __LINE__, text, X ) 55 #endif 56 57 #if defined(MBEDTLS_ECP_C) 58 #define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) \ 59 mbedtls_debug_print_ecp( ssl, level, __FILE__, __LINE__, text, X ) 60 #endif 61 62 #if defined(MBEDTLS_X509_CRT_PARSE_C) 63 #define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) \ 64 mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt ) 65 #endif 66 67 #else /* MBEDTLS_DEBUG_C */ 68 69 #define MBEDTLS_SSL_DEBUG_MSG( level, args ) do { } while( 0 ) 70 #define MBEDTLS_SSL_DEBUG_RET( level, text, ret ) do { } while( 0 ) 71 #define MBEDTLS_SSL_DEBUG_BUF( level, text, buf, len ) do { } while( 0 ) 72 #define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) do { } while( 0 ) 73 #define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) do { } while( 0 ) 74 #define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) do { } while( 0 ) 75 76 #endif /* MBEDTLS_DEBUG_C */ 77 78 #ifdef __cplusplus 79 extern "C" { 80 #endif 81 82 /** 83 * \brief Set the threshold error level to handle globally all debug output. 84 * Debug messages that have a level over the threshold value are 85 * discarded. 86 * (Default value: 0 = No debug ) 87 * 88 * \param threshold theshold level of messages to filter on. Messages at a 89 * higher level will be discarded. 90 * - Debug levels 91 * - 0 No debug 92 * - 1 Error 93 * - 2 State change 94 * - 3 Informational 95 * - 4 Verbose 96 */ 97 void mbedtls_debug_set_threshold( int threshold ); 98 99 /** 100 * \brief Print a message to the debug output. This function is always used 101 * through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl 102 * context, file and line number parameters. 103 * 104 * \param ssl SSL context 105 * \param level error level of the debug message 106 * \param file file the message has occurred in 107 * \param line line number the message has occurred at 108 * \param format format specifier, in printf format 109 * \param ... variables used by the format specifier 110 * 111 * \attention This function is intended for INTERNAL usage within the 112 * library only. 113 */ 114 void mbedtls_debug_print_msg( const mbedtls_ssl_context *ssl, int level, 115 const char *file, int line, 116 const char *format, ... ); 117 118 /** 119 * \brief Print the return value of a function to the debug output. This 120 * function is always used through the MBEDTLS_SSL_DEBUG_RET() macro, 121 * which supplies the ssl context, file and line number parameters. 122 * 123 * \param ssl SSL context 124 * \param level error level of the debug message 125 * \param file file the error has occurred in 126 * \param line line number the error has occurred in 127 * \param text the name of the function that returned the error 128 * \param ret the return code value 129 * 130 * \attention This function is intended for INTERNAL usage within the 131 * library only. 132 */ 133 void mbedtls_debug_print_ret( const mbedtls_ssl_context *ssl, int level, 134 const char *file, int line, 135 const char *text, int ret ); 136 137 /** 138 * \brief Output a buffer of size len bytes to the debug output. This function 139 * is always used through the MBEDTLS_SSL_DEBUG_BUF() macro, 140 * which supplies the ssl context, file and line number parameters. 141 * 142 * \param ssl SSL context 143 * \param level error level of the debug message 144 * \param file file the error has occurred in 145 * \param line line number the error has occurred in 146 * \param text a name or label for the buffer being dumped. Normally the 147 * variable or buffer name 148 * \param buf the buffer to be outputted 149 * \param len length of the buffer 150 * 151 * \attention This function is intended for INTERNAL usage within the 152 * library only. 153 */ 154 void mbedtls_debug_print_buf( const mbedtls_ssl_context *ssl, int level, 155 const char *file, int line, const char *text, 156 const unsigned char *buf, size_t len ); 157 158 #if defined(MBEDTLS_BIGNUM_C) 159 /** 160 * \brief Print a MPI variable to the debug output. This function is always 161 * used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the 162 * ssl context, file and line number parameters. 163 * 164 * \param ssl SSL context 165 * \param level error level of the debug message 166 * \param file file the error has occurred in 167 * \param line line number the error has occurred in 168 * \param text a name or label for the MPI being output. Normally the 169 * variable name 170 * \param X the MPI variable 171 * 172 * \attention This function is intended for INTERNAL usage within the 173 * library only. 174 */ 175 void mbedtls_debug_print_mpi( const mbedtls_ssl_context *ssl, int level, 176 const char *file, int line, 177 const char *text, const mbedtls_mpi *X ); 178 #endif 179 180 #if defined(MBEDTLS_ECP_C) 181 /** 182 * \brief Print an ECP point to the debug output. This function is always 183 * used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the 184 * ssl context, file and line number parameters. 185 * 186 * \param ssl SSL context 187 * \param level error level of the debug message 188 * \param file file the error has occurred in 189 * \param line line number the error has occurred in 190 * \param text a name or label for the ECP point being output. Normally the 191 * variable name 192 * \param X the ECP point 193 * 194 * \attention This function is intended for INTERNAL usage within the 195 * library only. 196 */ 197 void mbedtls_debug_print_ecp( const mbedtls_ssl_context *ssl, int level, 198 const char *file, int line, 199 const char *text, const mbedtls_ecp_point *X ); 200 #endif 201 202 #if defined(MBEDTLS_X509_CRT_PARSE_C) 203 /** 204 * \brief Print a X.509 certificate structure to the debug output. This 205 * function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro, 206 * which supplies the ssl context, file and line number parameters. 207 * 208 * \param ssl SSL context 209 * \param level error level of the debug message 210 * \param file file the error has occurred in 211 * \param line line number the error has occurred in 212 * \param text a name or label for the certificate being output 213 * \param crt X.509 certificate structure 214 * 215 * \attention This function is intended for INTERNAL usage within the 216 * library only. 217 */ 218 void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level, 219 const char *file, int line, 220 const char *text, const mbedtls_x509_crt *crt ); 221 #endif 222 223 #ifdef __cplusplus 224 } 225 #endif 226 227 #endif /* debug.h */ 228 229
