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.
40 OSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add
42 an extra line for each channel, to be output before and after group of
43 tracing output. What constitues an output group is decided by the code
44 that produces the output. The lines given here are considered
45 immutable; for more dynamic tracing prefixes, consider setting a
46 callback with OSSL_trace_set_callback() instead.
47 OSSL_trace_set_callback() is used to enable the given trace category by
49 giving it the tracer callback cb with the associated data data, which
50 will simply be passed through to cb whenever it's called. The callback
51 function is internally wrapped by a dedicated BIO object, the so called
52 callback trace channel. This should be used when it's desirable to do
53 form the trace output to something suitable for application needs where
54 a prefix and suffix line aren't enough.
55 OSSL_trace_set_channel() and OSSL_trace_set_callback() are mutually
57 exclusive, calling one of them will clear whatever was set by the
58 previous call.
59 Calling OSSL_trace_set_channel() with NULL for channel or
61 OSSL_trace_set_callback() with NULL for cb disables tracing for the
62 given category.
63 Trace callback
65 The tracer callback must return a size_t, which must be zero on error
66 and otherwise return the number of bytes that were output. It receives
67 a text buffer buf with cnt bytes of text, as well as the category, a
68 control number cmd, and the data that was passed to
69 OSSL_trace_set_callback().
70 The possible control numbers are:
72 OSSL_TRACE_CTRL_BEGIN
74 The callback is called from OSSL_trace_begin(), which gives the
75 callback the possibility to output a dynamic starting line, or set
76 a prefix that should be output at the beginning of each line, or
77 something other.
78 OSSL_TRACE_CTRL_WRITE
80 This callback is called whenever data is written to the BIO by some
81 regular BIO output routine. An arbitrary number of
82 OSSL_TRACE_CTRL_WRITE callbacks can occur inside a group marked by
83 a pair of OSSL_TRACE_CTRL_BEGIN and OSSL_TRACE_CTRL_END calls, but
84 never outside such a group.
85 OSSL_TRACE_CTRL_END
87 The callback is called from OSSL_trace_end(), which gives the
88 callback the possibility to output a dynamic ending line, or reset
89 the line prefix that was set with OSSL_TRACE_CTRL_BEGIN, or
90 something other.
91 Trace categories
93 The trace categories are simple numbers available through macros.
94 OSSL_TRACE_CATEGORY_TRACE
96 Traces the OpenSSL trace API itself.
97 More precisely, this will generate trace output any time a new
99 trace hook is set.
100 OSSL_TRACE_CATEGORY_INIT
102 Traces OpenSSL library initialization and cleanup.
103 This needs special care, as OpenSSL will do automatic cleanup after
105 exit from "main()", and any tracing output done during this cleanup
106 will be lost if the tracing channel or callback were cleaned away
107 prematurely. A suggestion is to make such cleanup part of a
108 function that's registered very early with atexit(3).
109 OSSL_TRACE_CATEGORY_TLS
111 Traces the TLS/SSL protocol.
112 OSSL_TRACE_CATEGORY_TLS_CIPHER
114 Traces the ciphers used by the TLS/SSL protocol.
115 OSSL_TRACE_CATEGORY_ENGINE_TABLE
117 Traces the ENGINE algorithm table selection.
118 More precisely, functions like ENGINE_get_pkey_asn1_meth_engine(),
120 ENGINE_get_pkey_meth_engine(), ENGINE_get_cipher_engine(),
121 ENGINE_get_digest_engine(), will generate trace summaries of the
122 handling of internal tables.
123 OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT
125 Traces the ENGINE reference counting.
126 More precisely, both reference counts in the ENGINE structure will
128 be monitored with a line of trace output generated for each change.
129 OSSL_TRACE_CATEGORY_PKCS5V2
131 Traces PKCS#5 v2 key generation.
132 OSSL_TRACE_CATEGORY_PKCS12_KEYGEN
134 Traces PKCS#12 key generation.
135 OSSL_TRACE_CATEGORY_PKCS12_DECRYPT
137 Traces PKCS#12 decryption.
138 OSSL_TRACE_CATEGORY_X509V3_POLICY
140 Traces X509v3 policy processing.
141 More precisely, this generates the complete policy tree at various
143 point during evaluation.
144 OSSL_TRACE_CATEGORY_BN_CTX
146 Traces BIGNUM context operations.
147 OSSL_TRACE_CATEGORY_CONF
149 Traces details about the provider and engine configuration.
150 There is also OSSL_TRACE_CATEGORY_ALL, which works as a fallback and
152 can be used to get all trace output.
153 Note, however, that in this case all trace output will effectively be
155 associated with the 'ALL' category, which is undesirable if the
156 application intends to include the category name in the trace output.
157 In this case it is better to register separate channels for each trace
158 category instead.
159
161 OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
162 OSSL_trace_set_suffix(), and OSSL_trace_set_callback() return 1 on
163 success, or 0 on failure.
164
166 In all examples below, the trace producing code is assumed to be the
167 following:
168 int foo = 42;
170 const char bar[] = { 0, 1, 2, 3, 4, 5, 6, 7,
171 8, 9, 10, 11, 12, 13, 14, 15 };
172 OSSL_TRACE_BEGIN(TLS) {
174 BIO_puts(trc_out, "foo: ");
175 BIO_printf(trc_out, "%d\n", foo);
176 BIO_dump(trc_out, bar, sizeof(bar));
177 } OSSL_TRACE_END(TLS);
178 Simple example
180 An example with just a channel and constant prefix / suffix.
181 int main(int argc, char *argv[])
183 {
184 BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT);
185 OSSL_trace_set_channel(OSSL_TRACE_CATEGORY_SSL, err);
186 OSSL_trace_set_prefix(OSSL_TRACE_CATEGORY_SSL, "BEGIN TRACE[TLS]");
187 OSSL_trace_set_suffix(OSSL_TRACE_CATEGORY_SSL, "END TRACE[TLS]");
188 /* ... work ... */
190 }
191 When the trace producing code above is performed, this will be output
193 on standard error:
194 BEGIN TRACE[TLS]
196 foo: 42
197 0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f ................
198 END TRACE[TLS]
199 Advanced example
201 This example uses the callback, and depends on pthreads functionality.
202 static size_t cb(const char *buf, size_t cnt,
204 int category, int cmd, void *vdata)
205 {
206 BIO *bio = vdata;
207 const char *label = NULL;
208 switch (cmd) {
210 case OSSL_TRACE_CTRL_BEGIN:
211 label = "BEGIN";
212 break;
213 case OSSL_TRACE_CTRL_END:
214 label = "END";
215 break;
216 }
217 if (label != NULL) {
219 union {
220 pthread_t tid;
221 unsigned long ltid;
222 } tid;
223 tid.tid = pthread_self();
225 BIO_printf(bio, "%s TRACE[%s]:%lx\n",
226 label, OSSL_trace_get_category_name(category), tid.ltid);
227 }
228 return (size_t)BIO_puts(bio, buf);
229 }
230 int main(int argc, char *argv[])
232 {
233 BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT);
234 OSSL_trace_set_callback(OSSL_TRACE_CATEGORY_SSL, cb, err);
235 /* ... work ... */
237 }
238 The output is almost the same as for the simple example above.
240 BEGIN TRACE[TLS]:7f9eb0193b80
242 foo: 42
243 0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f ................
244 END TRACE[TLS]:7f9eb0193b80
245
247 Configure Tracing
248 By default, the OpenSSL library is built with tracing disabled. To use
249 the tracing functionality documented here, it is therefore necessary to
250 configure and build OpenSSL with the 'enable-trace' option.
251 When the library is built with tracing disabled, the macro
253 OPENSSL_NO_TRACE is defined in <openssl/opensslconf.h> and all
254 functions described here are inoperational, i.e. will do nothing.
255
257 OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
258 OSSL_trace_set_suffix(), and OSSL_trace_set_callback() were all added
259 in OpenSSL 3.0.
260
262 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
263 Licensed under the Apache License 2.0 (the "License"). You may not use
265 this file except in compliance with the License. You can obtain a copy
266 in the file LICENSE in the source distribution or at
267 <https://www.openssl.org/source/license.html>.
2683.0.5 2022-07-05 OSSL_TRACE_SET_CHANNEL(3ossl)