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