kcenon::logger::security::audit_logger Class Reference

Secure audit logging with tamper detection. More...

#include <audit_logger.h>

Collaboration diagram for kcenon::logger::security::audit_logger:

Public Types
enum class	audit_event {   logger_started , logger_stopped , writer_added , writer_removed ,   encryption_key_loaded , encryption_key_rotated , encryption_key_generated , permission_denied ,   path_traversal_attempt , insecure_permissions_detected , suspicious_activity , configuration_changed ,   authentication_success , authentication_failure , file_access_denied , file_access_granted }
	Types of security-relevant events to audit. More...

Static Public Member Functions
static void	initialize (const std::filesystem::path &audit_file, const secure_key *hmac_key=nullptr)
	Initialize audit logger.
static void	log_audit_event (audit_event event, const std::string &details, const std::map< std::string, std::string > &metadata={})
	Log an audit event.
static bool	verify_entry (const std::string &json_entry, const std::string &signature)
	Verify integrity of an audit log entry.

Static Private Member Functions
static std::string	format_iso8601 (const std::chrono::system_clock::time_point &tp)
	Format timestamp as ISO8601 string.
static std::string	escape_json (const std::string &str)
	Escape JSON special characters.
static std::string	event_to_string (audit_event event)
	Convert audit event to string.
static std::string	calculate_hmac (const std::string &message, const secure_key &key)
	Calculate HMAC signature.
static void	write_to_audit_log (const std::string &json_entry, const std::string &signature)
	Write entry to audit log file.
static std::mutex &	get_mutex ()
static std::filesystem::path &	get_audit_file ()
static std::unique_ptr< secure_key > &	get_hmac_key ()

Detailed Description

Secure audit logging with tamper detection.

Features:

• JSON-formatted audit entries
• HMAC signatures for tamper detection
• Thread-safe logging
• Configurable audit file location

Definition at line 44 of file audit_logger.h.

Member Enumeration Documentation

audit_event

enum class kcenon::logger::security::audit_logger::audit_event

strong

Types of security-relevant events to audit.

Enumerator
logger_started
logger_stopped
writer_added
writer_removed
encryption_key_loaded
encryption_key_rotated
encryption_key_generated
permission_denied
path_traversal_attempt
insecure_permissions_detected
suspicious_activity
configuration_changed
authentication_success
authentication_failure
file_access_denied
file_access_granted

Definition at line 50 of file audit_logger.h.

                           {
        logger_started,
        logger_stopped,
        writer_added,
        writer_removed,
        encryption_key_loaded,
        encryption_key_rotated,
        encryption_key_generated,
        permission_denied,
        path_traversal_attempt,
        insecure_permissions_detected,
        suspicious_activity,
        configuration_changed,
        authentication_success,
        authentication_failure,
        file_access_denied,
        file_access_granted
    };

Member Function Documentation

calculate_hmac()

static std::string kcenon::logger::security::audit_logger::calculate_hmac ( const std::string & message, const secure_key & key )

inlinestaticprivate

Calculate HMAC signature.

Parameters

message	Message to sign
key	HMAC key

Returns

Hex-encoded signature

Definition at line 271 of file audit_logger.h.

      {
#ifdef HAS_OPENSSL_HMAC
        unsigned char digest[EVP_MAX_MD_SIZE];
        size_t digest_len = 0;
 
        // OpenSSL 3.x EVP_MAC API
        EVP_MAC* mac = EVP_MAC_fetch(nullptr, "HMAC", nullptr);
        if (!mac) {
            return "";
        }
 
        EVP_MAC_CTX* ctx = EVP_MAC_CTX_new(mac);
        if (!ctx) {
            EVP_MAC_free(mac);
            return "";
        }
 
        OSSL_PARAM params[] = {
            OSSL_PARAM_construct_utf8_string(
                OSSL_MAC_PARAM_DIGEST,
                const_cast<char*>("SHA256"),
                0
            ),
            OSSL_PARAM_END
        };
 
        if (EVP_MAC_init(ctx, key.data().data(), key.size(), params) != 1) {
            EVP_MAC_CTX_free(ctx);
            EVP_MAC_free(mac);
            return "";
        }
 
        if (EVP_MAC_update(ctx,
                          reinterpret_cast<const unsigned char*>(message.data()),
                          message.size()) != 1) {
            EVP_MAC_CTX_free(ctx);
            EVP_MAC_free(mac);
            return "";
        }
 
        if (EVP_MAC_final(ctx, digest, &digest_len, sizeof(digest)) != 1) {
            EVP_MAC_CTX_free(ctx);
            EVP_MAC_free(mac);
            return "";
        }
 
        EVP_MAC_CTX_free(ctx);
        EVP_MAC_free(mac);
 
        // Convert to hex string
        std::ostringstream hex;
        hex << std::hex << std::setfill('0');
        for (size_t i = 0; i < digest_len; ++i) {
            hex << std::setw(2) << static_cast<int>(digest[i]);
        }
        return hex.str();
#else
        // Fallback: simple hash (NOT cryptographically secure)
        // In production without OpenSSL, use a proper HMAC library
        size_t hash = 0;
        for (size_t i = 0; i < message.size(); ++i) {
            hash = hash * 31 + message[i];
            if (i < key.size()) {
                hash ^= key.data()[i];
            }
        }
 
        std::ostringstream oss;
        oss << std::hex << std::setfill('0') << std::setw(16) << hash;
        return oss.str();
#endif
    }

References kcenon::logger::security::secure_key::data(), and kcenon::logger::security::secure_key::size().

Referenced by verify_entry().

Here is the call graph for this function:

Here is the caller graph for this function:

escape_json()

static std::string kcenon::logger::security::audit_logger::escape_json ( const std::string & str )

inlinestaticprivate

Escape JSON special characters.

Definition at line 200 of file audit_logger.h.

                                                       {
        std::ostringstream oss;
        for (char c : str) {
            switch (c) {
                case '"':  oss << "\\\""; break;
                case '\\': oss << "\\\\"; break;
                case '\b': oss << "\\b";  break;
                case '\f': oss << "\\f";  break;
                case '\n': oss << "\\n";  break;
                case '\r': oss << "\\r";  break;
                case '\t': oss << "\\t";  break;
                default:
                    if (c < 32) {
                        oss << "\\u" << std::hex << std::setw(4) << std::setfill('0') << static_cast<int>(c);
                    } else {
                        oss << c;
                    }
                    break;
            }
        }
        return oss.str();
    }

event_to_string()

static std::string kcenon::logger::security::audit_logger::event_to_string ( audit_event event )

inlinestaticprivate

Convert audit event to string.

Definition at line 226 of file audit_logger.h.

                                                        {
        switch (event) {
            case audit_event::logger_started:
                return "logger_started";
            case audit_event::logger_stopped:
                return "logger_stopped";
            case audit_event::writer_added:
                return "writer_added";
            case audit_event::writer_removed:
                return "writer_removed";
            case audit_event::encryption_key_loaded:
                return "encryption_key_loaded";
            case audit_event::encryption_key_rotated:
                return "encryption_key_rotated";
            case audit_event::encryption_key_generated:
                return "encryption_key_generated";
            case audit_event::permission_denied:
                return "permission_denied";
            case audit_event::path_traversal_attempt:
                return "path_traversal_attempt";
            case audit_event::insecure_permissions_detected:
                return "insecure_permissions_detected";
            case audit_event::suspicious_activity:
                return "suspicious_activity";
            case audit_event::configuration_changed:
                return "configuration_changed";
            case audit_event::authentication_success:
                return "authentication_success";
            case audit_event::authentication_failure:
                return "authentication_failure";
            case audit_event::file_access_denied:
                return "file_access_denied";
            case audit_event::file_access_granted:
                return "file_access_granted";
            default:
                return "unknown_event";
        }
    }

References authentication_failure, authentication_success, configuration_changed, encryption_key_generated, encryption_key_loaded, encryption_key_rotated, file_access_denied, file_access_granted, insecure_permissions_detected, logger_started, logger_stopped, path_traversal_attempt, permission_denied, suspicious_activity, writer_added, and writer_removed.

format_iso8601()

static std::string kcenon::logger::security::audit_logger::format_iso8601 ( const std::chrono::system_clock::time_point & tp )

inlinestaticprivate

Format timestamp as ISO8601 string.

Definition at line 181 of file audit_logger.h.

      {
        auto time_t_value = std::chrono::system_clock::to_time_t(tp);
        std::tm tm_value;
#ifdef _WIN32
        localtime_s(&tm_value, &time_t_value);
#else
        localtime_r(&time_t_value, &tm_value);
#endif
 
        std::ostringstream oss;
        oss << std::put_time(&tm_value, "%Y-%m-%dT%H:%M:%S");
        return oss.str();
    }

get_audit_file()

static std::filesystem::path & kcenon::logger::security::audit_logger::get_audit_file ( )

inlinestaticprivate

Definition at line 381 of file audit_logger.h.

                                               {
        static std::filesystem::path path;
        return path;
    }

Referenced by initialize(), and write_to_audit_log().

Here is the caller graph for this function:

get_hmac_key()

static std::unique_ptr< secure_key > & kcenon::logger::security::audit_logger::get_hmac_key ( )

inlinestaticprivate

Definition at line 386 of file audit_logger.h.

                                                     {
        static std::unique_ptr<secure_key> key;
        return key;
    }

Referenced by initialize(), and verify_entry().

Here is the caller graph for this function:

get_mutex()

static std::mutex & kcenon::logger::security::audit_logger::get_mutex ( )

inlinestaticprivate

Definition at line 376 of file audit_logger.h.

                                 {
        static std::mutex mutex;
        return mutex;
    }

Referenced by initialize().

Here is the caller graph for this function:

initialize()

static void kcenon::logger::security::audit_logger::initialize ( const std::filesystem::path & audit_file, const secure_key * hmac_key = nullptr )

inlinestatic

Initialize audit logger.

Parameters

audit_file	Path to audit log file
hmac_key	HMAC key for tamper detection (optional)

Definition at line 74 of file audit_logger.h.

      {
        std::lock_guard lock(get_mutex());
 
        get_audit_file() = audit_file;
 
        if (hmac_key) {
            // Create a copy of the key data (secure_key is move-only)
            get_hmac_key().reset(new secure_key(hmac_key->data()));
        }
 
        // Create audit file directory if needed
        auto parent = audit_file.parent_path();
        if (!parent.empty() && !std::filesystem::exists(parent)) {
            std::filesystem::create_directories(parent);
        }
 
        // Set secure permissions on audit file
        if (std::filesystem::exists(audit_file)) {
            std::filesystem::permissions(
                audit_file,
                std::filesystem::perms::owner_read |
                std::filesystem::perms::owner_write,
                std::filesystem::perm_options::replace
            );
        }
    }

References get_audit_file(), get_hmac_key(), and get_mutex().

Here is the call graph for this function:

log_audit_event()

static void kcenon::logger::security::audit_logger::log_audit_event ( audit_event event, const std::string & details, const std::map< std::string, std::string > & metadata = {} )

inlinestatic

Log an audit event.

Parameters

event	Event type
details	Event details
metadata	Additional metadata (key-value pairs)

Definition at line 110 of file audit_logger.h.

                                                       {}
    ) {
        std::lock_guard lock(get_mutex());
 
        // Skip if not initialized
        if (get_audit_file().empty()) {
            return;
        }
 
        // 1. Get current timestamp
        auto now = std::chrono::system_clock::now();
 
        // 2. Build JSON entry
        std::ostringstream oss;
        oss << "{"
            << "\"timestamp\":\"" << format_iso8601(now) << "\","
            << "\"event\":\"" << event_to_string(event) << "\","
            << "\"details\":\"" << escape_json(details) << "\"";
 
        // 3. Add metadata if present
        if (!metadata.empty()) {
            oss << ",\"metadata\":{";
            bool first = true;
            for (const auto& [key, value] : metadata) {
                if (!first) oss << ",";
                oss << "\"" << escape_json(key) << "\":"
                    << "\"" << escape_json(value) << "\"";
                first = false;
            }
            oss << "}";
        }
 
        oss << "}";
 
        std::string json_entry = oss.str();
 
        // 4. Calculate HMAC signature (if key is available)
        std::string signature;
        if (get_hmac_key()) {
            signature = calculate_hmac(json_entry, *get_hmac_key());
        }
 
        // 5. Write to audit file
        write_to_audit_log(json_entry, signature);
    }

Referenced by kcenon::logger::encrypted_writer::encrypted_writer().

Here is the caller graph for this function:

verify_entry()

static bool kcenon::logger::security::audit_logger::verify_entry ( const std::string & json_entry, const std::string & signature )

inlinestatic

Verify integrity of an audit log entry.

Parameters

json_entry	JSON audit entry
signature	HMAC signature

Returns

true if signature is valid, false otherwise

Definition at line 165 of file audit_logger.h.

      {
        if (!get_hmac_key() || signature.empty()) {
            return false;
        }
 
        std::string expected = calculate_hmac(json_entry, *get_hmac_key());
        return expected == signature;
    }

References calculate_hmac(), and get_hmac_key().

Here is the call graph for this function:

write_to_audit_log()

static void kcenon::logger::security::audit_logger::write_to_audit_log ( const std::string & json_entry, const std::string & signature )

inlinestaticprivate

Write entry to audit log file.

Parameters

json_entry	JSON audit entry
signature	HMAC signature (optional)

Definition at line 352 of file audit_logger.h.

      {
        std::ofstream file(get_audit_file(), std::ios::app);
        if (!file) {
            // Cannot log audit event - this is a critical failure
            // In production, consider alternative logging (syslog, etc.)
            return;
        }
 
        // Write JSON entry
        file << json_entry;
 
        // Write signature if present
        if (!signature.empty()) {
            file << "\nSIGNATURE:" << signature;
        }
 
        file << "\n";
        file.flush();
    }

References get_audit_file().

Here is the call graph for this function:

---

The documentation for this class was generated from the following file:

• include/kcenon/logger/security/audit_logger.h