OSSL_CMP_LOG_OPEN(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💖 OSSL_CMP_LOG_OPEN 💖

okay bestie, so this is a page from the 3ossl manual set — yes, the OpenSSL one — and it's all about the CMP logging + error-reporting glow-up. no cap, it's lowkey iconic. let's get into it 🎀

✨ NAME ✨

so the whole squad here is: OSSL_CMP_log_open, OSSL_CMP_log_close, OSSL_CMP_severity, OSSL_CMP_LOG_EMERG, OSSL_CMP_LOG_ALERT, OSSL_CMP_LOG_CRIT, OSSL_CMP_LOG_ERR, OSSL_CMP_LOG_WARNING, OSSL_CMP_LOG_NOTICE, OSSL_CMP_LOG_INFO, OSSL_CMP_LOG_DEBUG, OSSL_CMP_LOG_TRACE,

and also OSSL_CMP_log_cb_t, OSSL_CMP_print_to_bio, OSSL_CMP_print_errors_cb — together they're the functions for logging and error reporting. the whole main-character lineup fr fr 💅

🌸 SYNOPSIS 🌸

like, here's the literal code, do not touch, copy it exactly:

#include <openssl/cmp_util.h>

int  OSSL_CMP_log_open(void);
void OSSL_CMP_log_close(void);

/* severity level declarations resemble those from syslog.h */
typedef int OSSL_CMP_severity;
#define OSSL_CMP_LOG_EMERG   0
#define OSSL_CMP_LOG_ALERT   1
#define OSSL_CMP_LOG_CRIT    2
#define OSSL_CMP_LOG_ERR     3
#define OSSL_CMP_LOG_WARNING 4
#define OSSL_CMP_LOG_NOTICE  5
#define OSSL_CMP_LOG_INFO    6
#define OSSL_CMP_LOG_DEBUG   7
#define OSSL_CMP_LOG_TRACE   8

typedef int (*OSSL_CMP_log_cb_t)(const char *component,
                                 const char *file, int line,
                                 OSSL_CMP_severity level, const char *msg);
int OSSL_CMP_print_to_bio(BIO *bio, const char *component, const char *file,
                          int line, OSSL_CMP_severity level, const char *msg);
void OSSL_CMP_print_errors_cb(OSSL_CMP_log_cb_t log_fn);

look at all those severity levels, she's got range 👑

🦋 DESCRIPTION 🦋

okay so the logging and error reporting facility described here is basically a little convenience bundle for CMP-specific logging — and yes it comes with a string prefix that mirrors the severity levels of syslog.h (so cute, very on-brand) — plus some enhancements to the error queue mechanism. and why do we need those enhancements? because the CMP library can produce big diagnostic messages when certificate validation fails. like, huge. essay-length. 💀

the vibe check: when an interesting activity is performed or an error occurs, some detail should be provided for user information, debugging, and auditing purposes. so a CMP application can obtain this information by providing a callback function with this type:

typedef int (*OSSL_CMP_log_cb_t)(const char *component,
                                 const char *file, int line,
                                 OSSL_CMP_severity level, const char *msg);

and what do the params give you? lowkey a lot:

  • some component info — which may be a module name and/or function name — or NULL
  • a file pathname or NULL
  • a line number or 0 indicating the source code location
  • a severity level
  • a message string describing the nature of the event, terminated by '\n'

even when an activity is successful, some warnings may be useful and some degree of auditing may be required. so the logging facility supports a severity level, and the callback function has a level parameter indicating such a level — that way error, warning, info, debug, etc. can all be treated differently. iconic, honestly. the callback is activated only when the severity level is sufficient according to the current level of verbosity, which by default is OSSL_CMP_LOG_INFO. 🫶

and heads up: the callback function may itself do non-trivial tasks like writing to a log file or remote stream, which in turn may fail. so the function should return 1 on success and 0 on failure. no pressure bestie 😭

💜 the individual functions, one by one 💜

  • OSSL_CMP_log_open() — initializes the CMP-specific logging facility to output everything to STDOUT. it fails if the integrated tracing is disabled or STDIO is not available. it may be called during application startup. alternatively, OSSL_CMP_CTX_set_log_cb(3) can be used for more flexibility. and like, as long as neither of the two is used, any logging output is ignored. 🙈
  • OSSL_CMP_log_close() — may be called when all activities are finished, to flush any pending CMP-specific log output and deallocate related resources. it may be called multiple times. it does get called at OpenSSL shutdown, so she's got your back either way. ✨
  • OSSL_CMP_print_to_bio() — prints the given component info, filename, line number, severity level, and log message or error queue message to the given bio. component usually is a function or module name. if it is NULL, empty, or "(unknown function)" then "CMP" is used as fallback. slay, she always has a backup plan 💅
  • OSSL_CMP_print_errors_cb() — outputs any entries in the OpenSSL error queue. it's similar to ERR_print_errors_cb(3) but uses the CMP log callback function log_fn for uniformity with CMP logging if not NULL. otherwise it prints to STDERR using OSSL_CMP_print_to_bio(3) (unless OPENSSL_NO_STDIO is defined). covered either way, periodt 🎀

🌈 RETURN VALUES 🌈

OSSL_CMP_log_close() and OSSL_CMP_print_errors_cb() do not return anything. they simply ~are~. 💀

all other functions return 1 on success, 0 on error. that's it, that's the whole story.

⭐ HISTORY ⭐

the OpenSSL CMP support was added in OpenSSL 3.0. so she's a 3.0 baby, we stan a legend 🔥

Copyright 2007-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

like actually read the license bestie, "not compliance" is not a vibe 🌸

okay that's the whole page!! and as a little sign-off: this gorgeous piece of documentation is from 3.5.6, dated 2026-04-07, and it lives under the name OSSL_CMP_LOG_OPEN(3ossl). bye bestie, go log something responsibly 🦋💖🧚

📦 where this page comes from