kcenon::pacs::security::audit_key_manager Class Reference

Holds the active encryption key and any retired keys for decryption of historical records. More...

#include <audit_log_cipher.h>

Collaboration diagram for kcenon::pacs::security::audit_key_manager:

Public Member Functions
	audit_key_manager ()=default
void	register_key (audit_cipher_key key)
	Register a key (idempotent by key_id; overwrites existing entry)
VoidResult	set_active (const std::string &key_id)
	Mark a previously-registered key as the active write key.
const audit_cipher_key *	find (const std::string &key_id) const
	Look up a key by identifier (returns nullptr if unknown)
Result< audit_cipher_key >	active () const
	Retrieve the active write key (error if none configured)
void	forget (const std::string &key_id)
	Drop a key by id (does nothing if it was not registered)
std::size_t	size () const
	Number of registered keys.
VoidResult	load_from_env ()
	Load keys from environment variables.

Static Public Member Functions
static VoidResult	decode_key (const std::string &encoded, std::uint8_t *out, std::size_t out_size)
	Decode a hex or base64 key string into a fixed-size buffer.

Private Attributes
std::mutex	mutex_
std::unordered_map< std::string, audit_cipher_key >	keys_
std::string	active_id_

Detailed Description

Holds the active encryption key and any retired keys for decryption of historical records.

A single "active" key is used for all new writes. Any number of additional keys (including the former active key) may be registered so that previously-written records remain verifiable after rotation.

Thread-safety: all public operations are internally synchronised.

Key sourcing: in production, populate via load_from_env() which reads PACS_AUDIT_LOG_ACTIVE_KEY_ID plus PACS_AUDIT_LOG_KEY_<id> and PACS_AUDIT_LOG_MAC_<id> (both hex- or base64-encoded). NEVER hard-code keys in source. Rotation procedure: provision a new <id>, update PACS_AUDIT_LOG_ACTIVE_KEY_ID, keep the previous key registered for as long as historical records are retained.

Definition at line 123 of file audit_log_cipher.h.

Constructor & Destructor Documentation

audit_key_manager()

kcenon::pacs::security::audit_key_manager::audit_key_manager ( )

default

Member Function Documentation

active()

Result< audit_cipher_key > kcenon::pacs::security::audit_key_manager::active ( ) const

nodiscard

Retrieve the active write key (error if none configured)

Definition at line 202 of file audit_log_cipher.cpp.

                                                         {
    std::lock_guard<std::mutex> lock(mutex_);
    if (active_id_.empty()) {
        return pacs_error<audit_cipher_key>(
            kcenon::common::error::codes::common_errors::not_found,
            "no active audit encryption key configured");
    }
    auto it = keys_.find(active_id_);
    if (it == keys_.end()) {
        return pacs_error<audit_cipher_key>(
            kcenon::common::error::codes::common_errors::internal_error,
            "active audit key missing from key store: " + active_id_);
    }
    return kcenon::common::Result<audit_cipher_key>(it->second);
}

References active_id_, keys_, mutex_, and kcenon::pacs::pacs_error().

Referenced by load_from_env().

Here is the call graph for this function:

Here is the caller graph for this function:

decode_key()

VoidResult kcenon::pacs::security::audit_key_manager::decode_key ( const std::string & encoded, std::uint8_t * out, std::size_t out_size )

staticnodiscard

Decode a hex or base64 key string into a fixed-size buffer.

Accepts:

• lowercase/uppercase hexadecimal of exactly 2*N characters, or
• base64 (standard alphabet, padding required) of N bytes

Parameters

encoded	the encoded string
out	destination buffer; must be exactly out_size bytes
out_size	size of the destination buffer; must equal the key length N

Returns

VoidResult success or decode error

Definition at line 229 of file audit_log_cipher.cpp.

                                                             {
    if (encoded.empty() || out == nullptr || out_size == 0) {
        return pacs_void_error(
            kcenon::common::error::codes::common_errors::invalid_argument,
            "empty key encoding or invalid buffer");
    }
 
    // Hex first: encoded length must be exactly 2 * out_size
    if (encoded.size() == out_size * 2) {
        if (detail::hex_decode(encoded, out, out_size)) {
            return kcenon::common::ok();
        }
        // fall through — may still be base64 of the same length
    }
 
    std::vector<std::uint8_t> decoded;
    if (!detail::base64_decode(encoded, decoded)) {
        return pacs_void_error(
            kcenon::common::error::codes::common_errors::invalid_argument,
            "audit key is neither valid hex nor base64");
    }
    if (decoded.size() != out_size) {
        return pacs_void_error(
            kcenon::common::error::codes::common_errors::invalid_argument,
            "audit key has wrong length after decoding");
    }
    std::memcpy(out, decoded.data(), out_size);
    // wipe temporary copy
    volatile std::uint8_t* p = decoded.data();
    for (std::size_t i = 0; i < decoded.size(); ++i) p[i] = 0;
    return kcenon::common::ok();
}

References kcenon::pacs::security::detail::base64_decode(), kcenon::pacs::security::detail::hex_decode(), out, and kcenon::pacs::pacs_void_error().

Referenced by load_from_env().

Here is the call graph for this function:

Here is the caller graph for this function:

find()

const audit_cipher_key * kcenon::pacs::security::audit_key_manager::find ( const std::string & key_id ) const

nodiscard

Look up a key by identifier (returns nullptr if unknown)

Definition at line 195 of file audit_log_cipher.cpp.

                                   {
    std::lock_guard<std::mutex> lock(mutex_);
    auto it = keys_.find(key_id);
    return it == keys_.end() ? nullptr : &it->second;
}

References keys_, and mutex_.

Referenced by load_from_env().

Here is the caller graph for this function:

forget()

void kcenon::pacs::security::audit_key_manager::forget

(

const std::string &

key_id

)

Drop a key by id (does nothing if it was not registered)

Definition at line 218 of file audit_log_cipher.cpp.

                                                      {
    std::lock_guard<std::mutex> lock(mutex_);
    keys_.erase(key_id);
    if (active_id_ == key_id) active_id_.clear();
}

References active_id_, keys_, and mutex_.

load_from_env()

VoidResult kcenon::pacs::security::audit_key_manager::load_from_env ( )

nodiscard

Load keys from environment variables.

Reads:

• PACS_AUDIT_LOG_ACTIVE_KEY_ID — the active write key id
• PACS_AUDIT_LOG_KEYS — comma-separated list of ids to load (optional; defaults to the active id only)
• PACS_AUDIT_LOG_KEY_<id> — 32-byte data key, hex or base64
• PACS_AUDIT_LOG_MAC_<id> — 32-byte MAC key, hex or base64

Returns

VoidResult reporting the first configuration error, if any

Definition at line 290 of file audit_log_cipher.cpp.

                                            {
    const std::string active = getenv_str("PACS_AUDIT_LOG_ACTIVE_KEY_ID");
    if (active.empty()) {
        return pacs_void_error(
            kcenon::common::error::codes::common_errors::invalid_argument,
            "PACS_AUDIT_LOG_ACTIVE_KEY_ID is not set");
    }
 
    std::vector<std::string> ids;
    const std::string list = getenv_str("PACS_AUDIT_LOG_KEYS");
    if (list.empty()) {
        ids.push_back(active);
    } else {
        ids = split_csv(list);
        if (std::find(ids.begin(), ids.end(), active) == ids.end()) {
            ids.push_back(active);
        }
    }
 
    for (const auto& id : ids) {
        if (id.empty() || id.find('|') != std::string::npos) {
            return pacs_void_error(
                kcenon::common::error::codes::common_errors::invalid_argument,
                "invalid audit key id: '" + id + "'");
        }
        const std::string key_env = "PACS_AUDIT_LOG_KEY_" + id;
        const std::string mac_env = "PACS_AUDIT_LOG_MAC_" + id;
        const std::string key_val = getenv_str(key_env.c_str());
        const std::string mac_val = getenv_str(mac_env.c_str());
        if (key_val.empty() || mac_val.empty()) {
            return pacs_void_error(
                kcenon::common::error::codes::common_errors::invalid_argument,
                "missing env var for audit key '" + id + "'");
        }
 
        audit_cipher_key k;
        k.key_id = id;
        auto r1 = decode_key(key_val, k.data_key.data(), k.data_key.size());
        if (!r1.is_ok()) {
            return pacs_void_error(
                kcenon::common::error::codes::common_errors::invalid_argument,
                "failed to decode " + key_env);
        }
        auto r2 = decode_key(mac_val, k.mac_key.data(), k.mac_key.size());
        if (!r2.is_ok()) {
            return pacs_void_error(
                kcenon::common::error::codes::common_errors::invalid_argument,
                "failed to decode " + mac_env);
        }
        register_key(std::move(k));
    }
 
    return set_active(active);
}

References active(), kcenon::pacs::security::audit_cipher_key::data_key, decode_key(), kcenon::pacs::security::empty, find(), kcenon::pacs::security::audit_cipher_key::key_id, kcenon::pacs::security::list, kcenon::pacs::security::audit_cipher_key::mac_key, kcenon::pacs::pacs_void_error(), register_key(), and set_active().

Here is the call graph for this function:

register_key()

void kcenon::pacs::security::audit_key_manager::register_key

(

audit_cipher_key

key

)

Register a key (idempotent by key_id; overwrites existing entry)

Definition at line 177 of file audit_log_cipher.cpp.

                                                         {
    std::lock_guard<std::mutex> lock(mutex_);
    const std::string id = key.key_id;
    keys_[id] = std::move(key);
    if (active_id_.empty()) active_id_ = id;
}

References active_id_, kcenon::pacs::security::audit_cipher_key::key_id, keys_, and mutex_.

Referenced by load_from_env().

Here is the caller graph for this function:

set_active()

VoidResult kcenon::pacs::security::audit_key_manager::set_active ( const std::string & key_id )

nodiscard

Mark a previously-registered key as the active write key.

Definition at line 184 of file audit_log_cipher.cpp.

                                                                {
    std::lock_guard<std::mutex> lock(mutex_);
    if (keys_.find(key_id) == keys_.end()) {
        return pacs_void_error(
            kcenon::common::error::codes::common_errors::not_found,
            "audit key not registered: " + key_id);
    }
    active_id_ = key_id;
    return kcenon::common::ok();
}

References active_id_, keys_, mutex_, and kcenon::pacs::pacs_void_error().

Referenced by load_from_env().

Here is the call graph for this function:

Here is the caller graph for this function:

size()

std::size_t kcenon::pacs::security::audit_key_manager::size ( ) const

nodiscard

Number of registered keys.

Definition at line 224 of file audit_log_cipher.cpp.

                                        {
    std::lock_guard<std::mutex> lock(mutex_);
    return keys_.size();
}

References keys_, and mutex_.

Member Data Documentation

active_id_

std::string kcenon::pacs::security::audit_key_manager::active_id_

private

Definition at line 180 of file audit_log_cipher.h.

Referenced by active(), forget(), register_key(), and set_active().

keys_

std::unordered_map<std::string, audit_cipher_key> kcenon::pacs::security::audit_key_manager::keys_

private

Definition at line 179 of file audit_log_cipher.h.

Referenced by active(), find(), forget(), register_key(), set_active(), and size().

mutex_

std::mutex kcenon::pacs::security::audit_key_manager::mutex_

mutableprivate

Definition at line 178 of file audit_log_cipher.h.

Referenced by active(), find(), forget(), register_key(), set_active(), and size().

---

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

• include/kcenon/pacs/security/audit_log_cipher.h
• src/security/audit_log_cipher.cpp