1=pod 2 3=head1 NAME 4 5OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end, 6OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE_CANCEL, 7OSSL_TRACE, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4, 8OSSL_TRACE5, OSSL_TRACE6, OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9, 9OSSL_TRACEV, 10OSSL_TRACE_ENABLED 11- OpenSSL Tracing API 12 13=head1 SYNOPSIS 14 15=for openssl generic 16 17 #include <openssl/trace.h> 18 19 int OSSL_trace_enabled(int category); 20 21 BIO *OSSL_trace_begin(int category); 22 void OSSL_trace_end(int category, BIO *channel); 23 24 /* trace group macros */ 25 OSSL_TRACE_BEGIN(category) { 26 ... 27 if (some_error) { 28 /* Leave trace group prematurely in case of an error */ 29 OSSL_TRACE_CANCEL(category); 30 goto err; 31 } 32 ... 33 } OSSL_TRACE_END(category); 34 35 /* one-shot trace macros */ 36 OSSL_TRACE1(category, format, arg1) 37 OSSL_TRACE2(category, format, arg1, arg2) 38 ... 39 OSSL_TRACE9(category, format, arg1, ..., arg9) 40 41 /* check whether a trace category is enabled */ 42 if (OSSL_TRACE_ENABLED(category)) { 43 ... 44 } 45 46=head1 DESCRIPTION 47 48The functions described here are mainly interesting for those who provide 49OpenSSL functionality, either in OpenSSL itself or in engine modules 50or similar. 51 52If tracing is enabled (see L</NOTES> below), these functions are used to 53generate free text tracing output. 54 55The tracing output is divided into types which are enabled 56individually by the application. 57The tracing types are described in detail in 58L<OSSL_trace_set_callback(3)/Trace types>. 59The fallback type B<OSSL_TRACE_CATEGORY_ALL> should I<not> be used 60with the functions described here. 61 62Tracing for a specific category is enabled if a so called 63I<trace channel> is attached to it. A trace channel is simply a 64BIO object to which the application can write its trace output. 65 66The application has two different ways of registering a trace channel, 67either by directly providing a BIO object using OSSL_trace_set_channel(), 68or by providing a callback routine using OSSL_trace_set_callback(). 69The latter is wrapped internally by a dedicated BIO object, so for the 70tracing code both channel types are effectively indistinguishable. 71We call them a I<simple trace channel> and a I<callback trace channel>, 72respectively. 73 74To produce trace output, it is necessary to obtain a pointer to the 75trace channel (i.e., the BIO object) using OSSL_trace_begin(), write 76to it using arbitrary BIO output routines, and finally releases the 77channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end() 78calls surrounding the trace output create a group, which acts as a 79critical section (guarded by a mutex) to ensure that the trace output 80of different threads does not get mixed up. 81 82The tracing code normally does not call OSSL_trace_{begin,end}() directly, 83but rather uses a set of convenience macros, see the L</Macros> section below. 84 85 86=head2 Functions 87 88OSSL_trace_enabled() can be used to check if tracing for the given 89I<category> is enabled. 90 91OSSL_trace_begin() is used to start a tracing section, 92and get the channel for the given I<category> in form of a BIO. 93This BIO can only be used for output. 94The pointer returned is NULL if the category is invalid or not enabled. 95 96OSSL_trace_end() is used to end a tracing section. 97 98Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections 99is I<mandatory>. 100The result of trying to produce tracing output outside of such 101sections is undefined. 102 103=head2 Macros 104 105There are a number of convenience macros defined, to make tracing 106easy and consistent. 107 108OSSL_TRACE_BEGIN() and OSSL_TRACE_END() reserve the B<BIO> C<trc_out> and are 109used as follows to wrap a trace section: 110 111 OSSL_TRACE_BEGIN(TLS) { 112 113 BIO_fprintf(trc_out, ... ); 114 115 } OSSL_TRACE_END(TLS); 116 117This will normally expand to: 118 119 do { 120 BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); 121 if (trc_out != NULL) { 122 ... 123 BIO_fprintf(trc_out, ...); 124 } 125 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); 126 } while (0); 127 128OSSL_TRACE_CANCEL() must be used before returning from or jumping out of a 129trace section: 130 131 OSSL_TRACE_BEGIN(TLS) { 132 133 if (some_error) { 134 OSSL_TRACE_CANCEL(TLS); 135 goto err; 136 } 137 BIO_fprintf(trc_out, ... ); 138 139 } OSSL_TRACE_END(TLS); 140 141This will normally expand to: 142 143 do { 144 BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); 145 if (trc_out != NULL) { 146 if (some_error) { 147 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); 148 goto err; 149 } 150 BIO_fprintf(trc_out, ... ); 151 } 152 OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); 153 } while (0); 154 155 156OSSL_TRACE() and OSSL_TRACE1(), OSSL_TRACE2(), ... OSSL_TRACE9() are 157so-called one-shot macros: 158 159The macro call C<OSSL_TRACE(category, text)>, produces literal text trace output. 160 161The macro call C<OSSL_TRACEn(category, format, arg1, ..., argn)> produces 162printf-style trace output with n format field arguments (n=1,...,9). 163It expands to: 164 165 OSSL_TRACE_BEGIN(category) { 166 BIO_printf(trc_out, format, arg1, ..., argN) 167 } OSSL_TRACE_END(category) 168 169Internally, all one-shot macros are implemented using a generic OSSL_TRACEV() 170macro, since C90 does not support variadic macros. This helper macro has a rather 171weird synopsis and should not be used directly. 172 173The OSSL_TRACE_ENABLED() macro can be used to conditionally execute some code 174only if a specific trace category is enabled. 175In some situations this is simpler than entering a trace section using 176OSSL_TRACE_BEGIN() and OSSL_TRACE_END(). 177For example, the code 178 179 if (OSSL_TRACE_ENABLED(TLS)) { 180 ... 181 } 182 183expands to 184 185 if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) { 186 ... 187 } 188 189=head1 NOTES 190 191It is not needed to guard trace output function calls like 192I<OSSL_TRACE(category, ...)> by I<OSSL_TRACE_ENABLED(category)>. 193 194If producing the trace output requires carrying out auxiliary calculations, 195this auxiliary code should be placed inside a conditional block which is 196executed only if the trace category is enabled. 197 198The most natural way to do this is to place the code inside the trace section 199itself because it already introduces such a conditional block. 200 201 OSSL_TRACE_BEGIN(TLS) { 202 int var = do_some_auxiliary_calculation(); 203 204 BIO_printf(trc_out, "var = %d\n", var); 205 206 } OSSL_TRACE_END(TLS); 207 208In some cases it is more advantageous to use a simple conditional group instead 209of a trace section. This is the case if calculations and tracing happen in 210different locations of the code, or if the calculations are so time consuming 211that placing them inside a (critical) trace section would create too much 212contention. 213 214 if (OSSL_TRACE_ENABLED(TLS)) { 215 int var = do_some_auxiliary_calculation(); 216 217 OSSL_TRACE1("var = %d\n", var); 218 } 219 220Note however that premature optimization of tracing code is in general futile 221and it's better to keep the tracing code as simple as possible. 222Because most often the limiting factor for the application's speed is the time 223it takes to print the trace output, not to calculate it. 224 225=head2 Configure Tracing 226 227By default, the OpenSSL library is built with tracing disabled. To 228use the tracing functionality documented here, it is therefore 229necessary to configure and build OpenSSL with the 'enable-trace' option. 230 231When the library is built with tracing disabled: 232 233=over 4 234 235=item * 236 237The macro B<OPENSSL_NO_TRACE> is defined in F<< <openssl/opensslconf.h> >>. 238 239=item * 240 241all functions are still present, but OSSL_trace_enabled() will always 242report the categories as disabled, and all other functions will do 243nothing. 244 245=item * 246 247the convenience macros are defined to produce dead code. 248For example, take this example from L</Macros> section above: 249 250 OSSL_TRACE_BEGIN(TLS) { 251 252 if (condition) { 253 OSSL_TRACE_CANCEL(TLS); 254 goto err; 255 } 256 BIO_fprintf(trc_out, ... ); 257 258 } OSSL_TRACE_END(TLS); 259 260When the tracing API isn't operational, that will expand to: 261 262 do { 263 BIO *trc_out = NULL; 264 if (0) { 265 if (condition) { 266 ((void)0); 267 goto err; 268 } 269 BIO_fprintf(trc_out, ... ); 270 } 271 } while (0); 272 273=back 274 275=head1 RETURN VALUES 276 277OSSL_trace_enabled() returns 1 if tracing for the given I<type> is 278operational and enabled, otherwise 0. 279 280OSSL_trace_begin() returns a B<BIO> pointer if the given I<type> is enabled, 281otherwise NULL. 282 283=head1 HISTORY 284 285The OpenSSL Tracing API was added in OpenSSL 3.0. 286 287=head1 COPYRIGHT 288 289Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 290 291Licensed under the Apache License 2.0 (the "License"). You may not use 292this file except in compliance with the License. You can obtain a copy 293in the file LICENSE in the source distribution or at 294L<https://www.openssl.org/source/license.html>. 295 296=cut 297