debug.h File Reference

Functions for controlling and providing debug output from the library. More...

`#include "mbedtls/config.h"`
`#include "mbedtls/ssl.h"`
`#include "mbedtls/ecp.h"`
Include dependency graph for debug.h:

Go to the source code of this file.

## Macros

#define | MBEDTLS_DEBUG_STRIP_PARENS(...) __VA_ARGS__
#define | MBEDTLS_SSL_DEBUG_MSG(level, args)
#define | MBEDTLS_SSL_DEBUG_RET(level, text, ret) mbedtls_debug_print_ret( ssl, level, __FILE__, __LINE__, text, ret )
#define | MBEDTLS_SSL_DEBUG_BUF(level, text, buf, len) mbedtls_debug_print_buf( ssl, level, __FILE__, __LINE__, text, buf, len )
#define | MBEDTLS_SSL_DEBUG_MPI(level, text, X) mbedtls_debug_print_mpi( ssl, level, __FILE__, __LINE__, text, X )
#define | MBEDTLS_SSL_DEBUG_ECP(level, text, X) mbedtls_debug_print_ecp( ssl, level, __FILE__, __LINE__, text, X )
#define | MBEDTLS_SSL_DEBUG_CRT(level, text, crt) mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt )
#define | MBEDTLS_SSL_DEBUG_ECDH(level, ecdh, attr) mbedtls_debug_printf_ecdh( ssl, level, __FILE__, __LINE__, ecdh, attr )
#define | MBEDTLS_PRINTF_ATTRIBUTE(string_index, first_to_check)
#define | MBEDTLS_PRINTF_SIZET "zu"
#define | MBEDTLS_PRINTF_LONGLONG "lld"

## Enumerations

enum | mbedtls_debug_ecdh_attr { MBEDTLS_DEBUG_ECDH_Q , MBEDTLS_DEBUG_ECDH_QP , MBEDTLS_DEBUG_ECDH_Z }

## Functions

void | mbedtls_debug_set_threshold (int threshold)
| Set the threshold error level to handle globally all debug output. Debug messages that have a level over the threshold value are discarded. (Default value: 0 = No debug ) More...
void | mbedtls_debug_print_msg (const mbedtls_ssl_context *ssl, int level, const char *file, int line, const char *format,...) MBEDTLS_PRINTF_ATTRIBUTE(5
| Print a message to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl context, file and line number parameters. More...
void void | mbedtls_debug_print_ret (const mbedtls_ssl_context *ssl, int level, const char *file, int line, const char *text, int ret)
| Print the return value of a function to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_RET() macro, which supplies the ssl context, file and line number parameters. More...
void | mbedtls_debug_print_buf (const mbedtls_ssl_context *ssl, int level, const char *file, int line, const char *text, const unsigned char *buf, size_t len)
| Output a buffer of size len bytes to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_BUF() macro, which supplies the ssl context, file and line number parameters. More...
void | mbedtls_debug_print_mpi (const mbedtls_ssl_context *ssl, int level, const char *file, int line, const char *text, const mbedtls_mpi *X)
| Print a MPI variable to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the ssl context, file and line number parameters. More...
void | mbedtls_debug_print_ecp (const mbedtls_ssl_context *ssl, int level, const char *file, int line, const char *text, const mbedtls_ecp_point *X)
| Print an ECP point to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the ssl context, file and line number parameters. More...
void | mbedtls_debug_print_crt (const mbedtls_ssl_context *ssl, int level, const char *file, int line, const char *text, const mbedtls_x509_crt *crt)
| Print a X.509 certificate structure to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro, which supplies the ssl context, file and line number parameters. More...
void | mbedtls_debug_printf_ecdh (const mbedtls_ssl_context *ssl, int level, const char *file, int line, const mbedtls_ecdh_context *ecdh, mbedtls_debug_ecdh_attr attr)
| Print a field of the ECDH structure in the SSL context to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file and line number parameters. More...

## Detailed Description

Functions for controlling and providing debug output from the library.

Definition in file debug.h.

## Macro Definition Documentation

## MBEDTLS_DEBUG_STRIP_PARENS

#define MBEDTLS_DEBUG_STRIP_PARENS | ( |  | ... | ) | __VA_ARGS__

Definition at line 39 of file debug.h.

## MBEDTLS_PRINTF_ATTRIBUTE

#define MBEDTLS_PRINTF_ATTRIBUTE | ( |  | string_index,
|  |  | first_to_check
| ) |  |

Mark a function as having printf attributes, and thus enable checking via -wFormat and other flags. This does nothing on builds with compilers that do not support the format attribute

Module: library/debug.c Caller:

This module provides debugging functions.

Definition at line 108 of file debug.h.

## MBEDTLS_PRINTF_LONGLONG

#define MBEDTLS_PRINTF_LONGLONG "lld"

Definition at line 129 of file debug.h.

## MBEDTLS_PRINTF_SIZET

#define MBEDTLS_PRINTF_SIZET "zu"

MBEDTLS_PRINTF_xxx: Due to issues with older window compilers and MinGW we need to define the printf specifier for size_t and long long per platform.

Module: library/debug.c Caller:

This module provides debugging functions.

Definition at line 128 of file debug.h.

## MBEDTLS_SSL_DEBUG_BUF

#define MBEDTLS_SSL_DEBUG_BUF | ( |  | level,
|  |  | text,
|  |  | buf,
|  |  | len
| ) |  | mbedtls_debug_print_buf( ssl, level, __FILE__, __LINE__, text, buf, len )

Definition at line 48 of file debug.h.

## MBEDTLS_SSL_DEBUG_CRT

#define MBEDTLS_SSL_DEBUG_CRT | ( |  | level,
|  |  | text,
|  |  | crt
| ) |  | mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt )

Definition at line 62 of file debug.h.

## MBEDTLS_SSL_DEBUG_ECDH

#define MBEDTLS_SSL_DEBUG_ECDH | ( |  | level,
|  |  | ecdh,
|  |  | attr
| ) |  | mbedtls_debug_printf_ecdh( ssl, level, __FILE__, __LINE__, ecdh, attr )

Definition at line 67 of file debug.h.

## MBEDTLS_SSL_DEBUG_ECP

#define MBEDTLS_SSL_DEBUG_ECP | ( |  | level,
|  |  | text,
|  |  | X
| ) |  | mbedtls_debug_print_ecp( ssl, level, __FILE__, __LINE__, text, X )

Definition at line 57 of file debug.h.

## MBEDTLS_SSL_DEBUG_MPI

#define MBEDTLS_SSL_DEBUG_MPI | ( |  | level,
|  |  | text,
|  |  | X
| ) |  | mbedtls_debug_print_mpi( ssl, level, __FILE__, __LINE__, text, X )

Definition at line 52 of file debug.h.

## MBEDTLS_SSL_DEBUG_MSG

#define MBEDTLS_SSL_DEBUG_MSG | ( |  | level,
|  |  | args
| ) |  |

Value:
mbedtls_debug_print_msg( ssl, level, __FILE__, __LINE__, \
MBEDTLS_DEBUG_STRIP_PARENS args )
MBEDTLS_DEBUG_STRIP_PARENS
#define MBEDTLS_DEBUG_STRIP_PARENS(...)
Definition: debug.h:39
mbedtls_debug_print_msg
void mbedtls_debug_print_msg(const mbedtls_ssl_context *ssl, int level, const char *file, int line, const char *format,...) MBEDTLS_PRINTF_ATTRIBUTE(5
Print a message to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_MSG()...

Definition at line 41 of file debug.h.

## MBEDTLS_SSL_DEBUG_RET

#define MBEDTLS_SSL_DEBUG_RET | ( |  | level,
|  |  | text,
|  |  | ret
| ) |  | mbedtls_debug_print_ret( ssl, level, __FILE__, __LINE__, text, ret )

Definition at line 45 of file debug.h.

## Enumeration Type Documentation

## mbedtls_debug_ecdh_attr

enum mbedtls_debug_ecdh_attr

Enumerator
MBEDTLS_DEBUG_ECDH_Q |
MBEDTLS_DEBUG_ECDH_QP |
MBEDTLS_DEBUG_ECDH_Z |

Definition at line 278 of file debug.h.

## Function Documentation

## mbedtls_debug_print_buf()

void mbedtls_debug_print_buf | ( | const mbedtls_ssl_context * | ssl,
|  | int | level,
|  | const char * | file,
|  | int | line,
|  | const char * | text,
|  | const unsigned char * | buf,
|  | size_t | len
| ) |  |

Output a buffer of size len bytes to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_BUF() macro, which supplies the ssl context, file and line number parameters.

Parameters

  ssl | SSL context
  level | error level of the debug message
  file | file the error has occurred in
  line | line number the error has occurred in
  text | a name or label for the buffer being dumped. Normally the variable or buffer name
  buf | the buffer to be outputted
  len | length of the buffer

Attention
  This function is intended for INTERNAL usage within the library only.

## mbedtls_debug_print_crt()

void mbedtls_debug_print_crt | ( | const mbedtls_ssl_context * | ssl,
|  | int | level,
|  | const char * | file,
|  | int | line,
|  | const char * | text,
|  | const mbedtls_x509_crt * | crt
| ) |  |

Print a X.509 certificate structure to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_CRT() macro, which supplies the ssl context, file and line number parameters.

Parameters

  ssl | SSL context
  level | error level of the debug message
  file | file the error has occurred in
  line | line number the error has occurred in
  text | a name or label for the certificate being output
  crt | X.509 certificate structure

Attention
  This function is intended for INTERNAL usage within the library only.

## mbedtls_debug_print_ecp()

void mbedtls_debug_print_ecp | ( | const mbedtls_ssl_context * | ssl,
|  | int | level,
|  | const char * | file,
|  | int | line,
|  | const char * | text,
|  | const mbedtls_ecp_point * | X
| ) |  |

Print an ECP point to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_ECP() macro, which supplies the ssl context, file and line number parameters.

Parameters

  ssl | SSL context
  level | error level of the debug message
  file | file the error has occurred in
  line | line number the error has occurred in
  text | a name or label for the ECP point being output. Normally the variable name
  X | the ECP point

Attention
  This function is intended for INTERNAL usage within the library only.

## mbedtls_debug_print_mpi()

void mbedtls_debug_print_mpi | ( | const mbedtls_ssl_context * | ssl,
|  | int | level,
|  | const char * | file,
|  | int | line,
|  | const char * | text,
|  | const mbedtls_mpi * | X
| ) |  |

Print a MPI variable to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_MPI() macro, which supplies the ssl context, file and line number parameters.

Parameters

  ssl | SSL context
  level | error level of the debug message
  file | file the error has occurred in
  line | line number the error has occurred in
  text | a name or label for the MPI being output. Normally the variable name
  X | the MPI variable

Attention
  This function is intended for INTERNAL usage within the library only.

## mbedtls_debug_print_msg()

void mbedtls_debug_print_msg | ( | const mbedtls_ssl_context * | ssl,
|  | int | level,
|  | const char * | file,
|  | int | line,
|  | const char * | format,
|  |  | ...
| ) |  |

Print a message to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_MSG() macro, which supplies the ssl context, file and line number parameters.

Parameters

  ssl | SSL context
  level | error level of the debug message
  file | file the message has occurred in
  line | line number the message has occurred at
  format | format specifier, in printf format
  ... | variables used by the format specifier

Attention
  This function is intended for INTERNAL usage within the library only.

## mbedtls_debug_print_ret()

void void mbedtls_debug_print_ret | ( | const mbedtls_ssl_context * | ssl,
|  | int | level,
|  | const char * | file,
|  | int | line,
|  | const char * | text,
|  | int | ret
| ) |  |

Print the return value of a function to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_RET() macro, which supplies the ssl context, file and line number parameters.

Parameters

  ssl | SSL context
  level | error level of the debug message
  file | file the error has occurred in
  line | line number the error has occurred in
  text | the name of the function that returned the error
  ret | the return code value

Attention
  This function is intended for INTERNAL usage within the library only.

## mbedtls_debug_printf_ecdh()

void mbedtls_debug_printf_ecdh | ( | const mbedtls_ssl_context * | ssl,
|  | int | level,
|  | const char * | file,
|  | int | line,
|  | const mbedtls_ecdh_context * | ecdh,
|  | mbedtls_debug_ecdh_attr | attr
| ) |  |

Print a field of the ECDH structure in the SSL context to the debug output. This function is always used through the MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file and line number parameters.

Parameters

  ssl | SSL context
  level | error level of the debug message
  file | file the error has occurred in
  line | line number the error has occurred in
  ecdh | the ECDH context
  attr | the identifier of the attribute being output

Attention
  This function is intended for INTERNAL usage within the library only.

## mbedtls_debug_set_threshold()

void mbedtls_debug_set_threshold | ( | int | threshold | ) |

Set the threshold error level to handle globally all debug output. Debug messages that have a level over the threshold value are discarded. (Default value: 0 = No debug )

Parameters

  threshold

  theshold level of messages to filter on. Messages at a higher level will be discarded.
  - Debug levels
    - 0 No debug
    - 1 Error
    - 2 State change
    - 3 Informational
    - 4 Verbose