doc/man3/OSSL_trace_enabled.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end
   6 - OpenSSL Tracing API
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/trace.h>
  11
  12  int OSSL_trace_enabled(int category);
  13
  14  BIO *OSSL_trace_begin(int category);
  15  void OSSL_trace_end(int category, BIO *channel);
  16
  17 =head1 DESCRIPTION
  18
  19 The functions described here are mainly interesting for those who provide
  20 OpenSSL functionality, either in OpenSSL itself or in engine modules
  21 or similar.
  22
  23 If tracing is enabled (see L</NOTES> below), these functions are used to
  24 generate free text tracing output.
  25
  26 The tracing output is divided into types which are enabled
  27 individually by the application.
  28 The tracing types are described in detail in
  29 L<OSSL_trace_set_callback(3)/Trace types>.
  30 The fallback type C<OSSL_TRACE_CATEGORY_ANY> should I<not> be used
  31 with the functions described here.
  32
  33 =head2 Functions
  34
  35 OSSL_trace_enabled() can be used to check if tracing for the given
  36 C<category> is enabled.
  37
  38 OSSL_trace_begin() is used to starts a tracing section, and get the
  39 channel for the given C<category> in form of a BIO.
  40 This BIO can only be used for output.
  41
  42 OSSL_trace_end() is used to end a tracing section.
  43
  44 Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections
  45 is I<mandatory>.
  46 The result of trying to produce tracing output outside of such
  47 sections is undefined.
  48
  49 =head2 Convenience Macros
  50
  51 There are a number of convenience macros defined, to make tracing
  52 easy and consistent.
  53
  54 C<OSSL_TRACE_BEGIN(category)> and C<OSSL_TRACE_END(category)> reserve
  55 the B<BIO> C<trc_out> and are used as follows to wrap a trace section:
  56
  57  OSSL_TRACE_BEGIN(TLS) {
  58
  59      BIO_fprintf(trc_out, ... );
  60
  61  } OSSL_TRACE_END(TLS);
  62
  63 This will normally expands to:
  64
  65  do {
  66      BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
  67      if (trc_out != NULL) {
  68          ...
  69          BIO_fprintf(trc_out, ...);
  70      }
  71      OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
  72  } while (0);
  73
  74 C<OSSL_TRACE_CANCEL(category)> must be used before returning from or
  75 jumping out of a trace section:
  76
  77  OSSL_TRACE_BEGIN(TLS) {
  78
  79      if (condition) {
  80          OSSL_TRACE_CANCEL(TLS);
  81          goto err;
  82      }
  83      BIO_fprintf(trc_out, ... );
  84
  85  } OSSL_TRACE_END(TLS);
  86
  87 This will normally expand to:
  88
  89  do {
  90      BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
  91      if (trc_out != NULL) {
  92          if (condition) {
  93              OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
  94              goto err;
  95          }
  96          BIO_fprintf(trc_out, ... );
  97      }
  98      OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
  99  } while (0);
 100
 101 =head1 NOTES
 102
 103 It is advisable to always check that a trace type is enabled with
 104 OSSL_trace_enabled() before generating any output, for example:
 105
 106     if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS)) {
 107         BIO *trace = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
 108         BIO_printf(trace, "FOO %d\n", somevalue);
 109         BIO_dump(trace, somememory, somememory_l);
 110         OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trace);
 111     }
 112
 113 =head2 Configure Tracing
 114
 115 By default, the OpenSSL library is built with tracing disabled. To
 116 use the tracing functionality documented here, it is therefore
 117 necessary to configure and build OpenSSL with the 'enable-trace' option.
 118
 119 When the library is built with tracing disabled:
 120
 121 =over 4
 122
 123 =item *
 124
 125 The macro C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h>.
 126
 127 =item *
 128
 129 all functions are still present, bu OSSL_trace_enabled() will always
 130 report the categories as disabled, and all other functions will do
 131 nothing.
 132
 133 =item *
 134
 135 the convenience macros are defined to produce dead code.
 136 For example, take this example from L</Convenience Macros> above:
 137
 138  OSSL_TRACE_BEGIN(TLS) {
 139
 140      if (condition) {
 141          OSSL_TRACE_CANCEL(TLS);
 142          goto err;
 143      }
 144      BIO_fprintf(trc_out, ... );
 145
 146  } OSSL_TRACE_END(TLS);
 147
 148 When the tracing API isn't operational, that will expand to:
 149
 150  do {
 151      BIO *trc_out = NULL;
 152      if (0) {
 153          if (condition) {
 154              ((void)0);
 155              goto err;
 156          }
 157          BIO_fprintf(trc_out, ... );
 158      }
 159  } while (0);
 160
 161 =back
 162
 163 =head1 RETURN VALUES
 164
 165 OSSL_trace_enabled() returns 1 if tracing for the given B<type> is
 166 operational and enabled, otherwise 0.
 167
 168 OSSL_trace_begin() returns a C<BIO *> if the given B<type> is enabled,
 169 otherwise C<NULL>.
 170
 171 =head1 HISTORY
 172
 173 The OpenSSL Tracing API was added ino OpenSSL 3.0.0.
 174
 175 =head1 COPYRIGHT
 176
 177 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 178
 179 Licensed under the Apache License 2.0 (the "License").  You may not use
 180 this file except in compliance with the License.  You can obtain a copy
 181 in the file LICENSE in the source distribution or at
 182 L<https://www.openssl.org/source/license.html>.
 183
 184 =cut