mirror of https://github.com/openssl/openssl.git
125 lines
4.7 KiB
Plaintext
125 lines
4.7 KiB
Plaintext
=pod
|
|
|
|
=head1 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,
|
|
|
|
OSSL_CMP_log_cb_t,
|
|
OSSL_CMP_print_to_bio,
|
|
OSSL_CMP_print_errors_cb
|
|
- functions for logging and error reporting
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#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);
|
|
|
|
=head1 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 CMP library in case of certificate validation failures.
|
|
|
|
When an interesting activity is performed or an error occurs, some detail
|
|
should be provided for user information, debugging, and auditing purposes.
|
|
A CMP application can obtain this information by providing a callback function
|
|
with the following type:
|
|
|
|
typedef int (*OSSL_CMP_log_cb_t)(const char *component,
|
|
const char *file, int line,
|
|
OSSL_CMP_severity level, const char *msg);
|
|
|
|
The parameters may provide
|
|
some component info (which may be a module name and/or function name) or NULL,
|
|
a file pathname or NULL,
|
|
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 '\n'.
|
|
|
|
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 I<level> 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 B<OSSL_CMP_LOG_INFO>.
|
|
|
|
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.
|
|
|
|
OSSL_CMP_log_open() initializes the CMP-specific logging facility to output
|
|
everything to STDOUT. It fails if the integrated tracing is disabled or STDIO
|
|
is not available. It may be called during application startup.
|
|
Alternatively, L<OSSL_CMP_CTX_set_log_cb(3)> can be used for more flexibility.
|
|
As long as neither if the two is used any logging output is ignored.
|
|
|
|
OSSL_CMP_log_close() 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.
|
|
|
|
OSSL_CMP_print_to_bio() prints the given component info, filename, line number,
|
|
severity level, and log message or error queue message to the given I<bio>.
|
|
I<component> usually is a function or module name.
|
|
If it is NULL, empty, or "(unknown function)" then "CMP" is used as fallback.
|
|
|
|
OSSL_CMP_print_errors_cb() outputs any entries in the OpenSSL error queue.
|
|
It is similar to L<ERR_print_errors_cb(3)> but uses the CMP log callback
|
|
function I<log_fn> for uniformity with CMP logging if not NULL. Otherwise it
|
|
prints to STDERR using L<OSSL_CMP_print_to_bio(3)> (unless B<OPENSSL_NO_STDIO>
|
|
is defined).
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
OSSL_CMP_log_close() and OSSL_CMP_print_errors_cb() do not return anything.
|
|
|
|
All other functions return 1 on success, 0 on error.
|
|
|
|
=head1 HISTORY
|
|
|
|
The OpenSSL CMP support was added in OpenSSL 3.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2007-2022 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
|