File debug.h

Functions for controlling and providing debug output from the library.

Defines

MBEDTLS_DEBUG_STRIP_PARENS(...)
MBEDTLS_SSL_DEBUG_MSG(level, args)
MBEDTLS_SSL_DEBUG_RET(level, text, ret)
MBEDTLS_SSL_DEBUG_BUF(level, text, buf, len)
MBEDTLS_SSL_DEBUG_MPI(level, text, X)
MBEDTLS_SSL_DEBUG_ECP(level, text, X)
MBEDTLS_SSL_DEBUG_CRT(level, text, crt)
MBEDTLS_SSL_DEBUG_ECDH(level, ecdh, attr)
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.

MBEDTLS_PRINTF_SIZET

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.

MBEDTLS_PRINTF_LONGLONG
MBEDTLS_PRINTF_MS_TIME

Enums

enum mbedtls_debug_ecdh_attr

Values:

enumerator MBEDTLS_DEBUG_ECDH_Q
enumerator MBEDTLS_DEBUG_ECDH_QP
enumerator 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 )

Parameters

threshold – threshold 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

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.

Attention

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

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

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.

Attention

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

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

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.

Attention

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

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

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.

Attention

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

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

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.

Attention

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

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

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.

Attention

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

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