mirror of
https://github.com/openssl/openssl.git
synced 2024-11-27 05:21:51 +08:00
0b836c2168
Co-authored-by: Dr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/8198)
289 lines
8.1 KiB
Plaintext
289 lines
8.1 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSL_trace_set_channel, OSSL_trace_set_prefix, OSSL_trace_set_suffix,
|
|
OSSL_trace_set_callback, OSSL_trace_cb - Enabling trace output
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/trace.h>
|
|
|
|
typedef size_t (*OSSL_trace_cb)(const char *buf, size_t cnt,
|
|
int category, int cmd, void *data);
|
|
|
|
void OSSL_trace_set_channel(int category, BIO *bio);
|
|
void OSSL_trace_set_prefix(int category, const char *prefix);
|
|
void OSSL_trace_set_suffix(int category, const char *suffix);
|
|
void OSSL_trace_set_callback(int category, OSSL_trace_cb cb, void *data);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
If available (see L</NOTES> below), the application can request
|
|
internal trace output.
|
|
This output comes in form of free text for humans to read.
|
|
|
|
The trace output is divided into categories which can be
|
|
enabled individually.
|
|
They are enabled by giving them a channel in form of a BIO, or a
|
|
tracer callback, which is responsible for performing the actual
|
|
output.
|
|
|
|
=head2 Functions
|
|
|
|
OSSL_trace_set_channel() is used to enable the given trace C<category>
|
|
by giving it the B<BIO> C<bio>.
|
|
|
|
OSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add
|
|
an extra line for each channel, to be output before and after group of
|
|
tracing output.
|
|
What constitues an output group is decided by the code that produces
|
|
the output.
|
|
The lines given here are considered immutable; for more dynamic
|
|
tracing prefixes, consider setting a callback with
|
|
OSSL_trace_set_callback() instead.
|
|
|
|
OSSL_trace_set_callback() is used to enable the given trace
|
|
C<category> by giving it the tracer callback C<cb> with the associated
|
|
data C<data>, which will simply be passed through to C<cb> whenever
|
|
it's called.
|
|
This should be used when it's desirable to do form the trace output to
|
|
something suitable for application needs where a prefix and suffix
|
|
line aren't enough.
|
|
|
|
OSSL_trace_set_channel() and OSSL_trace_set_callback() are mutually
|
|
exclusive, calling one of them will clear whatever was set by the
|
|
previous call.
|
|
|
|
Calling OSSL_trace_set_channel() with C<NULL> for C<channel> or
|
|
OSSL_trace_set_callback() with C<NULL> for C<cb> disables tracing for
|
|
the given C<category>
|
|
|
|
=head2 Trace callback
|
|
|
|
The tracer callback must return a C<size_t>, which must be zero on
|
|
error and otherwise return the number of bytes that were output.
|
|
It receives a text buffer C<buf> with C<cnt> bytes of text, as well as
|
|
the C<category>, a control number C<cmd>, and the C<data> that was
|
|
passed to OSSL_trace_set_callback().
|
|
|
|
The possible control numbers are:
|
|
|
|
=over 4
|
|
|
|
=item C<OSSL_TRACE_CTRL_BEGIN>
|
|
|
|
The callback is called from OSSL_trace_begin(), which gives the
|
|
callback the possibility to output a dynamic starting line, or set a
|
|
prefix that should be output at the beginning of each line, or
|
|
something other.
|
|
|
|
=item C<OSSL_TRACE_CTRL_DURING>
|
|
|
|
The callback is called from any regular BIO output routine.
|
|
|
|
=item C<OSSL_TRACE_CTRL_END>
|
|
|
|
The callback is called from OSSL_trace_end(), which gives the callback
|
|
the possibility to output a dynamic ending line, or reset the line
|
|
prefix that was set with OSSL_TRACE_CTRL_BEGIN, or something other.
|
|
|
|
=back
|
|
|
|
=head2 Trace categories
|
|
|
|
The trace categories are simple numbers available through macros.
|
|
|
|
=over 4
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_TRACE>
|
|
|
|
Traces the OpenSSL trace API itself.
|
|
|
|
More precisely, this will generate trace output any time a new
|
|
trace hook is set.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_INIT>
|
|
|
|
Traces OpenSSL library initialization and cleanup.
|
|
|
|
This needs special care, as OpenSSL will do automatic cleanup after
|
|
exit from C<main()>, and any tracing output done during this cleanup
|
|
will be lost if the tracing channel or callback were cleaned away
|
|
prematurely.
|
|
A suggestion is to make such cleanup part of a function that's
|
|
registered very early with L<atexit(3)>.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_TLS>
|
|
|
|
Traces the TLS/SSL protocoll.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_TLS_CIPHER>
|
|
|
|
Traces the ciphers used by the TLS/SSL protocoll.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_ENGINE_CONF>
|
|
|
|
Traces the ENGINE configuration.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_ENGINE_TABLE>
|
|
|
|
Traces the ENGINE algorithm table selection.
|
|
|
|
More precisely, engine_table_select(), the function that is used by
|
|
RSA, DSA (etc) code to select registered ENGINEs, cache defaults and
|
|
functional references (etc), will generate trace summaries.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT>
|
|
|
|
Tracds the ENGINE reference counting.
|
|
|
|
More precisely, both reference counts in the ENGINE structure will be
|
|
monitored with a line of trace output generated for each change.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_PKCS5V2>
|
|
|
|
Traces PKCS#5 v2 key generation.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_PKCS12_KEYGEN>
|
|
|
|
Traces PKCS#12 key generation.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_PKCS12_DECRYPT>
|
|
|
|
Traces PKCS#12 decryption.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_X509V3_POLICY>
|
|
|
|
Traces X509v3 policy processing.
|
|
|
|
More precisely, this generates the complete policy tree at various
|
|
point during evaluation.
|
|
|
|
=item C<OSSL_TRACE_CATEGORY_BN_CTX>
|
|
|
|
Traces BIGNUM context operations.
|
|
|
|
=back
|
|
|
|
There is also C<OSSL_TRACE_CATEGORY_ANY>, which works as a fallback
|
|
and can be used to get I<all> trace output.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
|
|
OSSL_trace_set_suffix(), and OSSL_trace_set_callback() return 1 on
|
|
success, or 0 on failure.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
In all examples below, we assume that the trace producing code is
|
|
this:
|
|
|
|
int foo = 42;
|
|
const char bar[] = { 0, 1, 2, 3, 4, 5, 6, 7,
|
|
8, 9, 10, 11, 12, 13, 14, 15 };
|
|
|
|
OSSL_TRACE_BEGIN(TLS) {
|
|
BIO_puts(trc_out, "foo: ");
|
|
BIO_printf(trc_out, "%d\n", foo);
|
|
BIO_dump(trc_out, bar, sizeof(bar));
|
|
} OSSL_TRACE_END(TLS);
|
|
|
|
=head1 Simple example
|
|
|
|
An example with just a channel and constant prefix / suffix.
|
|
|
|
int main(int argc, char *argv[])
|
|
{
|
|
BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT);
|
|
OSSL_trace_set_channel(OSSL_TRACE_CATEGORY_SSL, err);
|
|
OSSL_trace_set_prefix(OSSL_TRACE_CATEGORY_SSL, "BEGIN TRACE[TLS]");
|
|
OSSL_trace_set_suffix(OSSL_TRACE_CATEGORY_SSL, "END TRACE[TLS]");
|
|
|
|
/* ... work ... */
|
|
}
|
|
|
|
When the trace producing code above is performed, this will be output
|
|
on standard error:
|
|
|
|
BEGIN TRACE[TLS]
|
|
foo: 42
|
|
0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f ................
|
|
END TRACE[TLS]
|
|
|
|
=head2 Advanced example
|
|
|
|
This example uses the callback, and depends on pthreads functionality.
|
|
|
|
static size_t cb(const char *buf, size_t cnt,
|
|
int category, int cmd, void *vdata)
|
|
{
|
|
BIO *bio = vdata;
|
|
const char *label = NULL;
|
|
|
|
switch (cmd) {
|
|
case OSSL_TRACE_CTRL_BEGIN:
|
|
label = "BEGIN";
|
|
break;
|
|
case OSSL_TRACE_CTRL_END:
|
|
label = "END";
|
|
break;
|
|
}
|
|
|
|
if (label != NULL) {
|
|
union {
|
|
pthread_t tid;
|
|
unsigned long ltid;
|
|
} tid;
|
|
|
|
tid.tid = pthread_self();
|
|
BIO_printf(bio, "%s TRACE[%s]:%lx\n",
|
|
label, OSSL_trace_get_category_name(category), tid.ltid);
|
|
}
|
|
return (size_t)BIO_puts(bio, buf);
|
|
}
|
|
|
|
int main(int argc, char *argv[])
|
|
{
|
|
BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT);
|
|
OSSL_trace_set_callback(OSSL_TRACE_CATEGORY_SSL, cb, err);
|
|
|
|
/* ... work ... */
|
|
}
|
|
|
|
The output is almost the same as for the simple example above.
|
|
|
|
BEGIN TRACE[TLS]:7f9eb0193b80
|
|
foo: 42
|
|
0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f ................
|
|
END TRACE[TLS]:7f9eb0193b80
|
|
|
|
=head1 NOTES
|
|
|
|
=head2 Tracing disabled
|
|
|
|
The OpenSSL library may be built with tracing disabled, which makes
|
|
everything documented here inoperational.
|
|
|
|
When the library is built with tracing disabled, the macro
|
|
C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all
|
|
functions described here are inoperational, i.e. will do nothing.
|
|
|
|
=head1 HISTORY
|
|
|
|
OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
|
|
OSSL_trace_set_suffix(), and OSSL_trace_set_callback() were all added
|
|
in OpenSSL 3.0.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|