mirror of
https://github.com/openssl/openssl.git
synced 2024-12-09 05:51:54 +08:00
1a5ae1da14
* In the cmp app so far the -verbosity option had been missing. * Extend log output helpful for debugging CMP applications in setup_ssl_ctx() of the cmp app, ossl_cmp_msg_add_extraCerts(), OSSL_CMP_validate_msg(), and OSSL_CMP_MSG_http_perform(). * Correct suppression of log output with insufficient severity. * Add logging/severity level OSSL_CMP_LOG_TRACE = OSSL_CMP_LOG_MAX. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/12739)
124 lines
4.7 KiB
Plaintext
124 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 B<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 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 stutdown.
|
|
|
|
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 B<bio>.
|
|
B<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 B<ERR_print_errors_cb()> but uses the CMP log callback function
|
|
C<log_fn> for uniformity with CMP logging if not B<NULL>. Otherwise it prints to
|
|
STDERR using B<OSSL_CMP_print_to_bio(3)> (unless 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-2020 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
|