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