123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231 |
- =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_ALL> 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
|