Latest update.

doc/man3/OSSL_CMP_log_open.pod

@@ -0,0 +1,140 @@
+=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