debug.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311
  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. #if !defined(MBEDTLS_CONFIG_FILE)
  25. #include "mbedtls/config.h"
  26. #else
  27. #include MBEDTLS_CONFIG_FILE
  28. #endif
  29. #include "mbedtls/ssl.h"
  30. #if defined(MBEDTLS_ECP_C)
  31. #include "mbedtls/ecp.h"
  32. #endif
  33. #if defined(MBEDTLS_DEBUG_C)
  34. #define MBEDTLS_DEBUG_STRIP_PARENS( ... ) __VA_ARGS__
  35. #define MBEDTLS_SSL_DEBUG_MSG( level, args ) \
  36. mbedtls_debug_print_msg( ssl, level, __FILE__, __LINE__, \
  37. MBEDTLS_DEBUG_STRIP_PARENS args )
  38. #define MBEDTLS_SSL_DEBUG_RET( level, text, ret ) \
  39. mbedtls_debug_print_ret( ssl, level, __FILE__, __LINE__, text, ret )
  40. #define MBEDTLS_SSL_DEBUG_BUF( level, text, buf, len ) \
  41. mbedtls_debug_print_buf( ssl, level, __FILE__, __LINE__, text, buf, len )
  42. #if defined(MBEDTLS_BIGNUM_C)
  43. #define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) \
  44. mbedtls_debug_print_mpi( ssl, level, __FILE__, __LINE__, text, X )
  45. #endif
  46. #if defined(MBEDTLS_ECP_C)
  47. #define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) \
  48. mbedtls_debug_print_ecp( ssl, level, __FILE__, __LINE__, text, X )
  49. #endif
  50. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  51. #define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) \
  52. mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt )
  53. #endif
  54. #if defined(MBEDTLS_ECDH_C)
  55. #define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) \
  56. mbedtls_debug_printf_ecdh( ssl, level, __FILE__, __LINE__, ecdh, attr )
  57. #endif
  58. #else /* MBEDTLS_DEBUG_C */
  59. #define MBEDTLS_SSL_DEBUG_MSG( level, args ) do { } while( 0 )
  60. #define MBEDTLS_SSL_DEBUG_RET( level, text, ret ) do { } while( 0 )
  61. #define MBEDTLS_SSL_DEBUG_BUF( level, text, buf, len ) do { } while( 0 )
  62. #define MBEDTLS_SSL_DEBUG_MPI( level, text, X ) do { } while( 0 )
  63. #define MBEDTLS_SSL_DEBUG_ECP( level, text, X ) do { } while( 0 )
  64. #define MBEDTLS_SSL_DEBUG_CRT( level, text, crt ) do { } while( 0 )
  65. #define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr ) do { } while( 0 )
  66. #endif /* MBEDTLS_DEBUG_C */
  67. /**
  68. * \def MBEDTLS_PRINTF_ATTRIBUTE
  69. *
  70. * Mark a function as having printf attributes, and thus enable checking
  71. * via -wFormat and other flags. This does nothing on builds with compilers
  72. * that do not support the format attribute
  73. *
  74. * Module: library/debug.c
  75. * Caller:
  76. *
  77. * This module provides debugging functions.
  78. */
  79. #if defined(__has_attribute)
  80. #if __has_attribute(format)
  81. #if defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 1
  82. #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check) \
  83. __attribute__((__format__ (gnu_printf, string_index, first_to_check)))
  84. #else /* defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 1 */
  85. #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check) \
  86. __attribute__((format(printf, string_index, first_to_check)))
  87. #endif
  88. #else /* __has_attribute(format) */
  89. #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check)
  90. #endif /* __has_attribute(format) */
  91. #else /* defined(__has_attribute) */
  92. #define MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check)
  93. #endif
  94. /**
  95. * \def MBEDTLS_PRINTF_SIZET
  96. *
  97. * MBEDTLS_PRINTF_xxx: Due to issues with older window compilers
  98. * and MinGW we need to define the printf specifier for size_t
  99. * and long long per platform.
  100. *
  101. * Module: library/debug.c
  102. * Caller:
  103. *
  104. * This module provides debugging functions.
  105. */
  106. #if (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800)
  107. #include <inttypes.h>
  108. #define MBEDTLS_PRINTF_SIZET PRIuPTR
  109. #define MBEDTLS_PRINTF_LONGLONG "I64d"
  110. #else /* (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */
  111. #define MBEDTLS_PRINTF_SIZET "zu"
  112. #define MBEDTLS_PRINTF_LONGLONG "lld"
  113. #endif /* (defined(__MINGW32__) && __USE_MINGW_ANSI_STDIO == 0) || (defined(_MSC_VER) && _MSC_VER < 1800) */
  114. #ifdef __cplusplus
  115. extern "C" {
  116. #endif
  117. /**
  118. * \brief Set the threshold error level to handle globally all debug output.
  119. * Debug messages that have a level over the threshold value are
  120. * discarded.
  121. * (Default value: 0 = No debug )
  122. *
  123. * \param threshold theshold level of messages to filter on. Messages at a
  124. * higher level will be discarded.
  125. * - Debug levels
  126. * - 0 No debug
  127. * - 1 Error
  128. * - 2 State change
  129. * - 3 Informational
  130. * - 4 Verbose
  131. */
  132. void mbedtls_debug_set_threshold( int threshold );
  133. /**
  134. * \brief Print a message to the debug output. This function is always used
  135. * through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl
  136. * context, file and line number parameters.
  137. *
  138. * \param ssl SSL context
  139. * \param level error level of the debug message
  140. * \param file file the message has occurred in
  141. * \param line line number the message has occurred at
  142. * \param format format specifier, in printf format
  143. * \param ... variables used by the format specifier
  144. *
  145. * \attention This function is intended for INTERNAL usage within the
  146. * library only.
  147. */
  148. void mbedtls_debug_print_msg( const mbedtls_ssl_context *ssl, int level,
  149. const char *file, int line,
  150. const char *format, ... ) MBEDTLS_PRINTF_ATTRIBUTE(5, 6);
  151. /**
  152. * \brief Print the return value of a function to the debug output. This
  153. * function is always used through the MBEDTLS_SSL_DEBUG_RET() macro,
  154. * which supplies the ssl context, file and line number parameters.
  155. *
  156. * \param ssl SSL context
  157. * \param level error level of the debug message
  158. * \param file file the error has occurred in
  159. * \param line line number the error has occurred in
  160. * \param text the name of the function that returned the error
  161. * \param ret the return code value
  162. *
  163. * \attention This function is intended for INTERNAL usage within the
  164. * library only.
  165. */
  166. void mbedtls_debug_print_ret( const mbedtls_ssl_context *ssl, int level,
  167. const char *file, int line,
  168. const char *text, int ret );
  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. #if defined(MBEDTLS_BIGNUM_C)
  190. /**
  191. * \brief Print a MPI variable to the debug output. This function is always
  192. * used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the
  193. * ssl context, file and line number parameters.
  194. *
  195. * \param ssl SSL context
  196. * \param level error level of the debug message
  197. * \param file file the error has occurred in
  198. * \param line line number the error has occurred in
  199. * \param text a name or label for the MPI being output. Normally the
  200. * variable name
  201. * \param X the MPI variable
  202. *
  203. * \attention This function is intended for INTERNAL usage within the
  204. * library only.
  205. */
  206. void mbedtls_debug_print_mpi( const mbedtls_ssl_context *ssl, int level,
  207. const char *file, int line,
  208. const char *text, const mbedtls_mpi *X );
  209. #endif
  210. #if defined(MBEDTLS_ECP_C)
  211. /**
  212. * \brief Print an ECP point to the debug output. This function is always
  213. * used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the
  214. * ssl context, file and line number parameters.
  215. *
  216. * \param ssl SSL context
  217. * \param level error level of the debug message
  218. * \param file file the error has occurred in
  219. * \param line line number the error has occurred in
  220. * \param text a name or label for the ECP point being output. Normally the
  221. * variable name
  222. * \param X the ECP point
  223. *
  224. * \attention This function is intended for INTERNAL usage within the
  225. * library only.
  226. */
  227. void mbedtls_debug_print_ecp( const mbedtls_ssl_context *ssl, int level,
  228. const char *file, int line,
  229. const char *text, const mbedtls_ecp_point *X );
  230. #endif
  231. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  232. /**
  233. * \brief Print a X.509 certificate structure to the debug output. This
  234. * function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro,
  235. * which supplies the ssl context, file and line number parameters.
  236. *
  237. * \param ssl SSL context
  238. * \param level error level of the debug message
  239. * \param file file the error has occurred in
  240. * \param line line number the error has occurred in
  241. * \param text a name or label for the certificate being output
  242. * \param crt X.509 certificate structure
  243. *
  244. * \attention This function is intended for INTERNAL usage within the
  245. * library only.
  246. */
  247. void mbedtls_debug_print_crt( const mbedtls_ssl_context *ssl, int level,
  248. const char *file, int line,
  249. const char *text, const mbedtls_x509_crt *crt );
  250. #endif
  251. #if defined(MBEDTLS_ECDH_C)
  252. typedef enum
  253. {
  254. MBEDTLS_DEBUG_ECDH_Q,
  255. MBEDTLS_DEBUG_ECDH_QP,
  256. MBEDTLS_DEBUG_ECDH_Z,
  257. } mbedtls_debug_ecdh_attr;
  258. /**
  259. * \brief Print a field of the ECDH structure in the SSL context to the debug
  260. * output. This function is always used through the
  261. * MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file
  262. * and line number parameters.
  263. *
  264. * \param ssl SSL context
  265. * \param level error level of the debug message
  266. * \param file file the error has occurred in
  267. * \param line line number the error has occurred in
  268. * \param ecdh the ECDH context
  269. * \param attr the identifier of the attribute being output
  270. *
  271. * \attention This function is intended for INTERNAL usage within the
  272. * library only.
  273. */
  274. void mbedtls_debug_printf_ecdh( const mbedtls_ssl_context *ssl, int level,
  275. const char *file, int line,
  276. const mbedtls_ecdh_context *ecdh,
  277. mbedtls_debug_ecdh_attr attr );
  278. #endif
  279. #ifdef __cplusplus
  280. }
  281. #endif
  282. #endif /* debug.h */