NAME¶

OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end, OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE_CANCEL, OSSL_TRACE, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4, OSSL_TRACE5, OSSL_TRACE6, OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9, OSSL_TRACEV, OSSL_TRACE_STRING, OSSL_TRACE_STRING_MAX, OSSL_trace_string, OSSL_TRACE_ENABLED - OpenSSL Tracing API

SYNOPSIS¶

 #include <openssl/trace.h>
 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) {
     ...
     if (some_error) {
         /* Leave trace group prematurely in case of an error */
         OSSL_TRACE_CANCEL(category);
         goto err;
     }
     ...
 } OSSL_TRACE_END(category);
 /* one-shot trace macros */
 OSSL_TRACE(category, text)
 OSSL_TRACE1(category, format, arg1)
 OSSL_TRACE2(category, format, arg1, arg2)
 ...
 OSSL_TRACE9(category, format, arg1, ..., arg9)
 OSSL_TRACE_STRING(category, text, full, data, len)
 #define OSSL_TRACE_STRING_MAX 80
 int OSSL_trace_string(BIO *out, int text, int full,
                       const unsigned char *data, size_t size);
 /* check whether a trace category is enabled */
 if (OSSL_TRACE_ENABLED(category)) {
     ...
 }

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 the tracing facility is enabled (see "Configure Tracing" 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 "Trace types" in OSSL_trace_set_callback(3). The fallback type OSSL_TRACE_CATEGORY_ALL should not be used with the functions described here.

Tracing for a specific category is enabled at run-time if a so-called trace channel 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(3), or by providing a callback routine using OSSL_trace_set_callback(3). 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 simple trace channel and a callback trace channel, 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 "Macros" section below.

 OSSL_TRACE_BEGIN(TLS) {
     BIO_printf(trc_out, ... );
 } OSSL_TRACE_END(TLS);

 do {
     BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
     if (trc_out != NULL) {
         ...
         BIO_printf(trc_out, ...);
     }
     OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
 } while (0);

 OSSL_TRACE_BEGIN(TLS) {
     if (some_error) {
         OSSL_TRACE_CANCEL(TLS);
         goto err;
     }
     BIO_printf(trc_out, ... );
 } OSSL_TRACE_END(TLS);

 do {
     BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
     if (trc_out != NULL) {
         if (some_error) {
             OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
             goto err;
         }
         BIO_printf(trc_out, ... );
     }
     OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
 } while (0);

 OSSL_TRACE_BEGIN(category) {
     BIO_printf(trc_out, format, arg1, ..., argN);
 } OSSL_TRACE_END(category)

 OSSL_TRACE_BEGIN(category) {
     OSSL_trace_string(trc_out, text, full, data, len);
 } OSSL_TRACE_END(category)

 if (OSSL_TRACE_ENABLED(TLS)) {
     ...
 }

 if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) {
     ...
 }

NOTES¶

If producing the trace output requires carrying out auxiliary calculations, this auxiliary code should be placed inside a conditional block which is executed only if the trace category is enabled.

The most natural way to do this is to place the code inside the trace section itself because it already introduces such a conditional block.

 OSSL_TRACE_BEGIN(TLS) {
     int var = do_some_auxiliary_calculation();
     BIO_printf(trc_out, "var = %d\n", var);
 } OSSL_TRACE_END(TLS);

In some cases it is more advantageous to use a simple conditional group instead of a trace section. This is the case if calculations and tracing happen in different locations of the code, or if the calculations are so time consuming that placing them inside a (critical) trace section would create too much contention.

 if (OSSL_TRACE_ENABLED(TLS)) {
     int var = do_some_auxiliary_calculation();
     OSSL_TRACE1("var = %d\n", var);
 }

Note however that premature optimization of tracing code is in general futile and it's better to keep the tracing code as simple as possible. Because most often the limiting factor for the application's speed is the time it takes to print the trace output, not to calculate it.

RETURN VALUES¶

OSSL_trace_enabled() returns 1 if tracing for the given type is operational and enabled, otherwise 0.

OSSL_trace_begin() returns a BIO pointer if the given type is enabled, otherwise NULL.

OSSL_trace_string() returns the number of characters emitted, or -1 on error.

SEE ALSO¶

OSSL_trace_set_channel(3), OSSL_trace_set_callback(3)

HISTORY¶

The OpenSSL Tracing API was added in OpenSSL 3.0.

OSSL_TRACE_STRING(), OSSL_TRACE_STRING_MAX, and OSSL_trace_string were added in OpenSSL 3.2.

COPYRIGHT¶

Copyright 2019-2023 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 <https://www.openssl.org/source/license.html>.