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