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 OR GPL-2.0-or-later 9 * 10 * This file is provided under the Apache License 2.0, or the 11 * GNU General Public License v2.0 or later. 12 * 13 * ********** 14 * Apache License 2.0: 15 * 16 * Licensed under the Apache License, Version 2.0 (the "License"); you may 17 * not use this file except in compliance with the License. 18 * You may obtain a copy of the License at 19 * 20 * http://www.apache.org/licenses/LICENSE-2.0 21 * 22 * Unless required by applicable law or agreed to in writing, software 23 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 24 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 25 * See the License for the specific language governing permissions and 26 * limitations under the License. 27 * 28 * ********** 29 * 30 * ********** 31 * GNU General Public License v2.0 or later: 32 * 33 * This program is free software; you can redistribute it and/or modify 34 * it under the terms of the GNU General Public License as published by 35 * the Free Software Foundation; either version 2 of the License, or 36 * (at your option) any later version. 37 * 38 * This program is distributed in the hope that it will be useful, 39 * but WITHOUT ANY WARRANTY; without even the implied warranty of 40 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 41 * GNU General Public License for more details. 42 * 43 * You should have received a copy of the GNU General Public License along 44 * with this program; if not, write to the Free Software Foundation, Inc., 45 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 46 * 47 * ********** 48 */ 49 #ifndef MBEDTLS_DEBUG_H 50 #define MBEDTLS_DEBUG_H 51 52 #if !defined(MBEDTLS_CONFIG_FILE) 53 #include "config.h" 54 #else 55 #include MBEDTLS_CONFIG_FILE 56 #endif 57 58 #include "ssl.h" 59 60 #if defined(MBEDTLS_ECP_C) 61 #include "ecp.h" 62 #endif 63 64 #if defined(MBEDTLS_DEBUG_C) 65 66 #define MBEDTLS_DEBUG_STRIP_PARENS( ... ) __VA_ARGS__ 67 68 #define MBEDTLS_SSL_DEBUG_MSG( level, args ) \ 69 mbedtls_debug_print_msg( ssl, level, __FILE__, __LINE__, \ 70 MBEDTLS_DEBUG_STRIP_PARENS args ) 71 72 #define MBEDTLS_SSL_DEBUG_RET( level, text, ret ) \ 73 mbedtls_debug_print_ret( ssl, level, __FILE__, __LINE__, text, ret ) 74 75 #define MBEDTLS_SSL_DEBUG_BUF( level, text, buf, len ) \ 76 mbedtls_debug_print_buf( ssl, level, __FILE__, __LINE__, text, buf, len ) 77 78 #if defined(MBEDTLS_BIGNUM_C) 79 #define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) \ 80 mbedtls_debug_print_mpi( ssl, level, __FILE__, __LINE__, text, X ) 81 #endif 82 83 #if defined(MBEDTLS_ECP_C) 84 #define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) \ 85 mbedtls_debug_print_ecp( ssl, level, __FILE__, __LINE__, text, X ) 86 #endif 87 88 #if defined(MBEDTLS_X509_CRT_PARSE_C) 89 #define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) \ 90 mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt ) 91 #endif 92 93 #if defined(MBEDTLS_ECDH_C) 94 #define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) \ 95 mbedtls_debug_printf_ecdh( ssl, level, __FILE__, __LINE__, ecdh, attr ) 96 #endif 97 98 #else /* MBEDTLS_DEBUG_C */ 99 100 #define MBEDTLS_SSL_DEBUG_MSG( level, args ) do { } while( 0 ) 101 #define MBEDTLS_SSL_DEBUG_RET( level, text, ret ) do { } while( 0 ) 102 #define MBEDTLS_SSL_DEBUG_BUF( level, text, buf, len ) do { } while( 0 ) 103 #define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) do { } while( 0 ) 104 #define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) do { } while( 0 ) 105 #define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) do { } while( 0 ) 106 #define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) do { } while( 0 ) 107 108 #endif /* MBEDTLS_DEBUG_C */ 109 110 #ifdef __cplusplus 111 extern "C" { 112 #endif 113 114 /** 115 * \brief Set the threshold error level to handle globally all debug output. 116 * Debug messages that have a level over the threshold value are 117 * discarded. 118 * (Default value: 0 = No debug ) 119 * 120 * \param threshold theshold level of messages to filter on. Messages at a 121 * higher level will be discarded. 122 * - Debug levels 123 * - 0 No debug 124 * - 1 Error 125 * - 2 State change 126 * - 3 Informational 127 * - 4 Verbose 128 */ 129 void mbedtls_debug_set_threshold( int threshold ); 130 131 /** 132 * \brief Print a message to the debug output. This function is always used 133 * through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl 134 * context, file and line number parameters. 135 * 136 * \param ssl SSL context 137 * \param level error level of the debug message 138 * \param file file the message has occurred in 139 * \param line line number the message has occurred at 140 * \param format format specifier, in printf format 141 * \param ... variables used by the format specifier 142 * 143 * \attention This function is intended for INTERNAL usage within the 144 * library only. 145 */ 146 void mbedtls_debug_print_msg( const mbedtls_ssl_context *ssl, int level, 147 const char *file, int line, 148 const char *format, ... ); 149 150 /** 151 * \brief Print the return value of a function to the debug output. This 152 * function is always used through the MBEDTLS_SSL_DEBUG_RET() macro, 153 * which supplies the ssl context, file and line number parameters. 154 * 155 * \param ssl SSL context 156 * \param level error level of the debug message 157 * \param file file the error has occurred in 158 * \param line line number the error has occurred in 159 * \param text the name of the function that returned the error 160 * \param ret the return code value 161 * 162 * \attention This function is intended for INTERNAL usage within the 163 * library only. 164 */ 165 void mbedtls_debug_print_ret( const mbedtls_ssl_context *ssl, int level, 166 const char *file, int line, 167 const char *text, int ret ); 168 169 /** 170 * \brief Output a buffer of size len bytes to the debug output. This function 171 * is always used through the MBEDTLS_SSL_DEBUG_BUF() macro, 172 * which supplies the ssl context, file and line number parameters. 173 * 174 * \param ssl SSL context 175 * \param level error level of the debug message 176 * \param file file the error has occurred in 177 * \param line line number the error has occurred in 178 * \param text a name or label for the buffer being dumped. Normally the 179 * variable or buffer name 180 * \param buf the buffer to be outputted 181 * \param len length of the buffer 182 * 183 * \attention This function is intended for INTERNAL usage within the 184 * library only. 185 */ 186 void mbedtls_debug_print_buf( const mbedtls_ssl_context *ssl, int level, 187 const char *file, int line, const char *text, 188 const unsigned char *buf, size_t len ); 189 190 #if defined(MBEDTLS_BIGNUM_C) 191 /** 192 * \brief Print a MPI variable to the debug output. This function is always 193 * used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the 194 * 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 MPI being output. Normally the 201 * variable name 202 * \param X the MPI variable 203 * 204 * \attention This function is intended for INTERNAL usage within the 205 * library only. 206 */ 207 void mbedtls_debug_print_mpi( const mbedtls_ssl_context *ssl, int level, 208 const char *file, int line, 209 const char *text, const mbedtls_mpi *X ); 210 #endif 211 212 #if defined(MBEDTLS_ECP_C) 213 /** 214 * \brief Print an ECP point to the debug output. This function is always 215 * used through the MBEDTLS_SSL_DEBUG_ECP() 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 ECP point being output. Normally the 223 * variable name 224 * \param X the ECP point 225 * 226 * \attention This function is intended for INTERNAL usage within the 227 * library only. 228 */ 229 void mbedtls_debug_print_ecp( const mbedtls_ssl_context *ssl, int level, 230 const char *file, int line, 231 const char *text, const mbedtls_ecp_point *X ); 232 #endif 233 234 #if defined(MBEDTLS_X509_CRT_PARSE_C) 235 /** 236 * \brief Print a X.509 certificate structure to the debug output. This 237 * function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro, 238 * which supplies the 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 certificate being output 245 * \param crt X.509 certificate structure 246 * 247 * \attention This function is intended for INTERNAL usage within the 248 * library only. 249 */ 250 void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level, 251 const char *file, int line, 252 const char *text, const mbedtls_x509_crt *crt ); 253 #endif 254 255 #if defined(MBEDTLS_ECDH_C) 256 typedef enum 257 { 258 MBEDTLS_DEBUG_ECDH_Q, 259 MBEDTLS_DEBUG_ECDH_QP, 260 MBEDTLS_DEBUG_ECDH_Z, 261 } mbedtls_debug_ecdh_attr; 262 263 /** 264 * \brief Print a field of the ECDH structure in the SSL context to the debug 265 * output. This function is always used through the 266 * MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file 267 * and line number parameters. 268 * 269 * \param ssl SSL context 270 * \param level error level of the debug message 271 * \param file file the error has occurred in 272 * \param line line number the error has occurred in 273 * \param ecdh the ECDH context 274 * \param attr the identifier of the attribute being output 275 * 276 * \attention This function is intended for INTERNAL usage within the 277 * library only. 278 */ 279 void mbedtls_debug_printf_ecdh( const mbedtls_ssl_context *ssl, int level, 280 const char *file, int line, 281 const mbedtls_ecdh_context *ecdh, 282 mbedtls_debug_ecdh_attr attr ); 283 #endif 284 285 #ifdef __cplusplus 286 } 287 #endif 288 289 #endif /* debug.h */ 290 291