c37e635065
This commit adds some missing symbols and other minor enhancements. In particular, it establishes the term 'channel' as a synonym for a BIO object attached to a trace category, and introduces the concept of a 'simple' channel versus a 'callback' channel. Reviewed-by: Paul Dale <paul.dale@oracle.com> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/8463)
231 lines
6.4 KiB
Text
231 lines
6.4 KiB
Text
=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 <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) {
|
|
...
|
|
} 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</NOTES> 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<OSSL_trace_set_callback(3)/Trace types>.
|
|
The fallback type C<OSSL_TRACE_CATEGORY_ANY> should I<not> be used
|
|
with the functions described here.
|
|
|
|
Tracing for a specific category is enabled if a so called
|
|
I<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(),
|
|
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<simple trace channel> and a I<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 L</Macros> section below.
|
|
|
|
|
|
=head2 Functions
|
|
|
|
OSSL_trace_enabled() can be used to check if tracing for the given
|
|
C<category> is enabled.
|
|
|
|
OSSL_trace_begin() is used to starts a tracing section, and get the
|
|
channel for the given C<category> 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<mandatory>.
|
|
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<OSSL_TRACE_BEGIN(category)> and C<OSSL_TRACE_END(category)> reserve
|
|
the B<BIO> C<trc_out> 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<OSSL_TRACE_CANCEL(category)> 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<OSSL_TRACE1()>, ... C<OSSL_TRACE9()> 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<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h>.
|
|
|
|
=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</Macros> 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<type> is
|
|
operational and enabled, otherwise 0.
|
|
|
|
OSSL_trace_begin() returns a C<BIO *> if the given B<type> is enabled,
|
|
otherwise C<NULL>.
|
|
|
|
=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<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|