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_TRACE1, OSSL_TRACE2, OSSL_TRACE9
   7 - OpenSSL Tracing API
   8
   9 =head1 SYNOPSIS
  10
  11  #include <openssl/trace.h>
  12
  13  int OSSL_trace_enabled(int category);
  14
  15  BIO *OSSL_trace_begin(int category);
  16  void OSSL_trace_end(int category, BIO *channel);
  17
  18  /* trace group macros */
  19  OSSL_TRACE_BEGIN(category) {
  20     ...
  21  } OSSL_TRACE_END(category);
  22
  23  /* one-shot trace macros */
  24  OSSL_TRACE1(category, format, arg1)
  25  OSSL_TRACE2(category, format, arg1, arg2)
  26  ...
  27  OSSL_TRACE9(category, format, arg1, ..., arg9)
  28
  29
  30 =head1 DESCRIPTION
  31
  32 The functions described here are mainly interesting for those who provide
  33 OpenSSL functionality, either in OpenSSL itself or in engine modules
  34 or similar.
  35
  36 If tracing is enabled (see L</NOTES> below), these functions are used to
  37 generate free text tracing output.
  38
  39 The tracing output is divided into types which are enabled
  40 individually by the application.
  41 The tracing types are described in detail in
  42 L<OSSL_trace_set_callback(3)/Trace types>.
  43 The fallback type C<OSSL_TRACE_CATEGORY_ALL> should I<not> be used
  44 with the functions described here.
  45
  46 Tracing for a specific category is enabled if a so called
  47 I<trace channel> is attached to it. A trace channel is simply a
  48 BIO object to which the application can write its trace output.
  49
  50 The application has two different ways of registering a trace channel,
  51 either by directly providing a BIO object using OSSL_trace_set_channel(),
  52 or by providing a callback routine using OSSL_trace_set_callback().
  53 The latter is wrapped internally by a dedicated BIO object, so for the
  54 tracing code both channel types are effectively indistinguishable.
  55 We call them a I<simple trace channel> and a I<callback trace channel>,
  56 respectively.
  57
  58 To produce trace output, it is necessary to obtain a pointer to the
  59 trace channel (i.e., the BIO object) using OSSL_trace_begin(), write
  60 to it using arbitrary BIO output routines, and finally releases the
  61 channel using OSSL_trace_end(). The OSSL_trace_begin()/OSSL_trace_end()
  62 calls surrounding the trace output create a group, which acts as a
  63 critical section (guarded by a mutex) to ensure that the trace output
  64 of different threads does not get mixed up.
  65
  66 The tracing code normally does not call OSSL_trace_{begin,end}() directly,
  67 but rather uses a set of convenience macros, see the L</Macros> section below.
  68
  69
  70 =head2 Functions
  71
  72 OSSL_trace_enabled() can be used to check if tracing for the given
  73 C<category> is enabled.
  74
  75 OSSL_trace_begin() is used to starts a tracing section, and get the
  76 channel for the given C<category> in form of a BIO.
  77 This BIO can only be used for output.
  78
  79 OSSL_trace_end() is used to end a tracing section.
  80
  81 Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections
  82 is I<mandatory>.
  83 The result of trying to produce tracing output outside of such
  84 sections is undefined.
  85
  86 =head2 Macros
  87
  88 There are a number of convenience macros defined, to make tracing
  89 easy and consistent.
  90
  91 C<OSSL_TRACE_BEGIN(category)> and C<OSSL_TRACE_END(category)> reserve
  92 the B<BIO> C<trc_out> and are used as follows to wrap a trace section:
  93
  94  OSSL_TRACE_BEGIN(TLS) {
  95
  96      BIO_fprintf(trc_out, ... );
  97
  98  } OSSL_TRACE_END(TLS);
  99
 100 This will normally expand to:
 101
 102  do {
 103      BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
 104      if (trc_out != NULL) {
 105          ...
 106          BIO_fprintf(trc_out, ...);
 107      }
 108      OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
 109  } while (0);
 110
 111 C<OSSL_TRACE_CANCEL(category)> must be used before returning from or
 112 jumping out of a trace section:
 113
 114  OSSL_TRACE_BEGIN(TLS) {
 115
 116      if (condition) {
 117          OSSL_TRACE_CANCEL(TLS);
 118          goto err;
 119      }
 120      BIO_fprintf(trc_out, ... );
 121
 122  } OSSL_TRACE_END(TLS);
 123
 124 This will normally expand to:
 125
 126  do {
 127      BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
 128      if (trc_out != NULL) {
 129          if (condition) {
 130              OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
 131              goto err;
 132          }
 133          BIO_fprintf(trc_out, ... );
 134      }
 135      OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
 136  } while (0);
 137
 138
 139 C<OSSL_TRACE1()>, ... C<OSSL_TRACE9()> are one-shot macros which essentially wrap
 140 a single BIO_printf() into a tracing group.
 141
 142 The call OSSL_TRACEn(category, format, arg1, ..., argN) expands to:
 143
 144   OSSL_TRACE_BEGIN(category) {
 145     BIO_printf(trc_out, format, arg1, ..., argN)
 146   } OSSL_TRACE_END(category)
 147
 148 =head1 NOTES
 149
 150 It is advisable to always check that a trace type is enabled with
 151 OSSL_trace_enabled() before generating any output, for example:
 152
 153     if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS)) {
 154         BIO *trace = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
 155         BIO_printf(trace, "FOO %d\n", somevalue);
 156         BIO_dump(trace, somememory, somememory_l);
 157         OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trace);
 158     }
 159
 160 =head2 Configure Tracing
 161
 162 By default, the OpenSSL library is built with tracing disabled. To
 163 use the tracing functionality documented here, it is therefore
 164 necessary to configure and build OpenSSL with the 'enable-trace' option.
 165
 166 When the library is built with tracing disabled:
 167
 168 =over 4
 169
 170 =item *
 171
 172 The macro C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h>.
 173
 174 =item *
 175
 176 all functions are still present, bu OSSL_trace_enabled() will always
 177 report the categories as disabled, and all other functions will do
 178 nothing.
 179
 180 =item *
 181
 182 the convenience macros are defined to produce dead code.
 183 For example, take this example from L</Macros> section above:
 184
 185  OSSL_TRACE_BEGIN(TLS) {
 186
 187      if (condition) {
 188          OSSL_TRACE_CANCEL(TLS);
 189          goto err;
 190      }
 191      BIO_fprintf(trc_out, ... );
 192
 193  } OSSL_TRACE_END(TLS);
 194
 195 When the tracing API isn't operational, that will expand to:
 196
 197  do {
 198      BIO *trc_out = NULL;
 199      if (0) {
 200          if (condition) {
 201              ((void)0);
 202              goto err;
 203          }
 204          BIO_fprintf(trc_out, ... );
 205      }
 206  } while (0);
 207
 208 =back
 209
 210 =head1 RETURN VALUES
 211
 212 OSSL_trace_enabled() returns 1 if tracing for the given B<type> is
 213 operational and enabled, otherwise 0.
 214
 215 OSSL_trace_begin() returns a C<BIO *> if the given B<type> is enabled,
 216 otherwise C<NULL>.
 217
 218 =head1 HISTORY
 219
 220 The OpenSSL Tracing API was added ino OpenSSL 3.0.0.
 221
 222 =head1 COPYRIGHT
 223
 224 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 225
 226 Licensed under the Apache License 2.0 (the "License").  You may not use
 227 this file except in compliance with the License.  You can obtain a copy
 228 in the file LICENSE in the source distribution or at
 229 L<https://www.openssl.org/source/license.html>.
 230
 231 =cut