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</NOTES> 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 41=head2 Functions 42 43OSSL_trace_set_channel() is used to enable the given trace C<category> 44by attaching the B<BIO> I<bio> object as (simple) trace channel. 45On success the ownership of the BIO is transferred to the channel, 46so the caller must not free it directly. 47 48OSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add 49an extra line for each channel, to be output before and after group of 50tracing output. 51What constitutes an output group is decided by the code that produces 52the output. 53The lines given here are considered immutable; for more dynamic 54tracing prefixes, consider setting a callback with 55OSSL_trace_set_callback() instead. 56 57OSSL_trace_set_callback() is used to enable the given trace 58I<category> by giving it the tracer callback I<cb> with the associated 59data I<data>, which will simply be passed through to I<cb> whenever 60it's called. The callback function is internally wrapped by a 61dedicated BIO object, the so called I<callback trace channel>. 62This should be used when it's desirable to do form the trace output to 63something suitable for application needs where a prefix and suffix 64line aren't enough. 65 66OSSL_trace_set_channel() and OSSL_trace_set_callback() are mutually 67exclusive, calling one of them will clear whatever was set by the 68previous call. 69 70Calling OSSL_trace_set_channel() with NULL for I<channel> or 71OSSL_trace_set_callback() with NULL for I<cb> disables tracing for 72the given I<category>. 73 74=head2 Trace callback 75 76The tracer callback must return a B<size_t>, which must be zero on 77error and otherwise return the number of bytes that were output. 78It receives a text buffer I<buf> with I<cnt> bytes of text, as well as 79the I<category>, a control number I<cmd>, and the I<data> that was 80passed to OSSL_trace_set_callback(). 81 82The possible control numbers are: 83 84=over 4 85 86=item B<OSSL_TRACE_CTRL_BEGIN> 87 88The callback is called from OSSL_trace_begin(), which gives the 89callback the possibility to output a dynamic starting line, or set a 90prefix that should be output at the beginning of each line, or 91something other. 92 93=item B<OSSL_TRACE_CTRL_WRITE> 94 95This callback is called whenever data is written to the BIO by some 96regular BIO output routine. 97An arbitrary number of B<OSSL_TRACE_CTRL_WRITE> callbacks can occur 98inside a group marked by a pair of B<OSSL_TRACE_CTRL_BEGIN> and 99B<OSSL_TRACE_CTRL_END> calls, but never outside such a group. 100 101=item B<OSSL_TRACE_CTRL_END> 102 103The callback is called from OSSL_trace_end(), which gives the callback 104the possibility to output a dynamic ending line, or reset the line 105prefix that was set with B<OSSL_TRACE_CTRL_BEGIN>, or something other. 106 107=back 108 109=head2 Trace categories 110 111The trace categories are simple numbers available through macros. 112 113=over 4 114 115=item B<OSSL_TRACE_CATEGORY_TRACE> 116 117Traces the OpenSSL trace API itself. 118 119More precisely, this will generate trace output any time a new 120trace hook is set. 121 122=item B<OSSL_TRACE_CATEGORY_INIT> 123 124Traces OpenSSL library initialization and cleanup. 125 126This needs special care, as OpenSSL will do automatic cleanup after 127exit from C<main()>, and any tracing output done during this cleanup 128will be lost if the tracing channel or callback were cleaned away 129prematurely. 130A suggestion is to make such cleanup part of a function that's 131registered very early with L<atexit(3)>. 132 133=item B<OSSL_TRACE_CATEGORY_TLS> 134 135Traces the TLS/SSL protocol. 136 137=item B<OSSL_TRACE_CATEGORY_TLS_CIPHER> 138 139Traces the ciphers used by the TLS/SSL protocol. 140 141=item B<OSSL_TRACE_CATEGORY_CONF> 142 143Traces details about the provider and engine configuration. 144 145=item B<OSSL_TRACE_CATEGORY_ENGINE_TABLE> 146 147Traces the ENGINE algorithm table selection. 148 149More precisely, functions like ENGINE_get_pkey_asn1_meth_engine(), 150ENGINE_get_pkey_meth_engine(), ENGINE_get_cipher_engine(), 151ENGINE_get_digest_engine(), will generate trace summaries of the 152handling of internal tables. 153 154=item B<OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT> 155 156Traces the ENGINE reference counting. 157 158More precisely, both reference counts in the ENGINE structure will be 159monitored with a line of trace output generated for each change. 160 161=item B<OSSL_TRACE_CATEGORY_PKCS5V2> 162 163Traces PKCS#5 v2 key generation. 164 165=item B<OSSL_TRACE_CATEGORY_PKCS12_KEYGEN> 166 167Traces PKCS#12 key generation. 168 169=item B<OSSL_TRACE_CATEGORY_PKCS12_DECRYPT> 170 171Traces PKCS#12 decryption. 172 173=item B<OSSL_TRACE_CATEGORY_X509V3_POLICY> 174 175Traces X509v3 policy processing. 176 177More precisely, this generates the complete policy tree at various 178point during evaluation. 179 180=item B<OSSL_TRACE_CATEGORY_BN_CTX> 181 182Traces BIGNUM context operations. 183 184=item B<OSSL_TRACE_CATEGORY_CMP> 185 186Traces CMP client and server activity. 187 188=item B<OSSL_TRACE_CATEGORY_STORE> 189 190Traces STORE operations. 191 192=item B<OSSL_TRACE_CATEGORY_DECODER> 193 194Traces decoder operations. 195 196=item B<OSSL_TRACE_CATEGORY_ENCODER> 197 198Traces encoder operations. 199 200=item B<OSSL_TRACE_CATEGORY_REF_COUNT> 201 202Traces decrementing certain ASN.1 structure references. 203 204=back 205 206There is also B<OSSL_TRACE_CATEGORY_ALL>, which works as a fallback 207and can be used to get I<all> trace output. 208 209Note, however, that in this case all trace output will effectively be 210associated with the 'ALL' category, which is undesirable if the 211application intends to include the category name in the trace output. 212In this case it is better to register separate channels for each 213trace category instead. 214 215=head1 RETURN VALUES 216 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