18813Srgallard=pod 212442Smfang 312442Smfang=for openssl foreign manual atexit(3) 412442Smfang 512442Smfang=head1 NAME 612442Smfang 712442SmfangOSSL_trace_set_channel, OSSL_trace_set_prefix, OSSL_trace_set_suffix, 812442SmfangOSSL_trace_set_callback, OSSL_trace_cb - Enabling trace output 912442Smfang 1012442Smfang=head1 SYNOPSIS 1112442Smfang 1212442Smfang #include <openssl/trace.h> 1312442Smfang 1412442Smfang typedef size_t (*OSSL_trace_cb)(const char *buf, size_t cnt, 1512442Smfang int category, int cmd, void *data); 1612442Smfang 1712442Smfang void OSSL_trace_set_channel(int category, BIO *bio); 1812442Smfang void OSSL_trace_set_prefix(int category, const char *prefix); 1912442Smfang void OSSL_trace_set_suffix(int category, const char *suffix); 2012442Smfang void OSSL_trace_set_callback(int category, OSSL_trace_cb cb, void *data); 2112442Smfang 2212442Smfang=head1 DESCRIPTION 238813Srgallard 248813SrgallardIf available (see L</NOTES> below), the application can request 258813Srgallardinternal trace output. 268813SrgallardThis output comes in form of free text for humans to read. 278813Srgallard 288813SrgallardThe trace output is divided into categories which can be 298813Srgallardenabled individually. 308813SrgallardEvery category can be enabled individually by attaching a so called 3112442SmfangI<trace channel> to it, which in the simplest case is just a BIO object 3212442Smfangto which the application can write the tracing output for this category. 3312442SmfangAlternatively, the application can provide a tracer callback in order to 3412442Smfangget more finegrained trace information. This callback will be wrapped 3512442Smfanginternally by a dedicated BIO object. 3612442Smfang 3712442SmfangFor the tracing code, both trace channel types are indistinguishable. 3812442SmfangThese are called a I<simple trace channel> and a I<callback trace channel>, 3912442Smfangrespectively. 4012442Smfang 4112442Smfang=head2 Functions 4212442Smfang 4312442SmfangOSSL_trace_set_channel() is used to enable the given trace C<category> 4412442Smfangby attaching the B<BIO> I<bio> object as (simple) trace channel. 4512442SmfangOn success the ownership of the BIO is transferred to the channel, 4612442Smfangso the caller must not free it directly. 4712442Smfang 4812442SmfangOSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add 4912442Smfangan extra line for each channel, to be output before and after group of 500Sduketracing output. 518813SrgallardWhat constitutes an output group is decided by the code that produces 528813Srgallardthe output. 538813SrgallardThe lines given here are considered immutable; for more dynamic 548813Srgallardtracing prefixes, consider setting a callback with 558813SrgallardOSSL_trace_set_callback() instead. 568813Srgallard 578813SrgallardOSSL_trace_set_callback() is used to enable the given trace 588813SrgallardI<category> by giving it the tracer callback I<cb> with the associated 598813Srgallarddata I<data>, which will simply be passed through to I<cb> whenever 608813Srgallardit's called. The callback function is internally wrapped by a 618813Srgallarddedicated BIO object, the so called I<callback trace channel>. 628813SrgallardThis should be used when it's desirable to do form the trace output to 638813Srgallardsomething suitable for application needs where a prefix and suffix 648813Srgallardline aren't enough. 658813Srgallard 668813SrgallardOSSL_trace_set_channel() and OSSL_trace_set_callback() are mutually 678813Srgallardexclusive, calling one of them will clear whatever was set by the 688813Srgallardprevious call. 698813Srgallard 708813SrgallardCalling OSSL_trace_set_channel() with NULL for I<channel> or 718813SrgallardOSSL_trace_set_callback() with NULL for I<cb> disables tracing for 728813Srgallardthe given I<category>. 738813Srgallard 748813Srgallard=head2 Trace callback 758813Srgallard 768813SrgallardThe tracer callback must return a B<size_t>, which must be zero on 778813Srgallarderror and otherwise return the number of bytes that were output. 788813SrgallardIt receives a text buffer I<buf> with I<cnt> bytes of text, as well as 798813Srgallardthe I<category>, a control number I<cmd>, and the I<data> that was 808813Srgallardpassed to OSSL_trace_set_callback(). 818813Srgallard 828813SrgallardThe possible control numbers are: 838813Srgallard 848813Srgallard=over 4 858813Srgallard 868813Srgallard=item B<OSSL_TRACE_CTRL_BEGIN> 878813Srgallard 888813SrgallardThe callback is called from OSSL_trace_begin(), which gives the 898813Srgallardcallback the possibility to output a dynamic starting line, or set a 908813Srgallardprefix that should be output at the beginning of each line, or 918813Srgallardsomething other. 928813Srgallard 938813Srgallard=item B<OSSL_TRACE_CTRL_WRITE> 948813Srgallard 958813SrgallardThis callback is called whenever data is written to the BIO by some 968813Srgallardregular BIO output routine. 978813SrgallardAn arbitrary number of B<OSSL_TRACE_CTRL_WRITE> callbacks can occur 988813Srgallardinside a group marked by a pair of B<OSSL_TRACE_CTRL_BEGIN> and 998813SrgallardB<OSSL_TRACE_CTRL_END> calls, but never outside such a group. 1008813Srgallard 1018813Srgallard=item B<OSSL_TRACE_CTRL_END> 1028813Srgallard 1038813SrgallardThe callback is called from OSSL_trace_end(), which gives the callback 1048813Srgallardthe possibility to output a dynamic ending line, or reset the line 1058813Srgallardprefix that was set with B<OSSL_TRACE_CTRL_BEGIN>, or something other. 1068813Srgallard 1071178Stbell=back 1088813Srgallard 1098813Srgallard=head2 Trace categories 1108813Srgallard 1118813SrgallardThe trace categories are simple numbers available through macros. 1128813Srgallard 1138813Srgallard=over 4 1148813Srgallard 1158813Srgallard=item B<OSSL_TRACE_CATEGORY_TRACE> 1168813Srgallard 1178813SrgallardTraces the OpenSSL trace API itself. 1188813Srgallard 1198813SrgallardMore precisely, this will generate trace output any time a new 1208813Srgallardtrace hook is set. 1218813Srgallard 1228813Srgallard=item B<OSSL_TRACE_CATEGORY_INIT> 1238813Srgallard 1248813SrgallardTraces OpenSSL library initialization and cleanup. 1258813Srgallard 1268813SrgallardThis needs special care, as OpenSSL will do automatic cleanup after 1278813Srgallardexit from C<main()>, and any tracing output done during this cleanup 1288813Srgallardwill be lost if the tracing channel or callback were cleaned away 1298813Srgallardprematurely. 1308813SrgallardA suggestion is to make such cleanup part of a function that's 1318813Srgallardregistered very early with L<atexit(3)>. 1328813Srgallard 1338813Srgallard=item B<OSSL_TRACE_CATEGORY_TLS> 1348813Srgallard 1358813SrgallardTraces the TLS/SSL protocol. 1368813Srgallard 1378813Srgallard=item B<OSSL_TRACE_CATEGORY_TLS_CIPHER> 1388813Srgallard 1398813SrgallardTraces the ciphers used by the TLS/SSL protocol. 1408813Srgallard 1418813Srgallard=item B<OSSL_TRACE_CATEGORY_CONF> 1428813Srgallard 1438813SrgallardTraces details about the provider and engine configuration. 1448813Srgallard 1458813Srgallard=item B<OSSL_TRACE_CATEGORY_ENGINE_TABLE> 1468813Srgallard 1478813SrgallardTraces the ENGINE algorithm table selection. 1488813Srgallard 1498813SrgallardMore precisely, functions like ENGINE_get_pkey_asn1_meth_engine(), 1508813SrgallardENGINE_get_pkey_meth_engine(), ENGINE_get_cipher_engine(), 1518813SrgallardENGINE_get_digest_engine(), will generate trace summaries of the 1528813Srgallardhandling of internal tables. 1538813Srgallard 1548813Srgallard=item B<OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT> 1558813Srgallard 1568813SrgallardTraces the ENGINE reference counting. 1578813Srgallard 1588813SrgallardMore precisely, both reference counts in the ENGINE structure will be 1594176Sbpatelmonitored with a line of trace output generated for each change. 1608813Srgallard 1618813Srgallard=item B<OSSL_TRACE_CATEGORY_PKCS5V2> 1628813Srgallard 1634176SbpatelTraces PKCS#5 v2 key generation. 1648813Srgallard 1658813Srgallard=item B<OSSL_TRACE_CATEGORY_PKCS12_KEYGEN> 1668813Srgallard 1678813SrgallardTraces PKCS#12 key generation. 1688813Srgallard 1698813Srgallard=item B<OSSL_TRACE_CATEGORY_PKCS12_DECRYPT> 1704176Sbpatel 1718813SrgallardTraces PKCS#12 decryption. 1728813Srgallard 1738813Srgallard=item B<OSSL_TRACE_CATEGORY_X509V3_POLICY> 1744176Sbpatel 1758813SrgallardTraces X509v3 policy processing. 1768813Srgallard 1778813SrgallardMore precisely, this generates the complete policy tree at various 1788813Srgallardpoint during evaluation. 1798813Srgallard 1804176Sbpatel=item B<OSSL_TRACE_CATEGORY_BN_CTX> 1818813Srgallard 1828813SrgallardTraces BIGNUM context operations. 1838813Srgallard 1844176Sbpatel=item B<OSSL_TRACE_CATEGORY_CMP> 1858813Srgallard 1868813SrgallardTraces CMP client and server activity. 1878813Srgallard 1884176Sbpatel=item B<OSSL_TRACE_CATEGORY_STORE> 1898813Srgallard 1908813SrgallardTraces STORE operations. 1918813Srgallard 1928813Srgallard=item B<OSSL_TRACE_CATEGORY_DECODER> 1938813Srgallard 1948813SrgallardTraces decoder operations. 1958813Srgallard 1968813Srgallard=item B<OSSL_TRACE_CATEGORY_ENCODER> 1978813Srgallard 1988813SrgallardTraces encoder operations. 1998813Srgallard 2008813Srgallard=item B<OSSL_TRACE_CATEGORY_REF_COUNT> 2018813Srgallard 2028813SrgallardTraces decrementing certain ASN.1 structure references. 2038813Srgallard 2048813Srgallard=back 2058813Srgallard 2068813SrgallardThere is also B<OSSL_TRACE_CATEGORY_ALL>, which works as a fallback 2078813Srgallardand can be used to get I<all> trace output. 2088813Srgallard 2098813SrgallardNote, however, that in this case all trace output will effectively be 2108813Srgallardassociated with the 'ALL' category, which is undesirable if the 2118813Srgallardapplication intends to include the category name in the trace output. 2128813SrgallardIn this case it is better to register separate channels for each 21312442Smfangtrace category instead. 21412442Smfang 21512442Smfang=head1 RETURN VALUES 21612442Smfang 217OSSL_trace_set_channel(), OSSL_trace_set_prefix(), 218OSSL_trace_set_suffix(), and OSSL_trace_set_callback() return 1 on 219success, or 0 on failure. 220 221=head1 EXAMPLES 222 223In all examples below, the trace producing code is assumed to be 224the following: 225 226 int foo = 42; 227 const char bar[] = { 0, 1, 2, 3, 4, 5, 6, 7, 228 8, 9, 10, 11, 12, 13, 14, 15 }; 229 230 OSSL_TRACE_BEGIN(TLS) { 231 BIO_puts(trc_out, "foo: "); 232 BIO_printf(trc_out, "%d\n", foo); 233 BIO_dump(trc_out, bar, sizeof(bar)); 234 } OSSL_TRACE_END(TLS); 235 236=head2 Simple example 237 238An example with just a channel and constant prefix / suffix. 239 240 int main(int argc, char *argv[]) 241 { 242 BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT); 243 OSSL_trace_set_channel(OSSL_TRACE_CATEGORY_SSL, err); 244 OSSL_trace_set_prefix(OSSL_TRACE_CATEGORY_SSL, "BEGIN TRACE[TLS]"); 245 OSSL_trace_set_suffix(OSSL_TRACE_CATEGORY_SSL, "END TRACE[TLS]"); 246 247 /* ... work ... */ 248 } 249 250When the trace producing code above is performed, this will be output 251on standard error: 252 253 BEGIN TRACE[TLS] 254 foo: 42 255 0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f ................ 256 END TRACE[TLS] 257 258=head2 Advanced example 259 260This example uses the callback, and depends on pthreads functionality. 261 262 static size_t cb(const char *buf, size_t cnt, 263 int category, int cmd, void *vdata) 264 { 265 BIO *bio = vdata; 266 const char *label = NULL; 267 268 switch (cmd) { 269 case OSSL_TRACE_CTRL_BEGIN: 270 label = "BEGIN"; 271 break; 272 case OSSL_TRACE_CTRL_END: 273 label = "END"; 274 break; 275 } 276 277 if (label != NULL) { 278 union { 279 pthread_t tid; 280 unsigned long ltid; 281 } tid; 282 283 tid.tid = pthread_self(); 284 BIO_printf(bio, "%s TRACE[%s]:%lx\n", 285 label, OSSL_trace_get_category_name(category), tid.ltid); 286 } 287 return (size_t)BIO_puts(bio, buf); 288 } 289 290 int main(int argc, char *argv[]) 291 { 292 BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT); 293 OSSL_trace_set_callback(OSSL_TRACE_CATEGORY_SSL, cb, err); 294 295 /* ... work ... */ 296 } 297 298The output is almost the same as for the simple example above. 299 300 BEGIN TRACE[TLS]:7f9eb0193b80 301 foo: 42 302 0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f ................ 303 END TRACE[TLS]:7f9eb0193b80 304 305=head1 NOTES 306 307=head2 Configure Tracing 308 309By default, the OpenSSL library is built with tracing disabled. To 310use the tracing functionality documented here, it is therefore 311necessary to configure and build OpenSSL with the 'enable-trace' option. 312 313When the library is built with tracing disabled, the macro 314B<OPENSSL_NO_TRACE> is defined in F<< <openssl/opensslconf.h> >> and all 315functions described here are inoperational, i.e. will do nothing. 316 317=head1 HISTORY 318 319OSSL_trace_set_channel(), OSSL_trace_set_prefix(), 320OSSL_trace_set_suffix(), and OSSL_trace_set_callback() were all added 321in OpenSSL 3.0. 322 323=head1 COPYRIGHT 324 325Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. 326 327Licensed under the Apache License 2.0 (the "License"). You may not use 328this file except in compliance with the License. You can obtain a copy 329in the file LICENSE in the source distribution or at 330L<https://www.openssl.org/source/license.html>. 331 332=cut 333