doc/man3/OSSL_trace_enabled.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end,
   6 OSSL_TRACE_BEGIN, OSSL_TRACE_END, OSSL_TRACE_CANCEL,
   7 OSSL_TRACE, OSSL_TRACE1, OSSL_TRACE2, OSSL_TRACE3, OSSL_TRACE4,
   8 OSSL_TRACE5, OSSL_TRACE6, OSSL_TRACE7, OSSL_TRACE8, OSSL_TRACE9,
   9 OSSL_TRACEV,
  10 OSSL_TRACE_STRING, OSSL_TRACE_STRING_MAX, OSSL_trace_string,
  11 OSSL_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
  55 The functions described here are mainly interesting for those who provide
  56 OpenSSL functionality, either in OpenSSL itself or in engine modules
  57 or similar.
  58
  59 If the tracing facility is enabled (see L</Configure Tracing> below),
  60 these functions are used to generate free text tracing output.
  61
  62 The tracing output is divided into types which are enabled
  63 individually by the application.
  64 The tracing types are described in detail in
  65 L<OSSL_trace_set_callback(3)/Trace types>.
  66 The fallback type B<OSSL_TRACE_CATEGORY_ALL> should I<not> be used
  67 with the functions described here.
  68
  69 Tracing for a specific category is enabled at run-time if a so-called
  70 I<trace channel> is attached to it. A trace channel is simply a
  71 BIO object to which the application can write its trace output.
  72
  73 The application has two different ways of registering a trace channel,
  74 either by directly providing a BIO object using L<OSSL_trace_set_channel(3)>,
  75 or by providing a callback routine using L<OSSL_trace_set_callback(3)>.
  76 The latter is wrapped internally by a dedicated BIO object, so for the
  77 tracing code both channel types are effectively indistinguishable.
  78 We call them a I<simple trace channel> and a I<callback trace channel>,
  79 respectively.
  80
  81 To produce trace output, it is necessary to obtain a pointer to the
  82 trace channel (i.e., the BIO object) using OSSL_trace_begin(), write
  83 to it using arbitrary BIO output routines, and finally releases the
  84 channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end()
  85 calls surrounding the trace output create a group, which acts as a
  86 critical section (guarded by a mutex) to ensure that the trace output
  87 of different threads does not get mixed up.
  88
  89 The tracing code normally does not call OSSL_trace_{begin,end}() directly,
  90 but rather uses a set of convenience macros, see the L</Macros> section below.
  91
  92
  93 =head2 Functions
  94
  95 OSSL_trace_enabled() can be used to check if tracing for the given
  96 I<category> is enabled, i.e., if the tracing facility has been statically
  97 enabled (see L</Configure Tracing> below) and a trace channel has been
  98 registered using L<OSSL_trace_set_channel(3)> or L<OSSL_trace_set_callback(3)>.
  99
 100 OSSL_trace_begin() is used to starts a tracing section, and get the
 101 channel for the given I<category> in form of a BIO.
 102 This BIO can only be used for output.
 103
 104 OSSL_trace_end() is used to end a tracing section.
 105
 106 Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections
 107 is I<mandatory>.
 108 The result of trying to produce tracing output outside of such
 109 sections is undefined.
 110
 111 OSSL_trace_string() outputs I<data> of length I<size> as a string on BIO I<out>.
 112 If I<text> is 0, the function masks any included control characters apart from
 113 newlines and makes sure for nonempty input that the output ends with a newline.
 114 Unless I<full> is nonzero, the length is limited (with a suitable warning)
 115 to B<OSSL_TRACE_STRING_MAX> characters, which currently is 80.
 116
 117 =head2 Macros
 118
 119 There are a number of convenience macros defined, to make tracing
 120 easy and consistent.
 121
 122 OSSL_TRACE_BEGIN() and OSSL_TRACE_END() reserve the B<BIO> C<trc_out> and are
 123 used 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
 131 This 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
 142 OSSL_TRACE_CANCEL() must be used before returning from or jumping out of a
 143 trace 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
 155 This 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
 170 OSSL_TRACE() and OSSL_TRACE1(), OSSL_TRACE2(), ... OSSL_TRACE9() are
 171 so-called one-shot macros:
 172
 173 The macro call C<OSSL_TRACE(category, text)>, produces literal text trace output.
 174
 175 The macro call C<OSSL_TRACEn(category, format, arg1, ..., argn)> produces
 176 printf-style trace output with n format field arguments (n=1,...,9).
 177 It expands to:
 178
 179  OSSL_TRACE_BEGIN(category) {
 180      BIO_printf(trc_out, format, arg1, ..., argN);
 181  } OSSL_TRACE_END(category)
 182
 183 Internally, all one-shot macros are implemented using a generic OSSL_TRACEV()
 184 macro, since C90 does not support variadic macros. This helper macro has a rather
 185 weird synopsis and should not be used directly.
 186
 187 The macro call C<OSSL_TRACE_STRING(category, text, full, data, len)>
 188 outputs I<data> of length I<size> as a string
 189 if tracing for the given I<category> is enabled.
 190 It expands to:
 191
 192  OSSL_TRACE_BEGIN(category) {
 193      OSSL_trace_string(trc_out, text, full, data, len);
 194  } OSSL_TRACE_END(category)
 195
 196 The OSSL_TRACE_ENABLED() macro can be used to conditionally execute some code
 197 only if a specific trace category is enabled.
 198 In some situations this is simpler than entering a trace section using
 199 OSSL_TRACE_BEGIN() and OSSL_TRACE_END().
 200 For example, the code
 201
 202  if (OSSL_TRACE_ENABLED(TLS)) {
 203      ...
 204  }
 205
 206 expands to
 207
 208  if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS) {
 209      ...
 210  }
 211
 212 =head1 NOTES
 213
 214 If producing the trace output requires carrying out auxiliary calculations,
 215 this auxiliary code should be placed inside a conditional block which is
 216 executed only if the trace category is enabled.
 217
 218 The most natural way to do this is to place the code inside the trace section
 219 itself 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
 228 In some cases it is more advantageous to use a simple conditional group instead
 229 of a trace section. This is the case if calculations and tracing happen in
 230 different locations of the code, or if the calculations are so time consuming
 231 that placing them inside a (critical) trace section would create too much
 232 contention.
 233
 234  if (OSSL_TRACE_ENABLED(TLS)) {
 235      int var = do_some_auxiliary_calculation();
 236
 237      OSSL_TRACE1("var = %d\n", var);
 238  }
 239
 240 Note however that premature optimization of tracing code is in general futile
 241 and it's better to keep the tracing code as simple as possible.
 242 Because most often the limiting factor for the application's speed is the time
 243 it takes to print the trace output, not to calculate it.
 244
 245 =head2 Configure Tracing
 246
 247 By default, the OpenSSL library is built with tracing disabled. To
 248 use the tracing functionality documented here, it is therefore
 249 necessary to configure and build OpenSSL with the 'enable-trace' option.
 250
 251 When the library is built with tracing disabled:
 252
 253 =over 4
 254
 255 =item *
 256
 257 The macro B<OPENSSL_NO_TRACE> is defined in F<< <openssl/opensslconf.h> >>.
 258
 259 =item *
 260
 261 all functions are still present, but OSSL_trace_enabled() will always
 262 report the categories as disabled, and all other functions will do
 263 nothing.
 264
 265 =item *
 266
 267 the convenience macros are defined to produce dead code.
 268 For 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
 280 When 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
 297 OSSL_trace_enabled() returns 1 if tracing for the given I<type> is
 298 operational and enabled, otherwise 0.
 299
 300 OSSL_trace_begin() returns a B<BIO> pointer if the given I<type> is enabled,
 301 otherwise NULL.
 302
 303 OSSL_trace_string() returns the number of characters emitted, or -1 on error.
 304
 305 =head1 SEE ALSO
 306
 307 L<OSSL_trace_set_channel(3)>, L<OSSL_trace_set_callback(3)>
 308
 309 =head1 HISTORY
 310
 311 The OpenSSL Tracing API was added in OpenSSL 3.0.
 312
 313 OSSL_TRACE_STRING(), OSSL_TRACE_STRING_MAX, and OSSL_trace_string
 314 were added in OpenSSL 3.2.
 315
 316 =head1 COPYRIGHT
 317
 318 Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
 319
 320 Licensed under the Apache License 2.0 (the "License").  You may not use
 321 this file except in compliance with the License.  You can obtain a copy
 322 in the file LICENSE in the source distribution or at
 323 L<https://www.openssl.org/source/license.html>.
 324
 325 =cut