1=pod
2
3=for openssl foreign manual atexit(3)
4
5=head1 NAME
6
7OSSL_trace_set_channel, OSSL_trace_set_prefix, OSSL_trace_set_suffix,
8OSSL_trace_set_callback, OSSL_trace_cb - Enabling trace output
9
10=head1 SYNOPSIS
11
12 #include <openssl/trace.h>
13
14 typedef size_t (*OSSL_trace_cb)(const char *buf, size_t cnt,
15                                 int category, int cmd, void *data);
16
17 void OSSL_trace_set_channel(int category, BIO *bio);
18 void OSSL_trace_set_prefix(int category, const char *prefix);
19 void OSSL_trace_set_suffix(int category, const char *suffix);
20 void OSSL_trace_set_callback(int category, OSSL_trace_cb cb, void  *data);
21
22=head1 DESCRIPTION
23
24If available (see L</Configure Tracing> below), the application can request
25internal trace output.
26This output comes in form of free text for humans to read.
27
28The trace output is divided into categories which can be
29enabled individually.
30Every category can be enabled individually by attaching a so-called
31I<trace channel> to it, which in the simplest case is just a BIO object
32to which the application can write the tracing output for this category.
33Alternatively, the application can provide a tracer callback in order to
34get more finegrained trace information. This callback will be wrapped
35internally by a dedicated BIO object.
36
37For the tracing code, both trace channel types are indistinguishable.
38These are called a I<simple trace channel> and a I<callback trace channel>,
39respectively.
40
41L<OSSL_TRACE_ENABLED(3)> can be used to check whether tracing is currently
42enabled for the given category.
43Functions like L<OSSL_TRACE1(3)> and macros like L<OSSL_TRACE_BEGIN(3)>
44can be used for producing free-text trace output.
45
46=head2 Functions
47
48OSSL_trace_set_channel() is used to enable the given trace C<category>
49by attaching the B<BIO> I<bio> object as (simple) trace channel.
50
51OSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add
52an extra line for each channel, to be output before and after group of
53tracing output.
54What constitutes an output group is decided by the code that produces
55the output.
56The lines given here are considered immutable; for more dynamic
57tracing prefixes, consider setting a callback with
58OSSL_trace_set_callback() instead.
59
60OSSL_trace_set_callback() is used to enable the given trace
61I<category> by giving it the tracer callback I<cb> with the associated
62data I<data>, which will simply be passed through to I<cb> whenever
63it's called. The callback function is internally wrapped by a
64dedicated BIO object, the so-called I<callback trace channel>.
65This should be used when it's desirable to do form the trace output to
66something suitable for application needs where a prefix and suffix
67line aren't enough.
68
69OSSL_trace_set_channel() and OSSL_trace_set_callback() are mutually
70exclusive, calling one of them will clear whatever was set by the
71previous call.
72
73Calling OSSL_trace_set_channel() with NULL for I<channel> or
74OSSL_trace_set_callback() with NULL for I<cb> disables tracing for
75the given I<category>.
76
77=head2 Trace callback
78
79The tracer callback must return a B<size_t>, which must be zero on
80error and otherwise return the number of bytes that were output.
81It receives a text buffer I<buf> with I<cnt> bytes of text, as well as
82the I<category>, a control number I<cmd>, and the I<data> that was
83passed to OSSL_trace_set_callback().
84
85The possible control numbers are:
86
87=over 4
88
89=item B<OSSL_TRACE_CTRL_BEGIN>
90
91The callback is called from OSSL_trace_begin(), which gives the
92callback the possibility to output a dynamic starting line, or set a
93prefix that should be output at the beginning of each line, or
94something other.
95
96=item B<OSSL_TRACE_CTRL_WRITE>
97
98This callback is called whenever data is written to the BIO by some
99regular BIO output routine.
100An arbitrary number of B<OSSL_TRACE_CTRL_WRITE> callbacks can occur
101inside a group marked by a pair of B<OSSL_TRACE_CTRL_BEGIN> and
102B<OSSL_TRACE_CTRL_END> calls, but never outside such a group.
103
104=item B<OSSL_TRACE_CTRL_END>
105
106The callback is called from OSSL_trace_end(), which gives the callback
107the possibility to output a dynamic ending line, or reset the line
108prefix that was set with B<OSSL_TRACE_CTRL_BEGIN>, or something other.
109
110=back
111
112=head2 Trace categories
113
114The trace categories are simple numbers available through macros.
115
116=over 4
117
118=item B<OSSL_TRACE_CATEGORY_TRACE>
119
120Traces the OpenSSL trace API itself.
121
122More precisely, this will generate trace output any time a new
123trace hook is set.
124
125=item B<OSSL_TRACE_CATEGORY_INIT>
126
127Traces OpenSSL library initialization and cleanup.
128
129This needs special care, as OpenSSL will do automatic cleanup after
130exit from C<main()>, and any tracing output done during this cleanup
131will be lost if the tracing channel or callback were cleaned away
132prematurely.
133A suggestion is to make such cleanup part of a function that's
134registered very early with L<atexit(3)>.
135
136=item B<OSSL_TRACE_CATEGORY_TLS>
137
138Traces the TLS/SSL protocol.
139
140=item B<OSSL_TRACE_CATEGORY_TLS_CIPHER>
141
142Traces the ciphers used by the TLS/SSL protocol.
143
144=item B<OSSL_TRACE_CATEGORY_CONF>
145
146Traces details about the provider and engine configuration.
147
148=item B<OSSL_TRACE_CATEGORY_ENGINE_TABLE>
149
150Traces the ENGINE algorithm table selection.
151
152More precisely, functions like ENGINE_get_pkey_asn1_meth_engine(),
153ENGINE_get_pkey_meth_engine(), ENGINE_get_cipher_engine(),
154ENGINE_get_digest_engine(), will generate trace summaries of the
155handling of internal tables.
156
157=item B<OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT>
158
159Traces the ENGINE reference counting.
160
161More precisely, both reference counts in the ENGINE structure will be
162monitored with a line of trace output generated for each change.
163
164=item B<OSSL_TRACE_CATEGORY_PKCS5V2>
165
166Traces PKCS#5 v2 key generation.
167
168=item B<OSSL_TRACE_CATEGORY_PKCS12_KEYGEN>
169
170Traces PKCS#12 key generation.
171
172=item B<OSSL_TRACE_CATEGORY_PKCS12_DECRYPT>
173
174Traces PKCS#12 decryption.
175
176=item B<OSSL_TRACE_CATEGORY_X509V3_POLICY>
177
178Traces X509v3 policy processing.
179
180More precisely, this generates the complete policy tree at various
181point during evaluation.
182
183=item B<OSSL_TRACE_CATEGORY_BN_CTX>
184
185Traces BIGNUM context operations.
186
187=item B<OSSL_TRACE_CATEGORY_CMP>
188
189Traces CMP client and server activity.
190
191=item B<OSSL_TRACE_CATEGORY_STORE>
192
193Traces STORE operations.
194
195=item B<OSSL_TRACE_CATEGORY_DECODER>
196
197Traces decoder operations.
198
199=item B<OSSL_TRACE_CATEGORY_ENCODER>
200
201Traces encoder operations.
202
203=item B<OSSL_TRACE_CATEGORY_REF_COUNT>
204
205Traces decrementing certain ASN.1 structure references.
206
207=item B<OSSL_TRACE_CATEGORY_HTTP>
208
209Traces the HTTP client, such as message headers being sent and received.
210
211=back
212
213There is also B<OSSL_TRACE_CATEGORY_ALL>, which works as a fallback
214and can be used to get I<all> trace output.
215
216Note, however, that in this case all trace output will effectively be
217associated with the 'ALL' category, which is undesirable if the
218application intends to include the category name in the trace output.
219In this case it is better to register separate channels for each
220trace category instead.
221
222=head1 RETURN VALUES
223
224OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
225OSSL_trace_set_suffix(), and OSSL_trace_set_callback() return 1 on
226success, or 0 on failure.
227
228=head1 EXAMPLES
229
230In all examples below, the trace producing code is assumed to be
231the following:
232
233 int foo = 42;
234 const char bar[] = { 0,  1,  2,  3,  4,  5,  6,  7,
235                      8,  9, 10, 11, 12, 13, 14, 15 };
236
237 OSSL_TRACE_BEGIN(TLS) {
238     BIO_puts(trc_out, "foo: ");
239     BIO_printf(trc_out, "%d\n", foo);
240     BIO_dump(trc_out, bar, sizeof(bar));
241 } OSSL_TRACE_END(TLS);
242
243=head2 Simple example
244
245An example with just a channel and constant prefix / suffix.
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_channel(OSSL_TRACE_CATEGORY_SSL, err);
251     OSSL_trace_set_prefix(OSSL_TRACE_CATEGORY_SSL, "BEGIN TRACE[TLS]");
252     OSSL_trace_set_suffix(OSSL_TRACE_CATEGORY_SSL, "END TRACE[TLS]");
253
254     /* ... work ... */
255 }
256
257When the trace producing code above is performed, this will be output
258on standard error:
259
260 BEGIN TRACE[TLS]
261 foo: 42
262 0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f   ................
263 END TRACE[TLS]
264
265=head2 Advanced example
266
267This example uses the callback, and depends on pthreads functionality.
268
269 static size_t cb(const char *buf, size_t cnt,
270                 int category, int cmd, void *vdata)
271 {
272     BIO *bio = vdata;
273     const char *label = NULL;
274
275     switch (cmd) {
276     case OSSL_TRACE_CTRL_BEGIN:
277         label = "BEGIN";
278         break;
279     case OSSL_TRACE_CTRL_END:
280         label = "END";
281         break;
282     }
283
284     if (label != NULL) {
285         union {
286             pthread_t tid;
287             unsigned long ltid;
288         } tid;
289
290         tid.tid = pthread_self();
291         BIO_printf(bio, "%s TRACE[%s]:%lx\n",
292                    label, OSSL_trace_get_category_name(category), tid.ltid);
293     }
294     return (size_t)BIO_puts(bio, buf);
295 }
296
297 int main(int argc, char *argv[])
298 {
299     BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT);
300     OSSL_trace_set_callback(OSSL_TRACE_CATEGORY_SSL, cb, err);
301
302     /* ... work ... */
303 }
304
305The output is almost the same as for the simple example above.
306
307 BEGIN TRACE[TLS]:7f9eb0193b80
308 foo: 42
309 0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f   ................
310 END TRACE[TLS]:7f9eb0193b80
311
312=head1 NOTES
313
314=head2 Configure Tracing
315
316By default, the OpenSSL library is built with tracing disabled. To
317use the tracing functionality documented here, it is therefore
318necessary to configure and build OpenSSL with the 'enable-trace' option.
319
320When the library is built with tracing disabled, the macro
321B<OPENSSL_NO_TRACE> is defined in F<< <openssl/opensslconf.h> >> and all
322functions described here are inoperational, i.e. will do nothing.
323
324=head1 SEE ALSO
325
326L<OSSL_TRACE_ENABLED(3)>, L<OSSL_TRACE_BEGIN(3)>, L<OSSL_TRACE1(3)>,
327L<atexit(3)>
328
329=head1 HISTORY
330
331OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
332OSSL_trace_set_suffix(), and OSSL_trace_set_callback() were all added
333in OpenSSL 3.0.
334
335=head1 COPYRIGHT
336
337Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
338
339Licensed under the Apache License 2.0 (the "License").  You may not use
340this file except in compliance with the License.  You can obtain a copy
341in the file LICENSE in the source distribution or at
342L<https://www.openssl.org/source/license.html>.
343
344=cut
345