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