MBEDTLS_SSL_DEBUG_MSG no longer usable

[borrrden]

Summary

MBEDTLS_SSL_DEBUG_MSG no longer usable

System information

Mbed TLS version (number or commit id): 3.6.3
Operating system and version: Windows 10.0.19045.0
Configuration (if not default, please attach mbedtls_config.h): Github makes this impossible....
Compiler and options (if you used a pre-built binary, please indicate how you obtained it):

MSVC from visual studio 17.13.1

Additional environment information:

Expected behavior

If there is a macro present in a public header (i.e. in the include folder) then it should function. Or it should be removed.

Actual behavior

The macro is defined to use the mbedtls_debug_print_msg function, but that function is not defined.

mbedtls/include/mbedtls/debug.h

Lines 25 to 27 in 22098d4

	#define MBEDTLS_SSL_DEBUG_MSG(level, args) \
	mbedtls_debug_print_msg(ssl, level, __FILE__, __LINE__, \
	MBEDTLS_DEBUG_STRIP_PARENS args)

It is defined in the debug_internal.h header, but that is not a public header.

Steps to reproduce

#include <mbedtls/debug.h>

int main() {
    MBEDTLS_SSL_DEBUG_MSG(1, "message");
}

Additional information

[minosgalanakis]

Hi, and thank you for your report.

To my understanding, in order to use MBEDTLS_SSL_DEBUG_MSG, the MBEDTLS_DEBUG_C option must be enabled.
For reference using CMake, this can be done with:

cmake -D CMAKE_BUILD_TYPE=Debug .

On Windows, you should ensure that the MSVC build type is set to Debug.

I can't confirm this is the issue you're encountering, but I’d appreciate some clarification on the following:

• Was this code working in a previous version of Mbed TLS, and did it stop working with 3.6.3?
• Was Mbed TLS built using a Debug build configuration?

Since this looks like a usage question, I recommend continuing the discussion on the public mailing list: mbed-tls@lists.trustedfirmware.org. This allows more of the community to follow along and contribute.

I'll go ahead and close this issue here, but I’d be happy to carry on the conversation via the mailing list.

Thanks again!

[gilles-peskine-arm]

@minosgalanakis Actually MBEDTLS_DEBUG_C enables debug messages in TLS. It's unrelated to CMAKE_BUILD_TYPE=Debug which tells CMake to tell the compiler to include debug symbols (e.g. gcc -g).

[gilles-peskine-arm]

MBEDTLS_SSL_DEBUG_MSG and the other macros in <mbedtls/debug.h> were not documented in Mbed TLS 3.x, so they aren't formally covered by our definition of backward compatibility. In Mbed TLS 3.6.0, we removed the declarations of the underlying functions (which were documented as “for INTERNAL usage within the library only”), but we forgot to move the macros as well. I agree that this is inconsistent — but if we had noticed, the macros would still not have worked.

We intend to remove the macro definitions in Mbed TLS 4.0 as well. One reason we prefer to make the debugging facility private is that the library is used on many platforms that don't have a sufficiently C99-compliant vsnprintf, so we have a little added complexity (notably MBEDTLS_PRINTF_SIZET) which is hard to get right when the call to vsnprintf is compiled separately from the function that relays its arguments to vsnprintf.

That being said, if there is interest in making the TLS debug functions available outside the library, we can still re-expose the debug functions. However, if we do that, we need to sort out which parts of Mbed TLS ≤3.5's debug.h should be public and documented, and which parts should be private.

1. What is your use case for calling Mbed TLS's TLS debugging functionality, rather than just calling printf directly?
2. Would you be willing to contribute documentation for the parts of debug.h that should be public, and sort out which parts should be public?

[borrrden]

Thanks for all the information. I came to here because I saw a small error but I wasn't sure which part was the error. It could have been either that

A. The internal functions were mistakenly made private
B. The macros were mistakenly NOT made private

I can certainly adapt to the fact that your intention seems to be B. We were using it because we were integrating mbedtls with a third party web socket library (sockpp) and figured that we should put all messages related to that in the same context:

https://github.com/couchbasedeps/sockpp/blob/1eb85da51993526f067b0a8319e15a30fd17abe2/src/mbedtls_context.cpp#L113-L120

The nice part about that was that we could then scoop up those messages in a consuming project and either drop or log them based on verbosity settings:

https://github.com/couchbase/couchbase-lite-core/blob/5ade9aa867d1da80e9c9b378699ffa1a266ffbc0/Networking/TLSContext.cc#L40-L51

Essentially we got the "plumbing" here for free so to speak. Again, that's something that we can put back in ourselves if we need to so if the direction is B above as it seems to be that's fine I mostly wanted clarification.

[irwir]

The resolved issue #8591 is a case when debug capability was a major help in zeroing in on the roots of the problem.
Turning on the debugging caused some clashes with private declarations, and minor adjustments in ssl_mail_client.c had to be made too - even though the application already had code for debugging. These changes was not reported, and now the details were forgotten.

[gilles-peskine-arm]

I'm looking at this again after it missed the boat for 4.0, and we're now doing planning for the 4.1 long-time support branch and this is not likely to make the cut.

I do think it would make sense to expose the debug macros as a public API, or at least some of them. But clearly we can't find the time for it. A pull request would definitely help, but even so I'm afraid I can't promise we would find the time to do it.

I think this is safe enough that we can do it in an LTS branch if there's demand. In an LTS branch, we can't break the ABI, and we don't want to make major refactorings or significantly increase the code size. But exposing some private interfaces is ok.