5 OSSL_trace_set_channel, OSSL_trace_set_prefix, OSSL_trace_set_suffix,
6 OSSL_trace_set_callback, OSSL_trace_cb - Enabling trace output
10 #include <openssl/trace.h>
12 typedef size_t (*OSSL_trace_cb)(const char *buf, size_t cnt,
13 int category, int cmd, void *data);
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);
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.
26 The trace output is divided into categories which can be
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
34 OSSL_trace_set_channel() is used to enable the given trace C<category>
35 by giving it the B<BIO> C<bio>.
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
40 What constitues an output group is decided by the code that produces
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.
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
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
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
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
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().
70 The possible control numbers are:
74 =item C<OSSL_TRACE_CTRL_BEGIN>
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
81 =item C<OSSL_TRACE_CTRL_DURING>
83 The callback is called from any regular BIO output routine.
85 =item C<OSSL_TRACE_CTRL_END>
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.
93 =head2 Trace categories
95 The trace categories are simple numbers available through macros.
99 =item C<OSSL_TRACE_CATEGORY_TRACE>
101 Traces the OpenSSL trace API itself.
103 More precisely, this will generate trace output any time a new
106 =item C<OSSL_TRACE_CATEGORY_INIT>
108 Traces OpenSSL library initialization and cleanup.
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
114 A suggestion is to make such cleanup part of a function that's
115 registered very early with L<atexit(3)>.
117 =item C<OSSL_TRACE_CATEGORY_TLS>
119 Traces the TLS/SSL protocoll.
121 =item C<OSSL_TRACE_CATEGORY_TLS_CIPHER>
123 Traces the ciphers used by the TLS/SSL protocoll.
125 =item C<OSSL_TRACE_CATEGORY_ENGINE_CONF>
127 Traces the ENGINE configuration.
129 =item C<OSSL_TRACE_CATEGORY_ENGINE_TABLE>
131 Traces the ENGINE algorithm table selection.
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.
137 =item C<OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT>
139 Tracds the ENGINE reference counting.
141 More precisely, both reference counts in the ENGINE structure will be
142 monitored with a line of trace output generated for each change.
144 =item C<OSSL_TRACE_CATEGORY_PKCS5V2>
146 Traces PKCS#5 v2 key generation.
148 =item C<OSSL_TRACE_CATEGORY_PKCS12_KEYGEN>
150 Traces PKCS#12 key generation.
152 =item C<OSSL_TRACE_CATEGORY_PKCS12_DECRYPT>
154 Traces PKCS#12 decryption.
156 =item C<OSSL_TRACE_CATEGORY_X509V3_POLICY>
158 Traces X509v3 policy processing.
160 More precisely, this generates the complete policy tree at various
161 point during evaluation.
163 =item C<OSSL_TRACE_CATEGORY_BN_CTX>
165 Traces BIGNUM context operations.
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.
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.
180 In all examples below, we assume that the trace producing code is
184 const char bar[] = { 0, 1, 2, 3, 4, 5, 6, 7,
185 8, 9, 10, 11, 12, 13, 14, 15 };
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);
193 =head1 Simple example
195 An example with just a channel and constant prefix / suffix.
197 int main(int argc, char *argv[])
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]");
207 When the trace producing code above is performed, this will be output
212 0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f ................
215 =head2 Advanced example
217 This example uses the callback, and depends on pthreads functionality.
219 static size_t cb(const char *buf, size_t cnt,
220 int category, int cmd, void *vdata)
223 const char *label = NULL;
226 case OSSL_TRACE_CTRL_BEGIN:
229 case OSSL_TRACE_CTRL_END:
240 tid.tid = pthread_self();
241 BIO_printf(bio, "%s TRACE[%s]:%lx\n",
242 label, OSSL_trace_get_category_name(category), tid.ltid);
244 return (size_t)BIO_puts(bio, buf);
247 int main(int argc, char *argv[])
249 BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT);
250 OSSL_trace_set_callback(OSSL_TRACE_CATEGORY_SSL, cb, err);
255 The output is almost the same as for the simple example above.
257 BEGIN TRACE[TLS]:7f9eb0193b80
259 0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f ................
260 END TRACE[TLS]:7f9eb0193b80
264 =head2 Tracing disabled
266 The OpenSSL library may be built with tracing disabled, which makes
267 everything documented here inoperational.
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.
275 OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
276 OSSL_trace_set_suffix(), and OSSL_trace_set_callback() were all added
281 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
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>.