pme_facade.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright 2026 Johnson Ogundeji
#pragma once
 
 
#if !defined(SIGNET_ENABLE_COMMERCIAL) || !SIGNET_ENABLE_COMMERCIAL
#error "pme_facade.hpp requires SIGNET_ENABLE_COMMERCIAL=ON"
#endif
 
#include "signet/crypto/cipher_interface.hpp"
#include "signet/crypto/key_metadata.hpp"
#include "signet/crypto/hkdf.hpp"
#include "signet/crypto/pme.hpp"
#include "signet/error.hpp"
 
#include <array>
#include <cstdint>
#include <memory>
#include <string>
#include <unordered_map>
#include <vector>
 
namespace signet::forge::crypto {
 
// =========================================================================
// Column classification for PME
// =========================================================================
 
enum class ColumnClassification : uint8_t {
    REFERENCE  = 0,  
    FINANCIAL  = 1,  
    PII        = 2,  
    HEALTH     = 3,  
    RESTRICTED = 4,  
};
 
// =========================================================================
// KeyHandle — opaque, RAII, key-zeroing
// =========================================================================
 
class KeyHandle {
public:
    [[nodiscard]] static KeyHandle generate() {
        KeyHandle h;
        detail::cipher::fill_random_bytes(h.key_.data(), KEY_SIZE);
        detail::secure_mem::lock_memory(h.key_.data(), KEY_SIZE);
        h.valid_ = true;
        return h;
    }
 
    [[nodiscard]] static KeyHandle from_bytes(const uint8_t* data, size_t size) {
        if (size != KEY_SIZE) {
            throw std::invalid_argument(
                "KeyHandle requires exactly 32 bytes (AES-256), got " +
                std::to_string(size));
        }
        KeyHandle h;
        std::memcpy(h.key_.data(), data, KEY_SIZE);
        detail::secure_mem::lock_memory(h.key_.data(), KEY_SIZE);
        h.valid_ = true;
        return h;
    }
 
    [[nodiscard]] static KeyHandle from_seed(const std::string& seed) {
        KeyHandle h;
        auto prk = hkdf_extract(nullptr, 0,
            reinterpret_cast<const uint8_t*>(seed.data()), seed.size());
        hkdf_expand(prk,
            reinterpret_cast<const uint8_t*>("signet-pme-test-key"),
            19, h.key_.data(), KEY_SIZE);
        detail::secure_mem::lock_memory(h.key_.data(), KEY_SIZE);
        h.valid_ = true;
        return h;
    }
 
    ~KeyHandle() {
        if (valid_) {
            detail::secure_mem::secure_zero(key_.data(), KEY_SIZE);
            detail::secure_mem::unlock_memory(key_.data(), KEY_SIZE);
            valid_ = false;
        }
    }
 
    // Move-only (no copy — prevents key duplication)
    KeyHandle(KeyHandle&& other) noexcept
        : key_(other.key_), valid_(other.valid_) {
        if (other.valid_) {
            std::memset(other.key_.data(), 0, KEY_SIZE);
            other.valid_ = false;
        }
    }
    KeyHandle& operator=(KeyHandle&& other) noexcept {
        if (this != &other) {
            if (valid_) {
                detail::secure_mem::secure_zero(key_.data(), KEY_SIZE);
                detail::secure_mem::unlock_memory(key_.data(), KEY_SIZE);
            }
            key_ = other.key_;
            valid_ = other.valid_;
            if (other.valid_) {
                std::memset(other.key_.data(), 0, KEY_SIZE);
                other.valid_ = false;
            }
        }
        return *this;
    }
    KeyHandle(const KeyHandle&) = delete;
    KeyHandle& operator=(const KeyHandle&) = delete;
 
    [[nodiscard]] bool is_valid() const noexcept { return valid_; }
 
    static constexpr size_t key_size() noexcept { return KEY_SIZE; }
 
    // -- Internal access (C++ only, NOT exposed to Python) --
 
    [[nodiscard]] const uint8_t* data() const noexcept { return key_.data(); }
 
    [[nodiscard]] std::vector<uint8_t> to_vector() const {
        return std::vector<uint8_t>(key_.begin(), key_.end());
    }
 
private:
    KeyHandle() : key_{}, valid_(false) {}
    static constexpr size_t KEY_SIZE = 32;
    std::array<uint8_t, KEY_SIZE> key_;
    bool valid_;
};
 
// =========================================================================
// EncryptedWriterOptions — high-level config that builds EncryptionConfig
// =========================================================================
 
struct EncryptedWriterOptions {
    EncryptionAlgorithm algorithm = EncryptionAlgorithm::AES_GCM_CTR_V1;
 
    bool encrypt_footer = true;
 
    std::string aad_prefix = "signet-forge-pme";
 
    std::unordered_map<std::string, ColumnClassification> column_classes;
 
    void classify(const std::string& column_name, ColumnClassification cls) {
        column_classes[column_name] = cls;
    }
 
    [[nodiscard]] EncryptionConfig build_config(const KeyHandle& master_key) const {
        if (!master_key.is_valid()) {
            throw std::runtime_error("KeyHandle is not valid (moved or not initialised)");
        }
 
        EncryptionConfig config;
        config.algorithm = algorithm;
        config.encrypt_footer = encrypt_footer;
        config.footer_key = master_key.to_vector();
        config.aad_prefix = aad_prefix;
        config.key_mode = KeyMode::INTERNAL;
 
        // Derive per-column keys via HKDF
        for (const auto& [col_name, cls] : column_classes) {
            if (cls == ColumnClassification::REFERENCE) continue;
 
            // HKDF info = "signet-pme-col:" + classification + ":" + column_name
            std::string info = "signet-pme-col:" +
                std::to_string(static_cast<int>(cls)) + ":" + col_name;
 
            ColumnKeySpec spec;
            spec.column_name = col_name;
            spec.key.resize(32);
 
            auto prk = hkdf_extract(nullptr, 0,
                master_key.data(), KeyHandle::key_size());
            (void)hkdf_expand(prk,
                reinterpret_cast<const uint8_t*>(info.data()),
                info.size(), spec.key.data(), 32);
 
            config.column_keys.push_back(std::move(spec));
        }
 
        return config;
    }
};
 
// =========================================================================
// EncryptedReaderOptions — high-level config for decryption + RBAC
// =========================================================================
 
struct EncryptedReaderOptions {
    EncryptionAlgorithm algorithm = EncryptionAlgorithm::AES_GCM_CTR_V1;
 
    bool encrypted_footer = true;
 
    std::string aad_prefix = "signet-forge-pme";
 
    std::unordered_map<std::string, ColumnClassification> column_classes;
 
    std::vector<std::string> authorised_columns;
 
    void classify(const std::string& column_name, ColumnClassification cls) {
        column_classes[column_name] = cls;
    }
 
    void authorise(const std::string& column_name) {
        authorised_columns.push_back(column_name);
    }
 
    [[nodiscard]] bool is_authorised(const std::string& column_name) const {
        if (authorised_columns.empty()) return true;  // empty = full access
        for (const auto& name : authorised_columns) {
            if (name == column_name) return true;
        }
        return false;
    }
 
    [[nodiscard]] EncryptionConfig build_config(const KeyHandle& master_key) const {
        if (!master_key.is_valid()) {
            throw std::runtime_error("KeyHandle is not valid");
        }
 
        EncryptionConfig config;
        config.algorithm = algorithm;
        config.encrypt_footer = encrypted_footer;
        config.footer_key = master_key.to_vector();
        config.aad_prefix = aad_prefix;
        config.key_mode = KeyMode::INTERNAL;
 
        for (const auto& [col_name, cls] : column_classes) {
            if (cls == ColumnClassification::REFERENCE) continue;
            if (!is_authorised(col_name)) continue;  // RBAC: skip unauthorised
 
            std::string info = "signet-pme-col:" +
                std::to_string(static_cast<int>(cls)) + ":" + col_name;
 
            ColumnKeySpec spec;
            spec.column_name = col_name;
            spec.key.resize(32);
 
            auto prk = hkdf_extract(nullptr, 0,
                master_key.data(), KeyHandle::key_size());
            (void)hkdf_expand(prk,
                reinterpret_cast<const uint8_t*>(info.data()),
                info.size(), spec.key.data(), 32);
 
            config.column_keys.push_back(std::move(spec));
        }
 
        return config;
    }
};
 
} // namespace signet::forge::crypto