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