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