common/mbedtls/debug.h

   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 /**
  84  * \def MBEDTLS_PRINTF_ATTRIBUTE
  85  *
  86  * Mark a function as having printf attributes, and thus enable checking
  87  * via -wFormat and other flags. This does nothing on builds with compilers
  88  * that do not support the format attribute
  89  *
  90  * Module:  library/debug.c
  91  * Caller:
  92  *
  93  * This module provides debugging functions.
  94  */
  95 #if defined(__has_attribute)
  96 #if __has_attribute(format)
  97 #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check)    \
  98     __attribute__((format (printf, string_index, first_to_check)))
  99 #else /* __has_attribute(format) */
 100 #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check)
 101 #endif /* __has_attribute(format) */
 102 #else /* defined(__has_attribute) */
 103 #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check)
 104 #endif
 105
 106 /**
 107  * \def MBEDTLS_PRINTF_SIZET
 108  *
 109  * MBEDTLS_PRINTF_xxx: Due to issues with older window compilers
 110  * and MinGW we need to define the printf specifier for size_t
 111  * and long long per platform.
 112  *
 113  * Module:  library/debug.c
 114  * Caller:
 115  *
 116  * This module provides debugging functions.
 117  */
 118 #if defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER < 1800)
 119 #include <inttypes.h>
 120 #define MBEDTLS_PRINTF_SIZET     PRIuPTR
 121 #define MBEDTLS_PRINTF_LONGLONG  "I64d"
 122 #else /* defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER < 1800) */
 123 #define MBEDTLS_PRINTF_SIZET     "zu"
 124 #define MBEDTLS_PRINTF_LONGLONG  "lld"
 125 #endif /* defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER < 1800) */
 126
 127 #ifdef __cplusplus
 128 extern "C" {
 129 #endif
 130
 131 /**
 132  * \brief   Set the threshold error level to handle globally all debug output.
 133  *          Debug messages that have a level over the threshold value are
 134  *          discarded.
 135  *          (Default value: 0 = No debug )
 136  *
 137  * \param threshold     theshold level of messages to filter on. Messages at a
 138  *                      higher level will be discarded.
 139  *                          - Debug levels
 140  *                              - 0 No debug
 141  *                              - 1 Error
 142  *                              - 2 State change
 143  *                              - 3 Informational
 144  *                              - 4 Verbose
 145  */
 146 void mbedtls_debug_set_threshold(int threshold);
 147
 148 /**
 149  * \brief    Print a message to the debug output. This function is always used
 150  *          through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl
 151  *          context, file and line number parameters.
 152  *
 153  * \param ssl       SSL context
 154  * \param level     error level of the debug message
 155  * \param file      file the message has occurred in
 156  * \param line      line number the message has occurred at
 157  * \param format    format specifier, in printf format
 158  * \param ...       variables used by the format specifier
 159  *
 160  * \attention       This function is intended for INTERNAL usage within the
 161  *                  library only.
 162  */
 163 void mbedtls_debug_print_msg(const mbedtls_ssl_context *ssl, int level,
 164                              const char *file, int line,
 165                              const char *format, ...) MBEDTLS_PRINTF_ATTRIBUTE(5, 6);
 166
 167 /**
 168  * \brief   Print the return value of a function to the debug output. This
 169  *          function is always used through the MBEDTLS_SSL_DEBUG_RET() macro,
 170  *          which supplies the ssl context, file and line number parameters.
 171  *
 172  * \param ssl       SSL context
 173  * \param level     error level of the debug message
 174  * \param file      file the error has occurred in
 175  * \param line      line number the error has occurred in
 176  * \param text      the name of the function that returned the error
 177  * \param ret       the return code value
 178  *
 179  * \attention       This function is intended for INTERNAL usage within the
 180  *                  library only.
 181  */
 182 void mbedtls_debug_print_ret(const mbedtls_ssl_context *ssl, int level,
 183                              const char *file, int line,
 184                              const char *text, int ret);
 185
 186 /**
 187  * \brief   Output a buffer of size len bytes to the debug output. This function
 188  *          is always used through the MBEDTLS_SSL_DEBUG_BUF() macro,
 189  *          which supplies the 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 buffer being dumped. Normally the
 196  *                  variable or buffer name
 197  * \param buf       the buffer to be outputted
 198  * \param len       length of the buffer
 199  *
 200  * \attention       This function is intended for INTERNAL usage within the
 201  *                  library only.
 202  */
 203 void mbedtls_debug_print_buf(const mbedtls_ssl_context *ssl, int level,
 204                              const char *file, int line, const char *text,
 205                              const unsigned char *buf, size_t len);
 206
 207 #if defined(MBEDTLS_BIGNUM_C)
 208 /**
 209  * \brief   Print a MPI variable to the debug output. This function is always
 210  *          used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the
 211  *          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 MPI being output. Normally the
 218  *                  variable name
 219  * \param X         the MPI variable
 220  *
 221  * \attention       This function is intended for INTERNAL usage within the
 222  *                  library only.
 223  */
 224 void mbedtls_debug_print_mpi(const mbedtls_ssl_context *ssl, int level,
 225                              const char *file, int line,
 226                              const char *text, const mbedtls_mpi *X);
 227 #endif
 228
 229 #if defined(MBEDTLS_ECP_C)
 230 /**
 231  * \brief   Print an ECP point to the debug output. This function is always
 232  *          used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the
 233  *          ssl context, file and line number parameters.
 234  *
 235  * \param ssl       SSL context
 236  * \param level     error level of the debug message
 237  * \param file      file the error has occurred in
 238  * \param line      line number the error has occurred in
 239  * \param text      a name or label for the ECP point being output. Normally the
 240  *                  variable name
 241  * \param X         the ECP point
 242  *
 243  * \attention       This function is intended for INTERNAL usage within the
 244  *                  library only.
 245  */
 246 void mbedtls_debug_print_ecp(const mbedtls_ssl_context *ssl, int level,
 247                              const char *file, int line,
 248                              const char *text, const mbedtls_ecp_point *X);
 249 #endif
 250
 251 #if defined(MBEDTLS_X509_CRT_PARSE_C)
 252 /**
 253  * \brief   Print a X.509 certificate structure to the debug output. This
 254  *          function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro,
 255  *          which supplies the ssl context, file and line number parameters.
 256  *
 257  * \param ssl       SSL context
 258  * \param level     error level of the debug message
 259  * \param file      file the error has occurred in
 260  * \param line      line number the error has occurred in
 261  * \param text      a name or label for the certificate being output
 262  * \param crt       X.509 certificate structure
 263  *
 264  * \attention       This function is intended for INTERNAL usage within the
 265  *                  library only.
 266  */
 267 void mbedtls_debug_print_crt(const mbedtls_ssl_context *ssl, int level,
 268                              const char *file, int line,
 269                              const char *text, const mbedtls_x509_crt *crt);
 270 #endif
 271
 272 #if defined(MBEDTLS_ECDH_C)
 273 typedef enum {
 274     MBEDTLS_DEBUG_ECDH_Q,
 275     MBEDTLS_DEBUG_ECDH_QP,
 276     MBEDTLS_DEBUG_ECDH_Z,
 277 } mbedtls_debug_ecdh_attr;
 278
 279 /**
 280  * \brief   Print a field of the ECDH structure in the SSL context to the debug
 281  *          output. This function is always used through the
 282  *          MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file
 283  *          and line number parameters.
 284  *
 285  * \param ssl       SSL context
 286  * \param level     error level of the debug message
 287  * \param file      file the error has occurred in
 288  * \param line      line number the error has occurred in
 289  * \param ecdh      the ECDH context
 290  * \param attr      the identifier of the attribute being output
 291  *
 292  * \attention       This function is intended for INTERNAL usage within the
 293  *                  library only.
 294  */
 295 void mbedtls_debug_printf_ecdh(const mbedtls_ssl_context *ssl, int level,
 296                                const char *file, int line,
 297                                const mbedtls_ecdh_context *ecdh,
 298                                mbedtls_debug_ecdh_attr attr);
 299 #endif
 300
 301 #ifdef __cplusplus
 302 }
 303 #endif
 304
 305 #endif /* debug.h */