mirror of
https://github.com/openssl/openssl.git
synced 2024-12-09 05:51:54 +08:00
9c0586d5fc
Also patch find-doc-nits to ignore a Microsoft trademark and not flag it as a spelling error. Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/10023)
141 lines
5.2 KiB
Plaintext
141 lines
5.2 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSL_CMP_log_open,
|
|
OSSL_CMP_log_close,
|
|
OSSL_CMP_alert,
|
|
OSSL_CMP_err,
|
|
OSSL_CMP_warn,
|
|
OSSL_CMP_info,
|
|
OSSL_CMP_debug,
|
|
OSSL_CMP_log,
|
|
OSSL_CMP_log1,
|
|
OSSL_CMP_log2,
|
|
OSSL_CMP_log3,
|
|
OSSL_CMP_log4,
|
|
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_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);
|
|
#define OSSL_CMP_alert(msg)
|
|
#define OSSL_CMP_err(msg)
|
|
#define OSSL_CMP_warn(msg)
|
|
#define OSSL_CMP_info(msg)
|
|
#define OSSL_CMP_debug(msg)
|
|
#define OSSL_CMP_log(level, msg)
|
|
#define OSSL_CMP_log1(level, fmt, arg1)
|
|
#define OSSL_CMP_log2(level, fmt, arg1, arg2)
|
|
#define OSSL_CMP_log3(level, fmt, arg1, arg2, arg3)
|
|
#define OSSL_CMP_log4(level, fmt, arg1, arg2, arg3, arg4)
|
|
|
|
/* 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
|
|
typedef int (*OSSL_cmp_log_cb_t) (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 via the trace API,
|
|
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 void (*OSSL_cmp_log_cb_t)(const char *component,
|
|
const char *file, int line,
|
|
OSSL_CMP_severity level, const char *msg);
|
|
|
|
The parameters may provide
|
|
a component identifier (which may be a library name 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_alert() outputs a simple alert message via the trace API.
|
|
OSSL_CMP_err() outputs a simple error message via the trace API.
|
|
OSSL_CMP_warn() outputs a simple warning message via the trace API.
|
|
OSSL_CMP_info() outputs a simple info message via the trace API.
|
|
OSSL_CMP_debug() outputs a simple debug message via the trace API.
|
|
|
|
Note that due to the design of the trace API used, the log functions have no
|
|
effect unless the B<enable-trace> option is used during build configuration.
|
|
|
|
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 uses
|
|
B<ERR_print_errors(3)> to print to STDERR (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-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
|