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