1OSSL_CMP_LOG_OPEN(3ossl)            OpenSSL           OSSL_CMP_LOG_OPEN(3ossl)
2
3
4

NAME

6       OSSL_CMP_log_open, OSSL_CMP_log_close, OSSL_CMP_severity,
7       OSSL_CMP_LOG_EMERG, OSSL_CMP_LOG_ALERT, OSSL_CMP_LOG_CRIT,
8       OSSL_CMP_LOG_ERR, OSSL_CMP_LOG_WARNING, OSSL_CMP_LOG_NOTICE,
9       OSSL_CMP_LOG_INFO, OSSL_CMP_LOG_DEBUG, OSSL_CMP_LOG_TRACE,
10
11       OSSL_CMP_log_cb_t, OSSL_CMP_print_to_bio, OSSL_CMP_print_errors_cb -
12       functions for logging and error reporting
13

SYNOPSIS

15        #include <openssl/cmp_util.h>
16
17        int  OSSL_CMP_log_open(void);
18        void OSSL_CMP_log_close(void);
19
20        /* severity level declarations resemble those from syslog.h */
21        typedef int OSSL_CMP_severity;
22        #define OSSL_CMP_LOG_EMERG   0
23        #define OSSL_CMP_LOG_ALERT   1
24        #define OSSL_CMP_LOG_CRIT    2
25        #define OSSL_CMP_LOG_ERR     3
26        #define OSSL_CMP_LOG_WARNING 4
27        #define OSSL_CMP_LOG_NOTICE  5
28        #define OSSL_CMP_LOG_INFO    6
29        #define OSSL_CMP_LOG_DEBUG   7
30        #define OSSL_CMP_LOG_TRACE   8
31
32        typedef int (*OSSL_CMP_log_cb_t)(const char *component,
33                                         const char *file, int line,
34                                         OSSL_CMP_severity level, const char *msg);
35        int OSSL_CMP_print_to_bio(BIO *bio, const char *component, const char *file,
36                                  int line, OSSL_CMP_severity level, const char *msg);
37        void OSSL_CMP_print_errors_cb(OSSL_CMP_log_cb_t log_fn);
38

DESCRIPTION

40       The logging and error reporting facility described here contains
41       convenience functions for CMP-specific logging, including a string
42       prefix mirroring the severity levels of syslog.h, and enhancements of
43       the error queue mechanism needed for large diagnostic messages produced
44       by the CMP library in case of certificate validation failures.
45
46       When an interesting activity is performed or an error occurs, some
47       detail should be provided for user information, debugging, and auditing
48       purposes.  A CMP application can obtain this information by providing a
49       callback function with the following type:
50
51        typedef int (*OSSL_CMP_log_cb_t)(const char *component,
52                                         const char *file, int line,
53                                         OSSL_CMP_severity level, const char *msg);
54
55       The parameters may provide some component info (which may be a module
56       name and/or function name) or NULL, a file pathname or NULL, a line
57       number or 0 indicating the source code location, a severity level, and
58       a message string describing the nature of the event, terminated by
59       '\n'.
60
61       Even when an activity is successful some warnings may be useful and
62       some degree of auditing may be required. Therefore, the logging
63       facility supports a severity level and the callback function has a
64       level parameter indicating such a level, such that error, warning,
65       info, debug, etc. can be treated differently.  The callback is
66       activated only when the severity level is sufficient according to the
67       current level of verbosity, which by default is OSSL_CMP_LOG_INFO.
68
69       The callback function may itself do non-trivial tasks like writing to a
70       log file or remote stream, which in turn may fail.  Therefore, the
71       function should return 1 on success and 0 on failure.
72
73       OSSL_CMP_log_open() initializes the CMP-specific logging facility to
74       output everything to STDOUT. It fails if the integrated tracing is
75       disabled or STDIO is not available. It may be called during application
76       startup.  Alternatively, OSSL_CMP_CTX_set_log_cb(3) can be used for
77       more flexibility.  As long as neither if the two is used any logging
78       output is ignored.
79
80       OSSL_CMP_log_close() may be called when all activities are finished to
81       flush any pending CMP-specific log output and deallocate related
82       resources.  It may be called multiple times. It does get called at
83       OpenSSL shutdown.
84
85       OSSL_CMP_print_to_bio() prints the given component info, filename, line
86       number, severity level, and log message or error queue message to the
87       given bio.  component usually is a function or module name.  If it is
88       NULL, empty, or "(unknown function)" then "CMP" is used as fallback.
89
90       OSSL_CMP_print_errors_cb() outputs any entries in the OpenSSL error
91       queue.  It is similar to ERR_print_errors_cb(3) but uses the CMP log
92       callback function log_fn for uniformity with CMP logging if not NULL.
93       Otherwise it prints to STDERR using OSSL_CMP_print_to_bio(3) (unless
94       OPENSSL_NO_STDIO is defined).
95

RETURN VALUES

97       OSSL_CMP_log_close() and OSSL_CMP_print_errors_cb() do not return
98       anything.
99
100       All other functions return 1 on success, 0 on error.
101

HISTORY

103       The OpenSSL CMP support was added in OpenSSL 3.0.
104
106       Copyright 2007-2022 The OpenSSL Project Authors. All Rights Reserved.
107
108       Licensed under the Apache License 2.0 (the "License").  You may not use
109       this file except in compliance with the License.  You can obtain a copy
110       in the file LICENSE in the source distribution or at
111       <https://www.openssl.org/source/license.html>.
112
113
114
1153.1.1                             2023-08-31          OSSL_CMP_LOG_OPEN(3ossl)
Impressum