430 lines
16 KiB
Groff
430 lines
16 KiB
Groff
|
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
|
||
|
|
.\"
|
||
|
|
.\" Standard preamble:
|
||
|
|
.\" ========================================================================
|
||
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
||
|
|
.if t .sp .5v
|
||
|
|
.if n .sp
|
||
|
|
..
|
||
|
|
.de Vb \" Begin verbatim text
|
||
|
|
.ft CW
|
||
|
|
.nf
|
||
|
|
.ne \\$1
|
||
|
|
..
|
||
|
|
.de Ve \" End verbatim text
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
..
|
||
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
||
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
||
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
||
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
||
|
|
.\" nothing in troff, for use with C<>.
|
||
|
|
.tr \(*W-
|
||
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||
|
|
.ie n \{\
|
||
|
|
. ds -- \(*W-
|
||
|
|
. ds PI pi
|
||
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
||
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
||
|
|
. ds L" ""
|
||
|
|
. ds R" ""
|
||
|
|
. ds C` ""
|
||
|
|
. ds C' ""
|
||
|
|
'br\}
|
||
|
|
.el\{\
|
||
|
|
. ds -- \|\(em\|
|
||
|
|
. ds PI \(*p
|
||
|
|
. ds L" ``
|
||
|
|
. ds R" ''
|
||
|
|
'br\}
|
||
|
|
.\"
|
||
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
||
|
|
.ie \n(.g .ds Aq \(aq
|
||
|
|
.el .ds Aq '
|
||
|
|
.\"
|
||
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
||
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
||
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||
|
|
.\" output yourself in some meaningful fashion.
|
||
|
|
.ie \nF \{\
|
||
|
|
. de IX
|
||
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
||
|
|
..
|
||
|
|
. nr % 0
|
||
|
|
. rr F
|
||
|
|
.\}
|
||
|
|
.el \{\
|
||
|
|
. de IX
|
||
|
|
..
|
||
|
|
.\}
|
||
|
|
.\"
|
||
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||
|
|
. \" fudge factors for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds #H 0
|
||
|
|
. ds #V .8m
|
||
|
|
. ds #F .3m
|
||
|
|
. ds #[ \f1
|
||
|
|
. ds #] \fP
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
||
|
|
. ds #V .6m
|
||
|
|
. ds #F 0
|
||
|
|
. ds #[ \&
|
||
|
|
. ds #] \&
|
||
|
|
.\}
|
||
|
|
. \" simple accents for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds ' \&
|
||
|
|
. ds ` \&
|
||
|
|
. ds ^ \&
|
||
|
|
. ds , \&
|
||
|
|
. ds ~ ~
|
||
|
|
. ds /
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
||
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
||
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
||
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
||
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
||
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
||
|
|
.\}
|
||
|
|
. \" troff and (daisy-wheel) nroff accents
|
||
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
||
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
||
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
||
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
||
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
||
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
||
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
||
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
||
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
||
|
|
. \" corrections for vroff
|
||
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
||
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
||
|
|
. \" for low resolution devices (crt and lpr)
|
||
|
|
.if \n(.H>23 .if \n(.V>19 \
|
||
|
|
\{\
|
||
|
|
. ds : e
|
||
|
|
. ds 8 ss
|
||
|
|
. ds o a
|
||
|
|
. ds d- d\h'-1'\(ga
|
||
|
|
. ds D- D\h'-1'\(hy
|
||
|
|
. ds th \o'bp'
|
||
|
|
. ds Th \o'LP'
|
||
|
|
. ds ae ae
|
||
|
|
. ds Ae AE
|
||
|
|
.\}
|
||
|
|
.rm #[ #] #H #V #F C
|
||
|
|
.\" ========================================================================
|
||
|
|
.\"
|
||
|
|
.IX Title "OSSL_TRACE_SET_CHANNEL 3"
|
||
|
|
.TH OSSL_TRACE_SET_CHANNEL 3 "2020-03-02" "3.0.0-dev" "OpenSSL"
|
||
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||
|
|
.\" way too many mistakes in technical documents.
|
||
|
|
.if n .ad l
|
||
|
|
.nh
|
||
|
|
.SH "NAME"
|
||
|
|
OSSL_trace_set_channel, OSSL_trace_set_prefix, OSSL_trace_set_suffix,
|
||
|
|
OSSL_trace_set_callback, OSSL_trace_cb \- Enabling trace output
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.IX Header "SYNOPSIS"
|
||
|
|
.Vb 1
|
||
|
|
\& #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);
|
||
|
|
.Ve
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.IX Header "DESCRIPTION"
|
||
|
|
If available (see \*(L"\s-1NOTES\s0\*(R" below), the application can request
|
||
|
|
internal trace output.
|
||
|
|
This output comes in form of free text for humans to read.
|
||
|
|
.PP
|
||
|
|
The trace output is divided into categories which can be
|
||
|
|
enabled individually.
|
||
|
|
Every category can be enabled individually by attaching a so called
|
||
|
|
\&\fItrace channel\fR to it, which in the simplest case is just a \s-1BIO\s0 object
|
||
|
|
to which the application can write the tracing output for this category.
|
||
|
|
Alternatively, the application can provide a tracer callback in order to
|
||
|
|
get more finegrained trace information. This callback will be wrapped
|
||
|
|
internally by a dedicated \s-1BIO\s0 object.
|
||
|
|
.PP
|
||
|
|
For the tracing code, both trace channel types are indistinguishable.
|
||
|
|
These are called a \fIsimple trace channel\fR and a \fIcallback trace channel\fR,
|
||
|
|
respectively.
|
||
|
|
.SS "Functions"
|
||
|
|
.IX Subsection "Functions"
|
||
|
|
\&\fIOSSL_trace_set_channel()\fR is used to enable the given trace \f(CW\*(C`category\*(C'\fR
|
||
|
|
by attaching the \fB\s-1BIO\s0\fR \f(CW\*(C`bio\*(C'\fR object as (simple) trace channel.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_trace_set_prefix()\fR and \fIOSSL_trace_set_suffix()\fR 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
|
||
|
|
\&\fIOSSL_trace_set_callback()\fR instead.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_trace_set_callback()\fR is used to enable the given trace
|
||
|
|
\&\f(CW\*(C`category\*(C'\fR by giving it the tracer callback \f(CW\*(C`cb\*(C'\fR with the associated
|
||
|
|
data \f(CW\*(C`data\*(C'\fR, which will simply be passed through to \f(CW\*(C`cb\*(C'\fR whenever
|
||
|
|
it's called. The callback function is internally wrapped by a
|
||
|
|
dedicated \s-1BIO\s0 object, the so called \fIcallback trace channel\fR.
|
||
|
|
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.
|
||
|
|
.PP
|
||
|
|
\&\fIOSSL_trace_set_channel()\fR and \fIOSSL_trace_set_callback()\fR are mutually
|
||
|
|
exclusive, calling one of them will clear whatever was set by the
|
||
|
|
previous call.
|
||
|
|
.PP
|
||
|
|
Calling \fIOSSL_trace_set_channel()\fR with \f(CW\*(C`NULL\*(C'\fR for \f(CW\*(C`channel\*(C'\fR or
|
||
|
|
\&\fIOSSL_trace_set_callback()\fR with \f(CW\*(C`NULL\*(C'\fR for \f(CW\*(C`cb\*(C'\fR disables tracing for
|
||
|
|
the given \f(CW\*(C`category\*(C'\fR
|
||
|
|
.SS "Trace callback"
|
||
|
|
.IX Subsection "Trace callback"
|
||
|
|
The tracer callback must return a \f(CW\*(C`size_t\*(C'\fR, which must be zero on
|
||
|
|
error and otherwise return the number of bytes that were output.
|
||
|
|
It receives a text buffer \f(CW\*(C`buf\*(C'\fR with \f(CW\*(C`cnt\*(C'\fR bytes of text, as well as
|
||
|
|
the \f(CW\*(C`category\*(C'\fR, a control number \f(CW\*(C`cmd\*(C'\fR, and the \f(CW\*(C`data\*(C'\fR that was
|
||
|
|
passed to \fIOSSL_trace_set_callback()\fR.
|
||
|
|
.PP
|
||
|
|
The possible control numbers are:
|
||
|
|
.ie n .IP """OSSL_TRACE_CTRL_BEGIN""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CTRL_BEGIN\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CTRL_BEGIN"
|
||
|
|
The callback is called from \fIOSSL_trace_begin()\fR, 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.
|
||
|
|
.ie n .IP """OSSL_TRACE_CTRL_WRITE""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CTRL_WRITE\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CTRL_WRITE"
|
||
|
|
This callback is called whenever data is written to the \s-1BIO\s0 by some
|
||
|
|
regular \s-1BIO\s0 output routine.
|
||
|
|
An arbitrary number of \f(CW\*(C`OSSL_TRACE_CTRL_WRITE\*(C'\fR callbacks can occur
|
||
|
|
inside a group marked by a pair of \f(CW\*(C`OSSL_TRACE_CTRL_BEGIN\*(C'\fR and
|
||
|
|
\&\f(CW\*(C`OSSL_TRACE_CTRL_END\*(C'\fR calls, but never outside such a group.
|
||
|
|
.ie n .IP """OSSL_TRACE_CTRL_END""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CTRL_END\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CTRL_END"
|
||
|
|
The callback is called from \fIOSSL_trace_end()\fR, which gives the callback
|
||
|
|
the possibility to output a dynamic ending line, or reset the line
|
||
|
|
prefix that was set with \s-1OSSL_TRACE_CTRL_BEGIN\s0, or something other.
|
||
|
|
.SS "Trace categories"
|
||
|
|
.IX Subsection "Trace categories"
|
||
|
|
The trace categories are simple numbers available through macros.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_TRACE""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_TRACE\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_TRACE"
|
||
|
|
Traces the OpenSSL trace \s-1API\s0 itself.
|
||
|
|
.Sp
|
||
|
|
More precisely, this will generate trace output any time a new
|
||
|
|
trace hook is set.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_INIT""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_INIT\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_INIT"
|
||
|
|
Traces OpenSSL library initialization and cleanup.
|
||
|
|
.Sp
|
||
|
|
This needs special care, as OpenSSL will do automatic cleanup after
|
||
|
|
exit from \f(CW\*(C`main()\*(C'\fR, 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 \fIatexit\fR\|(3).
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_TLS""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_TLS\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_TLS"
|
||
|
|
Traces the \s-1TLS/SSL\s0 protocol.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_TLS_CIPHER""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_TLS_CIPHER\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_TLS_CIPHER"
|
||
|
|
Traces the ciphers used by the \s-1TLS/SSL\s0 protocol.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_ENGINE_CONF""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_ENGINE_CONF\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_ENGINE_CONF"
|
||
|
|
Traces the \s-1ENGINE\s0 configuration.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_ENGINE_TABLE""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_ENGINE_TABLE\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_ENGINE_TABLE"
|
||
|
|
Traces the \s-1ENGINE\s0 algorithm table selection.
|
||
|
|
.Sp
|
||
|
|
More precisely, \fIengine_table_select()\fR, the function that is used by
|
||
|
|
\&\s-1RSA\s0, \s-1DSA\s0 (etc) code to select registered ENGINEs, cache defaults and
|
||
|
|
functional references (etc), will generate trace summaries.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_ENGINE_REF_COUNT\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT"
|
||
|
|
Tracds the \s-1ENGINE\s0 reference counting.
|
||
|
|
.Sp
|
||
|
|
More precisely, both reference counts in the \s-1ENGINE\s0 structure will be
|
||
|
|
monitored with a line of trace output generated for each change.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_PKCS5V2""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_PKCS5V2\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_PKCS5V2"
|
||
|
|
Traces PKCS#5 v2 key generation.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_PKCS12_KEYGEN""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_PKCS12_KEYGEN\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_PKCS12_KEYGEN"
|
||
|
|
Traces PKCS#12 key generation.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_PKCS12_DECRYPT""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_PKCS12_DECRYPT\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_PKCS12_DECRYPT"
|
||
|
|
Traces PKCS#12 decryption.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_X509V3_POLICY""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_X509V3_POLICY\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_X509V3_POLICY"
|
||
|
|
Traces X509v3 policy processing.
|
||
|
|
.Sp
|
||
|
|
More precisely, this generates the complete policy tree at various
|
||
|
|
point during evaluation.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_BN_CTX""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_BN_CTX\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_BN_CTX"
|
||
|
|
Traces \s-1BIGNUM\s0 context operations.
|
||
|
|
.ie n .IP """OSSL_TRACE_CATEGORY_PROVIDER_CONF""" 4
|
||
|
|
.el .IP "\f(CWOSSL_TRACE_CATEGORY_PROVIDER_CONF\fR" 4
|
||
|
|
.IX Item "OSSL_TRACE_CATEGORY_PROVIDER_CONF"
|
||
|
|
Traces the \s-1OSSL_PROVIDER\s0 configuration.
|
||
|
|
.PP
|
||
|
|
There is also \f(CW\*(C`OSSL_TRACE_CATEGORY_ALL\*(C'\fR, which works as a fallback
|
||
|
|
and can be used to get \fIall\fR trace output.
|
||
|
|
.PP
|
||
|
|
Note, however, that in this case all trace output will effectively be
|
||
|
|
associated with the '\s-1ALL\s0' category, which is undesirable if the
|
||
|
|
application intends to include the category name in the trace output.
|
||
|
|
In this case it is better to register separate channels for each
|
||
|
|
trace category instead.
|
||
|
|
.SH "RETURN VALUES"
|
||
|
|
.IX Header "RETURN VALUES"
|
||
|
|
\&\fIOSSL_trace_set_channel()\fR, \fIOSSL_trace_set_prefix()\fR,
|
||
|
|
\&\fIOSSL_trace_set_suffix()\fR, and \fIOSSL_trace_set_callback()\fR return 1 on
|
||
|
|
success, or 0 on failure.
|
||
|
|
.SH "EXAMPLES"
|
||
|
|
.IX Header "EXAMPLES"
|
||
|
|
In all examples below, the trace producing code is assumed to be
|
||
|
|
the following:
|
||
|
|
.PP
|
||
|
|
.Vb 3
|
||
|
|
\& 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\en", foo);
|
||
|
|
\& BIO_dump(trc_out, bar, sizeof(bar));
|
||
|
|
\& } OSSL_TRACE_END(TLS);
|
||
|
|
.Ve
|
||
|
|
.SS "Simple example"
|
||
|
|
.IX Subsection "Simple example"
|
||
|
|
An example with just a channel and constant prefix / suffix.
|
||
|
|
.PP
|
||
|
|
.Vb 6
|
||
|
|
\& 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 ... */
|
||
|
|
\& }
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
When the trace producing code above is performed, this will be output
|
||
|
|
on standard error:
|
||
|
|
.PP
|
||
|
|
.Vb 4
|
||
|
|
\& 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]
|
||
|
|
.Ve
|
||
|
|
.SS "Advanced example"
|
||
|
|
.IX Subsection "Advanced example"
|
||
|
|
This example uses the callback, and depends on pthreads functionality.
|
||
|
|
.PP
|
||
|
|
.Vb 5
|
||
|
|
\& 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\en",
|
||
|
|
\& 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 ... */
|
||
|
|
\& }
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
The output is almost the same as for the simple example above.
|
||
|
|
.PP
|
||
|
|
.Vb 4
|
||
|
|
\& 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
|
||
|
|
.Ve
|
||
|
|
.SH "NOTES"
|
||
|
|
.IX Header "NOTES"
|
||
|
|
.SS "Configure Tracing"
|
||
|
|
.IX Subsection "Configure Tracing"
|
||
|
|
By default, the OpenSSL library is built with tracing disabled. To
|
||
|
|
use the tracing functionality documented here, it is therefore
|
||
|
|
necessary to configure and build OpenSSL with the 'enable\-trace' option.
|
||
|
|
.PP
|
||
|
|
When the library is built with tracing disabled, the macro
|
||
|
|
\&\f(CW\*(C`OPENSSL_NO_TRACE\*(C'\fR is defined in \f(CW\*(C`openssl/opensslconf.h\*(C'\fR and all
|
||
|
|
functions described here are inoperational, i.e. will do nothing.
|
||
|
|
.SH "HISTORY"
|
||
|
|
.IX Header "HISTORY"
|
||
|
|
\&\fIOSSL_trace_set_channel()\fR, \fIOSSL_trace_set_prefix()\fR,
|
||
|
|
\&\fIOSSL_trace_set_suffix()\fR, and \fIOSSL_trace_set_callback()\fR were all added
|
||
|
|
in OpenSSL 3.0.
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.IX Header "COPYRIGHT"
|
||
|
|
Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
|
||
|
|
.PP
|
||
|
|
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
|
||
|
|
this file except in compliance with the License. You can obtain a copy
|
||
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
||
|
|
<https://www.openssl.org/source/license.html>.
|