1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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" ''
. ds C`
. ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" 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_CMP_LOG_OPEN 3ossl"
.TH OSSL_CMP_LOG_OPEN 3ossl "2023-09-19" "3.0.11" "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_CMP_log_open,
OSSL_CMP_log_close,
OSSL_CMP_severity,
OSSL_CMP_LOG_EMERG,
OSSL_CMP_LOG_ALERT,
OSSL_CMP_LOG_CRIT,
OSSL_CMP_LOG_ERR,
OSSL_CMP_LOG_WARNING,
OSSL_CMP_LOG_NOTICE,
OSSL_CMP_LOG_INFO,
OSSL_CMP_LOG_DEBUG,
OSSL_CMP_LOG_TRACE,
.PP
OSSL_CMP_log_cb_t,
OSSL_CMP_print_to_bio,
OSSL_CMP_print_errors_cb
\&\- functions for logging and error reporting
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/cmp_util.h>
\&
\& int OSSL_CMP_log_open(void);
\& void OSSL_CMP_log_close(void);
\&
\& /* severity level declarations resemble those from syslog.h */
\& typedef int OSSL_CMP_severity;
\& #define OSSL_CMP_LOG_EMERG 0
\& #define OSSL_CMP_LOG_ALERT 1
\& #define OSSL_CMP_LOG_CRIT 2
\& #define OSSL_CMP_LOG_ERR 3
\& #define OSSL_CMP_LOG_WARNING 4
\& #define OSSL_CMP_LOG_NOTICE 5
\& #define OSSL_CMP_LOG_INFO 6
\& #define OSSL_CMP_LOG_DEBUG 7
\& #define OSSL_CMP_LOG_TRACE 8
\&
\& typedef int (*OSSL_CMP_log_cb_t)(const char *component,
\& const char *file, int line,
\& OSSL_CMP_severity level, const char *msg);
\& int OSSL_CMP_print_to_bio(BIO *bio, const char *component, const char *file,
\& int line, OSSL_CMP_severity level, const char *msg);
\& void OSSL_CMP_print_errors_cb(OSSL_CMP_log_cb_t log_fn);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The logging and error reporting facility described here contains
convenience functions for CMP-specific logging,
including a string prefix mirroring the severity levels of syslog.h,
and enhancements of the error queue mechanism needed for large diagnostic
messages produced by the \s-1CMP\s0 library in case of certificate validation failures.
.PP
When an interesting activity is performed or an error occurs, some detail
should be provided for user information, debugging, and auditing purposes.
A \s-1CMP\s0 application can obtain this information by providing a callback function
with the following type:
.PP
.Vb 3
\& typedef int (*OSSL_CMP_log_cb_t)(const char *component,
\& const char *file, int line,
\& OSSL_CMP_severity level, const char *msg);
.Ve
.PP
The parameters may provide
some component info (which may be a module name and/or function name) or \s-1NULL,\s0
a file pathname or \s-1NULL,\s0
a line number or 0 indicating the source code location,
a severity level, and
a message string describing the nature of the event, terminated by '\en'.
.PP
Even when an activity is successful some warnings may be useful and some degree
of auditing may be required. Therefore, the logging facility supports a severity
level and the callback function has a \fIlevel\fR parameter indicating such a
level, such that error, warning, info, debug, etc. can be treated differently.
The callback is activated only when the severity level is sufficient according
to the current level of verbosity, which by default is \fB\s-1OSSL_CMP_LOG_INFO\s0\fR.
.PP
The callback function may itself do non-trivial tasks like writing to
a log file or remote stream, which in turn may fail.
Therefore, the function should return 1 on success and 0 on failure.
.PP
\&\fBOSSL_CMP_log_open()\fR initializes the CMP-specific logging facility to output
everything to \s-1STDOUT.\s0 It fails if the integrated tracing is disabled or \s-1STDIO\s0
is not available. It may be called during application startup.
Alternatively, \fBOSSL_CMP_CTX_set_log_cb\fR\|(3) can be used for more flexibility.
As long as neither if the two is used any logging output is ignored.
.PP
\&\fBOSSL_CMP_log_close()\fR may be called when all activities are finished to flush
any pending CMP-specific log output and deallocate related resources.
It may be called multiple times. It does get called at OpenSSL shutdown.
.PP
\&\fBOSSL_CMP_print_to_bio()\fR prints the given component info, filename, line number,
severity level, and log message or error queue message to the given \fIbio\fR.
\&\fIcomponent\fR usually is a function or module name.
If it is \s-1NULL,\s0 empty, or \*(L"(unknown function)\*(R" then \*(L"\s-1CMP\*(R"\s0 is used as fallback.
.PP
\&\fBOSSL_CMP_print_errors_cb()\fR outputs any entries in the OpenSSL error queue.
It is similar to \fBERR_print_errors_cb\fR\|(3) but uses the \s-1CMP\s0 log callback
function \fIlog_fn\fR for uniformity with \s-1CMP\s0 logging if not \s-1NULL.\s0 Otherwise it
prints to \s-1STDERR\s0 using \fBOSSL_CMP_print_to_bio\fR\|(3) (unless \fB\s-1OPENSSL_NO_STDIO\s0\fR
is defined).
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBOSSL_CMP_log_close()\fR and \fBOSSL_CMP_print_errors_cb()\fR do not return anything.
.PP
All other functions return 1 on success, 0 on error.
.SH "HISTORY"
.IX Header "HISTORY"
The OpenSSL \s-1CMP\s0 support was added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2007\-2023 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>.
|
