doc/man3/OSSL_CMP_log_open.pod

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