=pod =head1 NAME OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end, OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE9 - OpenSSL Tracing API =head1 SYNOPSIS #include int OSSL_trace_enabled(int category); BIO *OSSL_trace_begin(int category); void OSSL_trace_end(int category, BIO *channel); /* trace group macros */ OSSL_TRACE_BEGIN(category) { ... } OSSL_TRACE_END(category); /* one-shot trace macros */ OSSL_TRACE1(category, format, arg1) OSSL_TRACE2(category, format, arg1, arg2) ... OSSL_TRACE9(category, format, arg1, ..., arg9) =head1 DESCRIPTION The functions described here are mainly interesting for those who provide OpenSSL functionality, either in OpenSSL itself or in engine modules or similar. If tracing is enabled (see L below), these functions are used to generate free text tracing output. The tracing output is divided into types which are enabled individually by the application. The tracing types are described in detail in L. The fallback type C should I be used with the functions described here. Tracing for a specific category is enabled if a so called I is attached to it. A trace channel is simply a BIO object to which the application can write its trace output. The application has two different ways of registering a trace channel, either by directly providing a BIO object using OSSL_trace_set_channel(), or by providing a callback routine using OSSL_trace_set_callback(). The latter is wrapped internally by a dedicated BIO object, so for the tracing code both channel types are effectively indistinguishable. We call them a I and a I, respectively. To produce trace output, it is necessary to obtain a pointer to the trace channel (i.e., the BIO object) using OSSL_trace_begin(), write to it using arbitrary BIO output routines, and finally releases the channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end() calls surrounding the trace output create a group, which acts as a critical section (guarded by a mutex) to ensure that the trace output of different threads does not get mixed up. The tracing code normally does not call OSSL_trace_{begin,end}() directly, but rather uses a set of convenience macros, see the L section below. =head2 Functions OSSL_trace_enabled() can be used to check if tracing for the given C is enabled. OSSL_trace_begin() is used to starts a tracing section, and get the channel for the given C in form of a BIO. This BIO can only be used for output. OSSL_trace_end() is used to end a tracing section. Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections is I. The result of trying to produce tracing output outside of such sections is undefined. =head2 Macros There are a number of convenience macros defined, to make tracing easy and consistent. C and C reserve the B C and are used as follows to wrap a trace section: OSSL_TRACE_BEGIN(TLS) { BIO_fprintf(trc_out, ... ); } OSSL_TRACE_END(TLS); This will normally expand to: do { BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); if (trc_out != NULL) { ... BIO_fprintf(trc_out, ...); } OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); } while (0); C must be used before returning from or jumping out of a trace section: OSSL_TRACE_BEGIN(TLS) { if (condition) { OSSL_TRACE_CANCEL(TLS); goto err; } BIO_fprintf(trc_out, ... ); } OSSL_TRACE_END(TLS); This will normally expand to: do { BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); if (trc_out != NULL) { if (condition) { OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); goto err; } BIO_fprintf(trc_out, ... ); } OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); } while (0); C, ... C are one-shot macros which essentially wrap a single BIO_printf() into a tracing group. The call OSSL_TRACEn(category, format, arg1, ..., argN) expands to: OSSL_TRACE_BEGIN(category) { BIO_printf(trc_out, format, arg1, ..., argN) } OSSL_TRACE_END(category) =head1 NOTES It is advisable to always check that a trace type is enabled with OSSL_trace_enabled() before generating any output, for example: if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS)) { BIO *trace = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); BIO_printf(trace, "FOO %d\n", somevalue); BIO_dump(trace, somememory, somememory_l); OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trace); } =head2 Configure Tracing By default, the OpenSSL library is built with tracing disabled. To use the tracing functionality documented here, it is therefore necessary to configure and build OpenSSL with the 'enable-trace' option. When the library is built with tracing disabled: =over 4 =item * The macro C is defined in C. =item * all functions are still present, bu OSSL_trace_enabled() will always report the categories as disabled, and all other functions will do nothing. =item * the convenience macros are defined to produce dead code. For example, take this example from L section above: OSSL_TRACE_BEGIN(TLS) { if (condition) { OSSL_TRACE_CANCEL(TLS); goto err; } BIO_fprintf(trc_out, ... ); } OSSL_TRACE_END(TLS); When the tracing API isn't operational, that will expand to: do { BIO *trc_out = NULL; if (0) { if (condition) { ((void)0); goto err; } BIO_fprintf(trc_out, ... ); } } while (0); =back =head1 RETURN VALUES OSSL_trace_enabled() returns 1 if tracing for the given B is operational and enabled, otherwise 0. OSSL_trace_begin() returns a C if the given B is enabled, otherwise C. =head1 HISTORY The OpenSSL Tracing API was added ino OpenSSL 3.0.0. =head1 COPYRIGHT Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at L. =cut