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