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