1=pod 2 3=head1 NAME 4 5OSSL_CMP_log_open, 6OSSL_CMP_log_close, 7OSSL_CMP_severity, 8OSSL_CMP_LOG_EMERG, 9OSSL_CMP_LOG_ALERT, 10OSSL_CMP_LOG_CRIT, 11OSSL_CMP_LOG_ERR, 12OSSL_CMP_LOG_WARNING, 13OSSL_CMP_LOG_NOTICE, 14OSSL_CMP_LOG_INFO, 15OSSL_CMP_LOG_DEBUG, 16OSSL_CMP_LOG_TRACE, 17 18OSSL_CMP_log_cb_t, 19OSSL_CMP_print_to_bio, 20OSSL_CMP_print_errors_cb 21- functions for logging and error reporting 22 23=head1 SYNOPSIS 24 25 #include <openssl/cmp_util.h> 26 27 int OSSL_CMP_log_open(void); 28 void OSSL_CMP_log_close(void); 29 30 /* severity level declarations resemble those from syslog.h */ 31 typedef int OSSL_CMP_severity; 32 #define OSSL_CMP_LOG_EMERG 0 33 #define OSSL_CMP_LOG_ALERT 1 34 #define OSSL_CMP_LOG_CRIT 2 35 #define OSSL_CMP_LOG_ERR 3 36 #define OSSL_CMP_LOG_WARNING 4 37 #define OSSL_CMP_LOG_NOTICE 5 38 #define OSSL_CMP_LOG_INFO 6 39 #define OSSL_CMP_LOG_DEBUG 7 40 #define OSSL_CMP_LOG_TRACE 8 41 42 typedef int (*OSSL_CMP_log_cb_t)(const char *component, 43 const char *file, int line, 44 OSSL_CMP_severity level, const char *msg); 45 int OSSL_CMP_print_to_bio(BIO *bio, const char *component, const char *file, 46 int line, OSSL_CMP_severity level, const char *msg); 47 void OSSL_CMP_print_errors_cb(OSSL_CMP_log_cb_t log_fn); 48 49=head1 DESCRIPTION 50 51The logging and error reporting facility described here contains 52convenience functions for CMP-specific logging, 53including a string prefix mirroring the severity levels of syslog.h, 54and enhancements of the error queue mechanism needed for large diagnostic 55messages produced by the CMP library in case of certificate validation failures. 56 57When an interesting activity is performed or an error occurs, some detail 58should be provided for user information, debugging, and auditing purposes. 59A CMP application can obtain this information by providing a callback function 60with the following type: 61 62 typedef int (*OSSL_CMP_log_cb_t)(const char *component, 63 const char *file, int line, 64 OSSL_CMP_severity level, const char *msg); 65 66The parameters may provide 67some component info (which may be a module name and/or function name) or NULL, 68a file pathname or NULL, 69a line number or 0 indicating the source code location, 70a severity level, and 71a message string describing the nature of the event, terminated by '\n'. 72 73Even when an activity is successful some warnings may be useful and some degree 74of auditing may be required. Therefore, the logging facility supports a severity 75level and the callback function has a I<level> parameter indicating such a 76level, such that error, warning, info, debug, etc. can be treated differently. 77The callback is activated only when the severity level is sufficient according 78to the current level of verbosity, which by default is B<OSSL_CMP_LOG_INFO>. 79 80The callback function may itself do non-trivial tasks like writing to 81a log file or remote stream, which in turn may fail. 82Therefore, the function should return 1 on success and 0 on failure. 83 84OSSL_CMP_log_open() initializes the CMP-specific logging facility to output 85everything to STDOUT. It fails if the integrated tracing is disabled or STDIO 86is not available. It may be called during application startup. 87Alternatively, L<OSSL_CMP_CTX_set_log_cb(3)> can be used for more flexibility. 88As long as neither if the two is used any logging output is ignored. 89 90OSSL_CMP_log_close() may be called when all activities are finished to flush 91any pending CMP-specific log output and deallocate related resources. 92It may be called multiple times. It does get called at OpenSSL shutdown. 93 94OSSL_CMP_print_to_bio() prints the given component info, filename, line number, 95severity level, and log message or error queue message to the given I<bio>. 96I<component> usually is a function or module name. 97If it is NULL, empty, or "(unknown function)" then "CMP" is used as fallback. 98 99OSSL_CMP_print_errors_cb() outputs any entries in the OpenSSL error queue. 100It is similar to L<ERR_print_errors_cb(3)> but uses the CMP log callback 101function I<log_fn> for uniformity with CMP logging if not NULL. Otherwise it 102prints to STDERR using L<OSSL_CMP_print_to_bio(3)> (unless B<OPENSSL_NO_STDIO> 103is defined). 104 105=head1 RETURN VALUES 106 107OSSL_CMP_log_close() and OSSL_CMP_print_errors_cb() do not return anything. 108 109All other functions return 1 on success, 0 on error. 110 111=head1 HISTORY 112 113The OpenSSL CMP support was added in OpenSSL 3.0. 114 115=head1 COPYRIGHT 116 117Copyright 2007-2022 The OpenSSL Project Authors. All Rights Reserved. 118 119Licensed under the Apache License 2.0 (the "License"). You may not use 120this file except in compliance with the License. You can obtain a copy 121in the file LICENSE in the source distribution or at 122L<https://www.openssl.org/source/license.html>. 123 124=cut 125
