blob: 1f82ce6640ac54773f7d7bf1eef50c933a513e50 [file] [log] [blame]
Paul Bakker5121ce52009-01-03 21:22:43 +00001/**
2 * \file debug.h
Paul Bakkere0ccd0a2009-01-04 16:27:10 +00003 *
Simon Butcher7ef5cf32016-02-13 22:20:04 +00004 * \brief Functions for controlling and providing debug output from the library.
Darryl Greena40a1012018-01-05 15:33:17 +00005 */
6/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02007 * Copyright The Mbed TLS Contributors
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +02008 * 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.
Paul Bakker5121ce52009-01-03 21:22:43 +000021 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020022#ifndef MBEDTLS_DEBUG_H
23#define MBEDTLS_DEBUG_H
Paul Bakker5121ce52009-01-03 21:22:43 +000024
Bence Szépkútic662b362021-05-27 11:25:03 +020025#include "mbedtls/build_info.h"
Rich Evans00ab4702015-02-06 13:43:58 +000026
Jaeden Amero6609aef2019-07-04 20:01:14 +010027#include "mbedtls/ssl.h"
Rich Evans00ab4702015-02-06 13:43:58 +000028
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020029#if defined(MBEDTLS_ECP_C)
Jaeden Amero6609aef2019-07-04 20:01:14 +010030#include "mbedtls/ecp.h"
Paul Bakker41c83d32013-03-20 14:39:14 +010031#endif
Paul Bakker5121ce52009-01-03 21:22:43 +000032
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020033#if defined(MBEDTLS_DEBUG_C)
Paul Bakker5121ce52009-01-03 21:22:43 +000034
Manuel Pégourié-Gonnardb74c2452015-06-29 20:08:23 +020035#define MBEDTLS_DEBUG_STRIP_PARENS( ... ) __VA_ARGS__
36
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020037#define MBEDTLS_SSL_DEBUG_MSG( level, args ) \
Manuel Pégourié-Gonnarda16e7c42015-06-29 20:14:19 +020038 mbedtls_debug_print_msg( ssl, level, __FILE__, __LINE__, \
Manuel Pégourié-Gonnardb74c2452015-06-29 20:08:23 +020039 MBEDTLS_DEBUG_STRIP_PARENS args )
Paul Bakker5121ce52009-01-03 21:22:43 +000040
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020041#define MBEDTLS_SSL_DEBUG_RET( level, text, ret ) \
Manuel Pégourié-Gonnard2ff873c2015-05-19 14:38:09 +020042 mbedtls_debug_print_ret( ssl, level, __FILE__, __LINE__, text, ret )
Paul Bakker5121ce52009-01-03 21:22:43 +000043
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020044#define MBEDTLS_SSL_DEBUG_BUF( level, text, buf, len ) \
Manuel Pégourié-Gonnard2ff873c2015-05-19 14:38:09 +020045 mbedtls_debug_print_buf( ssl, level, __FILE__, __LINE__, text, buf, len )
Paul Bakker5121ce52009-01-03 21:22:43 +000046
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020047#if defined(MBEDTLS_BIGNUM_C)
48#define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) \
Manuel Pégourié-Gonnard2ff873c2015-05-19 14:38:09 +020049 mbedtls_debug_print_mpi( ssl, level, __FILE__, __LINE__, text, X )
Paul Bakkered27a042013-04-18 22:46:23 +020050#endif
Paul Bakker5121ce52009-01-03 21:22:43 +000051
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020052#if defined(MBEDTLS_ECP_C)
53#define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) \
Manuel Pégourié-Gonnard2ff873c2015-05-19 14:38:09 +020054 mbedtls_debug_print_ecp( ssl, level, __FILE__, __LINE__, text, X )
Paul Bakkered27a042013-04-18 22:46:23 +020055#endif
Paul Bakker41c83d32013-03-20 14:39:14 +010056
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020057#if defined(MBEDTLS_X509_CRT_PARSE_C)
Hanno Becker612a2f12020-10-09 09:19:39 +010058#if !defined(MBEDTLS_X509_REMOVE_INFO)
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020059#define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) \
Manuel Pégourié-Gonnard2ff873c2015-05-19 14:38:09 +020060 mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt )
Peter Kolbus9a969b62018-12-11 13:55:56 -060061#else
62#define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) do { } while( 0 )
Hanno Becker612a2f12020-10-09 09:19:39 +010063#endif /* MBEDTLS_X509_REMOVE_INFO */
Peter Kolbus9a969b62018-12-11 13:55:56 -060064#endif /* MBEDTLS_X509_CRT_PARSE_C */
Paul Bakker5121ce52009-01-03 21:22:43 +000065
Janos Follath948f4be2018-08-22 01:37:55 +010066#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
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020071#else /* MBEDTLS_DEBUG_C */
Paul Bakker5121ce52009-01-03 21:22:43 +000072
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020073#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 )
Janos Follath948f4be2018-08-22 01:37:55 +010079#define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) do { } while( 0 )
Paul Bakker5121ce52009-01-03 21:22:43 +000080
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020081#endif /* MBEDTLS_DEBUG_C */
Paul Bakker5121ce52009-01-03 21:22:43 +000082
Paul Elliott4e589702020-12-09 14:38:01 +000083/**
84 * \def MBEDTLS_PRINTF_ATTRIBUTE
85 *
86 * Mark a function as having printf attributes, and thus enable checking
Paul Elliottaa5e1322021-03-05 15:52:25 +000087 * via -wFormat and other flags. This does nothing on builds with compilers
88 * that do not support the format attribute
Paul Elliott4e589702020-12-09 14:38:01 +000089 *
90 * Module: library/debug.c
91 * Caller:
92 *
93 * This module provides debugging functions.
94 */
Paul Elliottaa5e1322021-03-05 15:52:25 +000095#if defined(__has_attribute)
96#if __has_attribute(format)
eugenee42a50d2021-05-12 12:33:36 -040097#if defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 1
Paul Elliott4e589702020-12-09 14:38:01 +000098#define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check) \
eugenee42a50d2021-05-12 12:33:36 -040099 __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
Paul Elliottaa5e1322021-03-05 15:52:25 +0000104#else /* __has_attribute(format) */
105#define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check)
106#endif /* __has_attribute(format) */
107#else /* defined(__has_attribute) */
Paul Elliottabb3af72020-12-18 16:43:22 +0000108#define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check)
Paul Elliott4e589702020-12-09 14:38:01 +0000109#endif
110
Jerry Yu687101b2021-09-14 16:03:56 +0800111/* MSVC support __func__ from visual studio 2015( 1900 )
112 Use MSVC predefine macro to avoid name check fail.
113 */
114#if (defined(_MSC_VER) && ( _MSC_VER <= 1900 ))
115#define __func__ __FUNCTION__
116#endif
117
Paul Elliottd48d5c62021-01-07 14:47:05 +0000118/**
119 * \def MBEDTLS_PRINTF_SIZET
120 *
121 * MBEDTLS_PRINTF_xxx: Due to issues with older window compilers
122 * and MinGW we need to define the printf specifier for size_t
123 * and long long per platform.
124 *
125 * Module: library/debug.c
126 * Caller:
127 *
128 * This module provides debugging functions.
129 */
eugenee42a50d2021-05-12 12:33:36 -0400130#if (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800)
Paul Elliott48438c72021-01-08 17:05:25 +0000131 #include <inttypes.h>
132 #define MBEDTLS_PRINTF_SIZET PRIuPTR
133 #define MBEDTLS_PRINTF_LONGLONG "I64d"
eugenee42a50d2021-05-12 12:33:36 -0400134#else /* (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */
Paul Elliottd48d5c62021-01-07 14:47:05 +0000135 #define MBEDTLS_PRINTF_SIZET "zu"
136 #define MBEDTLS_PRINTF_LONGLONG "lld"
eugenee42a50d2021-05-12 12:33:36 -0400137#endif /* (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */
Paul Elliottd48d5c62021-01-07 14:47:05 +0000138
Paul Bakker5121ce52009-01-03 21:22:43 +0000139#ifdef __cplusplus
140extern "C" {
141#endif
142
Paul Bakkerc73079a2014-04-25 16:34:30 +0200143/**
Simon Butcher7ef5cf32016-02-13 22:20:04 +0000144 * \brief Set the threshold error level to handle globally all debug output.
145 * Debug messages that have a level over the threshold value are
146 * discarded.
147 * (Default value: 0 = No debug )
Paul Bakkerc73079a2014-04-25 16:34:30 +0200148 *
Simon Butcher7ef5cf32016-02-13 22:20:04 +0000149 * \param threshold theshold level of messages to filter on. Messages at a
150 * higher level will be discarded.
151 * - Debug levels
152 * - 0 No debug
153 * - 1 Error
154 * - 2 State change
155 * - 3 Informational
156 * - 4 Verbose
Paul Bakkerc73079a2014-04-25 16:34:30 +0200157 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200158void mbedtls_debug_set_threshold( int threshold );
Paul Bakkerc73079a2014-04-25 16:34:30 +0200159
Simon Butcher7ef5cf32016-02-13 22:20:04 +0000160/**
Janos Follathd75b7822016-03-18 16:28:20 +0000161 * \brief Print a message to the debug output. This function is always used
Simon Butcher7ef5cf32016-02-13 22:20:04 +0000162 * through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl
163 * context, file and line number parameters.
164 *
165 * \param ssl SSL context
166 * \param level error level of the debug message
167 * \param file file the message has occurred in
168 * \param line line number the message has occurred at
169 * \param format format specifier, in printf format
170 * \param ... variables used by the format specifier
171 *
172 * \attention This function is intended for INTERNAL usage within the
173 * library only.
174 */
Manuel Pégourié-Gonnarda16e7c42015-06-29 20:14:19 +0200175void mbedtls_debug_print_msg( const mbedtls_ssl_context *ssl, int level,
Manuel Pégourié-Gonnardb74c2452015-06-29 20:08:23 +0200176 const char *file, int line,
Paul Elliott4e589702020-12-09 14:38:01 +0000177 const char *format, ... ) MBEDTLS_PRINTF_ATTRIBUTE(5, 6);
Manuel Pégourié-Gonnardd23f5932015-06-23 12:04:52 +0200178
Simon Butcher7ef5cf32016-02-13 22:20:04 +0000179/**
180 * \brief Print the return value of a function to the debug output. This
181 * function is always used through the MBEDTLS_SSL_DEBUG_RET() macro,
182 * which supplies the ssl context, file and line number parameters.
183 *
184 * \param ssl SSL context
185 * \param level error level of the debug message
186 * \param file file the error has occurred in
187 * \param line line number the error has occurred in
188 * \param text the name of the function that returned the error
189 * \param ret the return code value
190 *
191 * \attention This function is intended for INTERNAL usage within the
192 * library only.
193 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200194void mbedtls_debug_print_ret( const mbedtls_ssl_context *ssl, int level,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000195 const char *file, int line,
196 const char *text, int ret );
Paul Bakker5121ce52009-01-03 21:22:43 +0000197
Simon Butcher7ef5cf32016-02-13 22:20:04 +0000198/**
199 * \brief Output a buffer of size len bytes to the debug output. This function
200 * is always used through the MBEDTLS_SSL_DEBUG_BUF() macro,
201 * which supplies the ssl context, file and line number parameters.
202 *
203 * \param ssl SSL context
204 * \param level error level of the debug message
205 * \param file file the error has occurred in
206 * \param line line number the error has occurred in
207 * \param text a name or label for the buffer being dumped. Normally the
208 * variable or buffer name
209 * \param buf the buffer to be outputted
210 * \param len length of the buffer
211 *
212 * \attention This function is intended for INTERNAL usage within the
213 * library only.
214 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200215void mbedtls_debug_print_buf( const mbedtls_ssl_context *ssl, int level,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000216 const char *file, int line, const char *text,
Manuel Pégourié-Gonnarda78b2182015-03-19 17:16:11 +0000217 const unsigned char *buf, size_t len );
Paul Bakker5121ce52009-01-03 21:22:43 +0000218
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200219#if defined(MBEDTLS_BIGNUM_C)
Simon Butcher7ef5cf32016-02-13 22:20:04 +0000220/**
221 * \brief Print a MPI variable to the debug output. This function is always
222 * used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the
223 * ssl context, file and line number parameters.
224 *
225 * \param ssl SSL context
226 * \param level error level of the debug message
227 * \param file file the error has occurred in
228 * \param line line number the error has occurred in
229 * \param text a name or label for the MPI being output. Normally the
230 * variable name
231 * \param X the MPI variable
232 *
233 * \attention This function is intended for INTERNAL usage within the
234 * library only.
235 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200236void mbedtls_debug_print_mpi( const mbedtls_ssl_context *ssl, int level,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000237 const char *file, int line,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200238 const char *text, const mbedtls_mpi *X );
Paul Bakkered27a042013-04-18 22:46:23 +0200239#endif
Paul Bakker5121ce52009-01-03 21:22:43 +0000240
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200241#if defined(MBEDTLS_ECP_C)
Simon Butcher7ef5cf32016-02-13 22:20:04 +0000242/**
243 * \brief Print an ECP point to the debug output. This function is always
244 * used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the
245 * ssl context, file and line number parameters.
246 *
247 * \param ssl SSL context
248 * \param level error level of the debug message
249 * \param file file the error has occurred in
250 * \param line line number the error has occurred in
251 * \param text a name or label for the ECP point being output. Normally the
252 * variable name
253 * \param X the ECP point
254 *
255 * \attention This function is intended for INTERNAL usage within the
256 * library only.
257 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200258void mbedtls_debug_print_ecp( const mbedtls_ssl_context *ssl, int level,
Paul Bakker41c83d32013-03-20 14:39:14 +0100259 const char *file, int line,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200260 const char *text, const mbedtls_ecp_point *X );
Paul Bakker41c83d32013-03-20 14:39:14 +0100261#endif
262
Hanno Becker612a2f12020-10-09 09:19:39 +0100263#if defined(MBEDTLS_X509_CRT_PARSE_C) && !defined(MBEDTLS_X509_REMOVE_INFO)
Simon Butcher7ef5cf32016-02-13 22:20:04 +0000264/**
265 * \brief Print a X.509 certificate structure to the debug output. This
266 * function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro,
267 * which supplies the ssl context, file 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 text a name or label for the certificate being output
274 * \param crt X.509 certificate structure
275 *
276 * \attention This function is intended for INTERNAL usage within the
277 * library only.
278 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200279void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000280 const char *file, int line,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200281 const char *text, const mbedtls_x509_crt *crt );
Paul Bakkered27a042013-04-18 22:46:23 +0200282#endif
Paul Bakker5121ce52009-01-03 21:22:43 +0000283
Janos Follath948f4be2018-08-22 01:37:55 +0100284#if defined(MBEDTLS_ECDH_C)
285typedef enum
286{
287 MBEDTLS_DEBUG_ECDH_Q,
288 MBEDTLS_DEBUG_ECDH_QP,
289 MBEDTLS_DEBUG_ECDH_Z,
290} mbedtls_debug_ecdh_attr;
291
292/**
293 * \brief Print a field of the ECDH structure in the SSL context to the debug
294 * output. This function is always used through the
295 * MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file
296 * and line number parameters.
297 *
298 * \param ssl SSL context
299 * \param level error level of the debug message
300 * \param file file the error has occurred in
301 * \param line line number the error has occurred in
302 * \param ecdh the ECDH context
303 * \param attr the identifier of the attribute being output
304 *
305 * \attention This function is intended for INTERNAL usage within the
306 * library only.
307 */
308void mbedtls_debug_printf_ecdh( const mbedtls_ssl_context *ssl, int level,
309 const char *file, int line,
310 const mbedtls_ecdh_context *ecdh,
311 mbedtls_debug_ecdh_attr attr );
312#endif
313
Paul Bakker5121ce52009-01-03 21:22:43 +0000314#ifdef __cplusplus
315}
316#endif
317
318#endif /* debug.h */