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_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,
  16 OSSL_CMP_LOG_TRACE,
  17
  18 OSSL_CMP_log_cb_t,
  19 OSSL_CMP_print_to_bio,
  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);
  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
  51 The logging and error reporting facility described here contains
  52 convenience functions for CMP-specific logging,
  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
  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
  66 The parameters may provide
  67 some component info (which may be a module name and/or function name) or NULL,
  68 a file pathname or NULL,
  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
  74 of auditing may be required. Therefore, the logging facility supports a severity
  75 level and the callback function has a I<level> parameter indicating such a
  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
  78 to the current level of verbosity, which by default is B<OSSL_CMP_LOG_INFO>.
  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.
  82 Therefore, the function should return 1 on success and 0 on failure.
  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
  94 OSSL_CMP_print_to_bio() prints the given component info, filename, line number,
  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.
  97 If it is NULL, empty, or "(unknown function)" then "CMP" is used as fallback.
  98
  99 OSSL_CMP_print_errors_cb() outputs any entries in the OpenSSL error queue.
 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).
 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
 117 Copyright 2007-2021 The OpenSSL Project Authors. All Rights Reserved.
 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