Configure: disable new trace api by default
[openssl.git] / 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 Configure Tracing
265
266 By default, the OpenSSL library is built with tracing disabled. To
267 use the tracing functionality documented here, it is therefore
268 necessary to configure and build OpenSSL with the 'enable-trace' option.
269
270 When the library is built with tracing disabled, the macro
271 C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all
272 functions described here are inoperational, i.e. will do nothing.
273
274 =head1 HISTORY
275
276 OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
277 OSSL_trace_set_suffix(), and OSSL_trace_set_callback() were all added
278 in OpenSSL 3.0.0.
279
280 =head1 COPYRIGHT
281
282 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
283
284 Licensed under the Apache License 2.0 (the "License").  You may not use
285 this file except in compliance with the License.  You can obtain a copy
286 in the file LICENSE in the source distribution or at
287 L<https://www.openssl.org/source/license.html>.
288
289 =cut