doc/man3/OSSL_trace_set_channel.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_trace_set_channel, OSSL_trace_set_prefix, OSSL_trace_set_suffix,
   6 OSSL_trace_set_callback, OSSL_trace_cb - Enabling trace output
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/trace.h>
  11
  12  typedef size_t (*OSSL_trace_cb)(const char *buf, size_t cnt,
  13                                  int category, int cmd, void *data);
  14
  15  void OSSL_trace_set_channel(int category, BIO *bio);
  16  void OSSL_trace_set_prefix(int category, const char *prefix);
  17  void OSSL_trace_set_suffix(int category, const char *suffix);
  18  void OSSL_trace_set_callback(int category, OSSL_trace_cb cb, void  *data);
  19
  20 =head1 DESCRIPTION
  21
  22 If available (see L</NOTES> below), the application can request
  23 internal trace output.
  24 This output comes in form of free text for humans to read.
  25
  26 The trace output is divided into categories which can be
  27 enabled individually.
  28 They are enabled by giving them a channel in form of a BIO, or a
  29 tracer callback, which is responsible for performing the actual
  30 output.
  31
  32 =head2 Functions
  33
  34 OSSL_trace_set_channel() is used to enable the given trace C<category>
  35 by giving it the B<BIO> C<bio>.
  36
  37 OSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add
  38 an extra line for each channel, to be output before and after group of
  39 tracing output.
  40 What constitues an output group is decided by the code that produces
  41 the output.
  42 The lines given here are considered immutable; for more dynamic
  43 tracing prefixes, consider setting a callback with
  44 OSSL_trace_set_callback() instead.
  45
  46 OSSL_trace_set_callback() is used to enable the given trace
  47 C<category> by giving it the tracer callback C<cb> with the associated
  48 data C<data>, which will simply be passed through to C<cb> whenever
  49 it's called.
  50 This should be used when it's desirable to do form the trace output to
  51 something suitable for application needs where a prefix and suffix
  52 line aren't enough.
  53
  54 OSSL_trace_set_channel() and OSSL_trace_set_callback() are mutually
  55 exclusive, calling one of them will clear whatever was set by the
  56 previous call.
  57
  58 Calling OSSL_trace_set_channel() with C<NULL> for C<channel> or
  59 OSSL_trace_set_callback() with C<NULL> for C<cb> disables tracing for
  60 the given C<category>
  61
  62 =head2 Trace callback
  63
  64 The tracer callback must return a C<size_t>, which must be zero on
  65 error and otherwise return the number of bytes that were output.
  66 It receives a text buffer C<buf> with C<cnt> bytes of text, as well as
  67 the C<category>, a control number C<cmd>, and the C<data> that was
  68 passed to OSSL_trace_set_callback().
  69
  70 The possible control numbers are:
  71
  72 =over 4
  73
  74 =item C<OSSL_TRACE_CTRL_BEGIN>
  75
  76 The callback is called from OSSL_trace_begin(), which gives the
  77 callback the possibility to output a dynamic starting line, or set a
  78 prefix that should be output at the beginning of each line, or
  79 something other.
  80
  81 =item C<OSSL_TRACE_CTRL_DURING>
  82
  83 The callback is called from any regular BIO output routine.
  84
  85 =item C<OSSL_TRACE_CTRL_END>
  86
  87 The callback is called from OSSL_trace_end(), which gives the callback
  88 the possibility to output a dynamic ending line, or reset the line
  89 prefix that was set with OSSL_TRACE_CTRL_BEGIN, or something other.
  90
  91 =back
  92
  93 =head2 Trace categories
  94
  95 The trace categories are simple numbers available through macros.
  96
  97 =over 4
  98
  99 =item C<OSSL_TRACE_CATEGORY_TRACE>
 100
 101 Traces the OpenSSL trace API itself.
 102
 103 More precisely, this will generate trace output any time a new
 104 trace hook is set.
 105
 106 =item C<OSSL_TRACE_CATEGORY_INIT>
 107
 108 Traces OpenSSL library initialization and cleanup.
 109
 110 This needs special care, as OpenSSL will do automatic cleanup after
 111 exit from C<main()>, and any tracing output done during this cleanup
 112 will be lost if the tracing channel or callback were cleaned away
 113 prematurely.
 114 A suggestion is to make such cleanup part of a function that's
 115 registered very early with L<atexit(3)>.
 116
 117 =item C<OSSL_TRACE_CATEGORY_TLS>
 118
 119 Traces the TLS/SSL protocoll.
 120
 121 =item C<OSSL_TRACE_CATEGORY_TLS_CIPHER>
 122
 123 Traces the ciphers used by the TLS/SSL protocoll.
 124
 125 =item C<OSSL_TRACE_CATEGORY_ENGINE_CONF>
 126
 127 Traces the ENGINE configuration.
 128
 129 =item C<OSSL_TRACE_CATEGORY_ENGINE_TABLE>
 130
 131 Traces the ENGINE algorithm table selection.
 132
 133 More precisely, engine_table_select(), the function that is used by
 134 RSA, DSA (etc) code to select registered ENGINEs, cache defaults and
 135 functional references (etc), will generate trace summaries.
 136
 137 =item C<OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT>
 138
 139 Tracds the ENGINE reference counting.
 140
 141 More precisely, both reference counts in the ENGINE structure will be
 142 monitored with a line of trace output generated for each change.
 143
 144 =item C<OSSL_TRACE_CATEGORY_PKCS5V2>
 145
 146 Traces PKCS#5 v2 key generation.
 147
 148 =item C<OSSL_TRACE_CATEGORY_PKCS12_KEYGEN>
 149
 150 Traces PKCS#12 key generation.
 151
 152 =item C<OSSL_TRACE_CATEGORY_PKCS12_DECRYPT>
 153
 154 Traces PKCS#12 decryption.
 155
 156 =item C<OSSL_TRACE_CATEGORY_X509V3_POLICY>
 157
 158 Traces X509v3 policy processing.
 159
 160 More precisely, this generates the complete policy tree at various
 161 point during evaluation.
 162
 163 =item C<OSSL_TRACE_CATEGORY_BN_CTX>
 164
 165 Traces BIGNUM context operations.
 166
 167 =back
 168
 169 There is also C<OSSL_TRACE_CATEGORY_ANY>, which works as a fallback
 170 and can be used to get I<all> trace output.
 171
 172 =head1 RETURN VALUES
 173
 174 OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
 175 OSSL_trace_set_suffix(), and OSSL_trace_set_callback() return 1 on
 176 success, or 0 on failure.
 177
 178 =head1 EXAMPLES
 179
 180 In all examples below, we assume that the trace producing code is
 181 this:
 182
 183  int foo = 42;
 184  const char bar[] = { 0,  1,  2,  3,  4,  5,  6,  7,
 185                       8,  9, 10, 11, 12, 13, 14, 15 };
 186
 187  OSSL_TRACE_BEGIN(TLS) {
 188      BIO_puts(trc_out, "foo: ");
 189      BIO_printf(trc_out, "%d\n", foo);
 190      BIO_dump(trc_out, bar, sizeof(bar));
 191  } OSSL_TRACE_END(TLS);
 192
 193 =head1 Simple example
 194
 195 An example with just a channel and constant prefix / suffix.
 196
 197  int main(int argc, char *argv[])
 198  {
 199      BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT);
 200      OSSL_trace_set_channel(OSSL_TRACE_CATEGORY_SSL, err);
 201      OSSL_trace_set_prefix(OSSL_TRACE_CATEGORY_SSL, "BEGIN TRACE[TLS]");
 202      OSSL_trace_set_suffix(OSSL_TRACE_CATEGORY_SSL, "END TRACE[TLS]");
 203
 204      /* ... work ... */
 205  }
 206
 207 When the trace producing code above is performed, this will be output
 208 on standard error:
 209
 210  BEGIN TRACE[TLS]
 211  foo: 42
 212  0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f   ................
 213  END TRACE[TLS]
 214
 215 =head2 Advanced example
 216
 217 This example uses the callback, and depends on pthreads functionality.
 218
 219  static size_t cb(const char *buf, size_t cnt,
 220                  int category, int cmd, void *vdata)
 221  {
 222      BIO *bio = vdata;
 223      const char *label = NULL;
 224
 225      switch (cmd) {
 226      case OSSL_TRACE_CTRL_BEGIN:
 227          label = "BEGIN";
 228          break;
 229      case OSSL_TRACE_CTRL_END:
 230          label = "END";
 231          break;
 232      }
 233
 234      if (label != NULL) {
 235          union {
 236              pthread_t tid;
 237              unsigned long ltid;
 238          } tid;
 239
 240          tid.tid = pthread_self();
 241          BIO_printf(bio, "%s TRACE[%s]:%lx\n",
 242                     label, OSSL_trace_get_category_name(category), tid.ltid);
 243      }
 244      return (size_t)BIO_puts(bio, buf);
 245  }
 246
 247  int main(int argc, char *argv[])
 248  {
 249      BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT);
 250      OSSL_trace_set_callback(OSSL_TRACE_CATEGORY_SSL, cb, err);
 251
 252      /* ... work ... */
 253  }
 254
 255 The output is almost the same as for the simple example above.
 256
 257  BEGIN TRACE[TLS]:7f9eb0193b80
 258  foo: 42
 259  0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f   ................
 260  END TRACE[TLS]:7f9eb0193b80
 261
 262 =head1 NOTES
 263
 264 =head2 Tracing disabled
 265
 266 The OpenSSL library may be built with tracing disabled, which makes
 267 everything documented here inoperational.
 268
 269 When the library is built with tracing disabled, the macro
 270 C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all
 271 functions described here are inoperational, i.e. will do nothing.
 272
 273 =head1 HISTORY
 274
 275 OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
 276 OSSL_trace_set_suffix(), and OSSL_trace_set_callback() were all added
 277 in OpenSSL 3.0.0.
 278
 279 =head1 COPYRIGHT
 280
 281 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 282
 283 Licensed under the Apache License 2.0 (the "License").  You may not use
 284 this file except in compliance with the License.  You can obtain a copy
 285 in the file LICENSE in the source distribution or at
 286 L<https://www.openssl.org/source/license.html>.
 287
 288 =cut