wp_logging.h

/* wp_logging.h
 *
 * Copyright (C) 2006-2025 wolfSSL Inc.
 *
 * This file is part of wolfProvider.
 *
 * wolfProvider is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * wolfProvider is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with wolfProvider. If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef WP_LOGGING_H
#define WP_LOGGING_H

#ifdef WOLFPROV_USER_SETTINGS
    #include "user_settings.h"
#endif


#if defined(__IAR_SYSTEMS_ICC__) || defined(__GNUC__)
    /* Function is a printf style function. Pretend parameter is string literal.
     *
     * @param s  [in]  Index of string literal. Index from 1.
     * @param v  [in]  Index of first argument to check. 0 means don't.
     */
    #define WP_PRINTF_FUNC(s, v)  __attribute__((__format__ (__printf__, s, v)))
#else
    #define WP_PRINTF_FUNC(s, v)
#endif


#ifndef WOLFPROV_MAX_LOG_WIDTH
#define WOLFPROV_MAX_LOG_WIDTH 120
#endif


/* Helper macro to select function name for logging */
#if defined(_WIN32)
    #define WOLFPROV_FUNC_NAME __FUNCTION__
#elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
    #define WOLFPROV_FUNC_NAME __func__
#else
    #define WOLFPROV_FUNC_NAME ""
#endif


/* wolfProv debug logging support can be compiled in by defining
 * WOLFPROV_DEBUG or by using the --enable-debug configure option.
 *
 * By default, when debug is enabled, logging is active immediately.
 * Use --enable-debug-silent to compile in debug support but keep it
 * silent by default. In silent mode, logging is only activated when
 * WOLFPROV_LOG_LEVEL or WOLFPROV_LOG_COMPONENTS environment variables
 * are set at runtime.
 *
 * wolfProv supports the log levels as mentioned in wolfProv_LogLevels
 * enum below. The default logging level when debug logging is compiled in
 * and enabled at runtime is WP_LOG_LEVEL_DEFAULT.
 *
 * wolfProv supports log message control per-component/algorithm type,
 * with all possible logging components in wolfProv_LogComponents enum
 * below. The default logging level when debug logging is compiled in and
 * enabled at runtime is WP_LOG_COMP_DEFAULT.
 *
 */

/* Possible debug/logging options:
 *
 * WOLFPROV_DEBUG       Define to enable debug logging (or --enable-debug)
 * WOLFPROV_USER_LOG    Defines name of function for log output. By default
 *                        wolfProv will log with fprintf to stderr. Users
 *                        can define this to a custom log function to be used
 *                        in place of fprintf. Alternatively, users can
 *                        register a logging callback for custom logging.
 * WOLFPROV_LOG_PRINTF  Define to Use printf instead of fprintf (to stderr)
 *                        for logs. Not applicable if using WOLFPROV_USER_LOG
 *                        or custom logging callback.
 * WOLFPROV_LOG_FILE     Define to specify a file path for debug output instead
 *                        of stderr. This is typically set via --debug-log=FILE
 *                        build script argument.
 *
 * COMPILE-TIME MACRO CONFIGURATIONS:
 * Define these macros in this header to control logging at compile time:
 * NOTE: wolfProvider needs to be built with --debug to enable the logging first
 * before we can set the log level and components.
 *
 * WOLFPROV_LOG_LEVEL_FILTER Sets the log level. Use WP_LOG_* constants from enum below.
 *                        Examples:
 *                        - WP_LOG_LEVEL_ERROR (only errors)
 *                        - (WP_LOG_LEVEL_ERROR | WP_LOG_LEVEL_ENTER) (errors and function enter)
 *                        - (WP_LOG_LEVEL_ERROR | WP_LOG_LEVEL_LEAVE) (errors and function leave)
 *                        - (WP_LOG_LEVEL_ALL) (all levels)
 *
 * WOLFPROV_LOG_COMPONENTS_FILTER  Set component bitmask to filter specific
 *                        algorithms. Use WP_LOG_* constants from enum below.
 *                        Examples:
 *                        - WP_LOG_COMP_HKDF (HKDF only)
 *                        - (WP_LOG_COMP_AES | WP_LOG_COMP_DES) (ciphers only)
 *                        - (WP_LOG_COMP_ECC | WP_LOG_COMP_RSA | WP_LOG_COMP_HKDF) (multiple algorithms)
 *                        - WP_LOG_COMP_CIPHER (all cipher operations)
 *
 * EXAMPLES:
 * #define WOLFPROV_LOG_LEVEL_FILTER (WP_LOG_LEVEL_ERROR | WP_LOG_LEVEL_ENTER | WP_LOG_LEVEL_LEAVE | WP_LOG_LEVEL_INFO)
 * #define WOLFPROV_LOG_COMPONENTS_FILTER WP_LOG_COMP_HKDF
 * // Shows level (ERROR + ENTER/LEAVE + INFO) for HKDF operations only
 *
 * #define WOLFPROV_LOG_LEVEL_FILTER (WP_LOG_LEVEL_ALL)
 * #define WOLFPROV_LOG_COMPONENTS_FILTER (WP_LOG_COMP_ECC | WP_LOG_COMP_RSA | WP_LOG_COMP_HKDF)
 * // Shows level (ERROR + ENTER/LEAVE + INFO + VERBOSE + DEBUG + TRACE) for ECC, RSA, and HKDF only
 *
 * When modifying the enum values, ensure the corresponding strings in the
 * wp_logging.c file are updated to match.
 */
/*-------------------------------------------------------------*
 *  wolfProv_LogLevels
 *-------------------------------------------------------------*/

#define WP_LOG_LEVEL_ERROR     0x0001  /* logs errors */
#define WP_LOG_LEVEL_ENTER     0x0002  /* logs function enter */
#define WP_LOG_LEVEL_LEAVE     0x0004  /* logs function leave */
#define WP_LOG_LEVEL_INFO      0x0008  /* logs informative messages */
#define WP_LOG_LEVEL_VERBOSE   0x0010  /* logs encrypted/decrypted/digested data */
/* To see the return code from wolfssl, you must add WP_LOG_LEVEL_DEBUG to the
 * WOLFPROV_LOG_LEVEL_FILTER */
#define WP_LOG_LEVEL_DEBUG     0x0020  /* logs debug-level detailed information */
#define WP_LOG_LEVEL_TRACE     0x0040  /* logs trace-level ultra-detailed information */

/* default log level when logging is turned on */
#define WP_LOG_LEVEL_DEFAULT ( \
    WP_LOG_LEVEL_ERROR | \
    WP_LOG_LEVEL_LEAVE | \
    WP_LOG_LEVEL_INFO)

/* log all, including verbose */
#define WP_LOG_LEVEL_ALL ( \
    WP_LOG_LEVEL_ERROR   | \
    WP_LOG_LEVEL_ENTER   | \
    WP_LOG_LEVEL_LEAVE   | \
    WP_LOG_LEVEL_INFO    | \
    WP_LOG_LEVEL_VERBOSE | \
    WP_LOG_LEVEL_DEBUG   | \
    WP_LOG_LEVEL_TRACE )

/*-------------------------------------------------------------*
 *  wolfProv_LogComponents
 *-------------------------------------------------------------*/

/* Legacy component categories */
#define WP_LOG_COMP_RNG        0x0001      /* random number generation */
#define WP_LOG_COMP_DIGEST     0x0002      /* digest (SHA-1/2/3) */
#define WP_LOG_COMP_MAC        0x0004      /* mac functions: HMAC, CMAC */
#define WP_LOG_COMP_CIPHER     0x0008      /* cipher (AES, 3DES) */
#define WP_LOG_COMP_PK         0x0010      /* public key algorithms (RSA, ECC) */
#define WP_LOG_COMP_KE         0x0020      /* key agreement (DH, ECDH) */
#define WP_LOG_COMP_KDF        0x0040      /* password base key derivation algorithms */
#define WP_LOG_COMP_PROVIDER   0x0080      /* all provider specific logs */

/* Granular algorithm family categories */
#define WP_LOG_COMP_RSA        0x0100      /* RSA operations */
#define WP_LOG_COMP_ECC        0x0200      /* ECC operations */
#define WP_LOG_COMP_DH         0x0400      /* Diffie-Hellman operations */
#define WP_LOG_COMP_AES        0x0800      /* AES cipher operations */
#define WP_LOG_COMP_DES        0x1000      /* 3DES cipher operations */
#define WP_LOG_COMP_SHA        0x2000      /* SHA digest operations */
#define WP_LOG_COMP_MD5        0x4000      /* MD5 digest operations */
#define WP_LOG_COMP_HMAC       0x8000      /* HMAC operations */
#define WP_LOG_COMP_CMAC       0x10000     /* CMAC operations */
#define WP_LOG_COMP_HKDF       0x20000     /* HKDF operations */
#define WP_LOG_COMP_PBKDF2     0x40000     /* PBKDF2 operations */
#define WP_LOG_COMP_KRB5KDF    0x80000     /* KRB5KDF operations */
#define WP_LOG_COMP_DRBG       0x100000    /* DRBG operations */
#define WP_LOG_COMP_ECDSA      0x200000    /* ECDSA signature operations */
#define WP_LOG_COMP_ECDH       0x400000    /* ECDH key exchange operations */
#define WP_LOG_COMP_ED25519    0x800000    /* Ed25519 operations */
#define WP_LOG_COMP_ED448      0x1000000   /* Ed448 operations */
#define WP_LOG_COMP_X25519     0x2000000   /* X25519 operations */
#define WP_LOG_COMP_X448       0x4000000   /* X448 operations */
#define WP_LOG_COMP_QUERY      0x8000000   /* wolfprov_query operations */
#define WP_LOG_COMP_TLS1_PRF   0x10000000  /* TLS1 PRF operations */
#define WP_LOG_COMP_SSHKDF     0x20000000  /* SSHKDF operations */

/* log all components */
#define WP_LOG_COMP_ALL ( \
    WP_LOG_COMP_RNG        | \
    WP_LOG_COMP_DIGEST     | \
    WP_LOG_COMP_MAC        | \
    WP_LOG_COMP_CIPHER     | \
    WP_LOG_COMP_PK         | \
    WP_LOG_COMP_KE         | \
    WP_LOG_COMP_KDF        | \
    WP_LOG_COMP_PROVIDER   | \
    WP_LOG_COMP_RSA        | \
    WP_LOG_COMP_ECC        | \
    WP_LOG_COMP_DH         | \
    WP_LOG_COMP_AES        | \
    WP_LOG_COMP_DES        | \
    WP_LOG_COMP_SHA        | \
    WP_LOG_COMP_MD5        | \
    WP_LOG_COMP_HMAC       | \
    WP_LOG_COMP_CMAC       | \
    WP_LOG_COMP_HKDF       | \
    WP_LOG_COMP_PBKDF2     | \
    WP_LOG_COMP_KRB5KDF    | \
    WP_LOG_COMP_DRBG       | \
    WP_LOG_COMP_ECDSA      | \
    WP_LOG_COMP_ECDH       | \
    WP_LOG_COMP_ED25519    | \
    WP_LOG_COMP_ED448      | \
    WP_LOG_COMP_X25519     | \
    WP_LOG_COMP_X448       | \
    WP_LOG_COMP_QUERY      | \
    WP_LOG_COMP_TLS1_PRF  | \
    WP_LOG_COMP_SSHKDF )

/* default components logged */
#define WP_LOG_COMP_DEFAULT WP_LOG_COMP_ALL

/* Manually set the log level */
#ifndef WOLFPROV_LOG_LEVEL_FILTER
#define WOLFPROV_LOG_LEVEL_FILTER WP_LOG_LEVEL_DEFAULT
#endif

/* Manually set the components */
#ifndef WOLFPROV_LOG_COMPONENTS_FILTER
#define WOLFPROV_LOG_COMPONENTS_FILTER WP_LOG_COMP_DEFAULT
#endif

/* Conditional logging macro that checks compile-time configuration */
#ifdef WOLFPROV_DEBUG
    #define WOLFPROV_COMPILE_TIME_CHECK(component, level) \
        ((WOLFPROV_LOG_LEVEL_FILTER & (level)) && \
         (WOLFPROV_LOG_COMPONENTS_FILTER & (component)))
#else
    #define WOLFPROV_COMPILE_TIME_CHECK(component, level) 0
#endif

typedef void (*wolfProv_Logging_cb)(const int logLevel, const int component,
    const char *const logMessage);
int wolfProv_SetLoggingCb(wolfProv_Logging_cb logF);

/* turn logging on, only if compiled in */
int  wolfProv_Debugging_ON(void);
/* turn logging off */
void wolfProv_Debugging_OFF(void);

/* Set logging level, bitmask of wolfProv_LogLevels */
int wolfProv_SetLogLevel(int levelMask);
/* Set which components are logged, bitmask of wolfProv_LogComponents */
int wolfProv_SetLogComponents(int componentMask);
/* Initialize logging module */
int wolfProv_LogInit(void);

#ifdef WOLFPROV_DEBUG

#define WOLFPROV_STRINGIZE_HELPER(x) #x
#define WOLFPROV_STRINGIZE(x) WOLFPROV_STRINGIZE_HELPER(x)

void wolfprovider_msg(int component, int logLevel, const char *fmt, ...);

/* Common macro which implements the compile-time check to strip disabled logs */
#define WOLFPROV_MSG_EX(component, level, fmt, ...) \
    do { if (WOLFPROV_COMPILE_TIME_CHECK(component, level)) { \
        wolfprovider_msg(component, level, fmt, ##__VA_ARGS__); \
    } } while(0)

#define WOLFPROV_MSG(component, fmt, ...) \
    WOLFPROV_MSG_EX(component, WP_LOG_LEVEL_INFO, fmt, ##__VA_ARGS__)

#define WOLFPROV_ERROR(component, err)                                           \
    WOLFPROV_ERROR_LINE(component, err, __FILE__, __LINE__)
#define WOLFPROV_ERROR_MSG(component, msg)                                       \
    WOLFPROV_ERROR_MSG_LINE(component, msg, __FILE__, __LINE__)
#define WOLFPROV_ERROR_FUNC(component, funcName, ret)                            \
    WOLFPROV_ERROR_FUNC_LINE(component, funcName, ret, __FILE__, __LINE__)
#define WOLFPROV_ERROR_FUNC_NULL(component, funcName, ret)                       \
    WOLFPROV_ERROR_FUNC_NULL_LINE(component, funcName, ret, __FILE__, __LINE__)

#define WOLFPROV_LEAVE(component, msg, ret) \
    WOLFPROV_LEAVE_EX(component, WOLFPROV_FUNC_NAME, msg, ret)
void WOLFPROV_LEAVE_EX(int component, const char* func, const char* msg, int ret);
#define WOLFPROV_LEAVE_SILENT(component, msg, ret) \
    WOLFPROV_LEAVE_SILENT_EX(component, WOLFPROV_FUNC_NAME, msg, ret)
void WOLFPROV_LEAVE_SILENT_EX(int component, const char* func, const char* msg,
    int ret);

#define WOLFPROV_ENTER(component, msg) \
    WOLFPROV_MSG_EX(component, WP_LOG_LEVEL_ENTER, "wolfProv Entering %s", msg)
#ifdef WOLFPROV_LEAVE_SILENT_MODE
#define WOLFPROV_ENTER_SILENT(component, msg) \
    WOLFPROV_ENTER_SILENT(component, msg)
#else
#define WOLFPROV_ENTER_SILENT(component, msg) \
    WOLFPROV_MSG_EX(component, WP_LOG_LEVEL_ENTER, "wolfProv Entering [leaving silently] %s", msg)
#endif

#define WOLFPROV_MSG_VERBOSE(component, fmt, ...) \
    WOLFPROV_MSG_EX(component, WP_LOG_LEVEL_VERBOSE, fmt, ##__VA_ARGS__)
#define WOLFPROV_MSG_DEBUG(component, fmt, ...) \
    WOLFPROV_MSG_EX(component, WP_LOG_LEVEL_DEBUG, fmt, ##__VA_ARGS__)
#define WOLFPROV_MSG_DEBUG_RETCODE(component, func_name, rc) \
    WOLFPROV_MSG_DEBUG(component, "%s failed with rc=%d", func_name, rc)
#define WOLFPROV_MSG_TRACE(component, fmt, ...) \
    WOLFPROV_MSG_EX(component, WP_LOG_LEVEL_TRACE, fmt, ##__VA_ARGS__)

void WOLFPROV_ERROR_LINE(int component, int err, const char* file, int line);
void WOLFPROV_ERROR_MSG_LINE(int component, const char* msg, const char* file,
    int line);
void WOLFPROV_ERROR_FUNC_LINE(int component, const char* funcName, int ret,
    const char* file, int line);
void WOLFPROV_ERROR_FUNC_NULL_LINE(int component, const char* funcName,
    const void *ret, const char* file, int line);
void WOLFPROV_BUFFER(int component, const unsigned char* buffer,
    unsigned int length);

#else /* WOLFPROV_DEBUG */

#define WOLFPROV_ENTER(t, m)
#define WOLFPROV_ENTER_SILENT(t, m)
#define WOLFPROV_LEAVE(t, m, r)
#define WOLFPROV_LEAVE_SILENT(t, m, r)
#define WOLFPROV_MSG(t, m, ...)
#define WOLFPROV_MSG_VERBOSE(t, m, ...)
#define WOLFPROV_MSG_DEBUG(t, m, ...)
#define WOLFPROV_MSG_DEBUG_RETCODE(t, f, r)
#define WOLFPROV_MSG_TRACE(t, m, ...)
#define WOLFPROV_ERROR(t, e)
#define WOLFPROV_ERROR_MSG(t, e)
#define WOLFPROV_ERROR_FUNC(t, f, r)
#define WOLFPROV_ERROR_FUNC_NULL(t, f, r)
#define WOLFPROV_BUFFER(t, b, l)

#endif /* WOLFPROV_DEBUG */

#endif /* WP_LOGGING_H */