key_lock Class

namespace keychain → class key_lock

Overview

The key_lock class provides access control mechanisms for encrypted data, enabling fine-grained permission management and secure key escrow for multi-recipient encryption scenarios.

Class Hierarchy

namespace keychain {
    class key_lock : public serializable {
        // Access control for encrypted data
    };
}

Constructor

key_lock();
key_lock(const std::string& lock_id);
key_lock(const key_lock& other);

Properties

Lock Identity

std::string get_lock_id() const;
void set_lock_id(const std::string& id);

std::string get_description() const;
void set_description(const std::string& description);

Unique identification and description of the key lock.

Access Control

std::vector<std::string> get_authorized_dids() const;
void add_authorized_did(const std::string& did);
void remove_authorized_did(const std::string& did);
bool is_authorized(const std::string& did) const;

std::vector<std::string> get_required_signatures() const;
void set_required_signatures(const std::vector<std::string>& dids);
size_t get_signature_threshold() const;
void set_signature_threshold(size_t threshold);

Multi-signature and authorization management.

Time-Based Access

std::chrono::system_clock::time_point get_valid_from() const;
void set_valid_from(const std::chrono::system_clock::time_point& time);

std::chrono::system_clock::time_point get_valid_until() const;
void set_valid_until(const std::chrono::system_clock::time_point& time);

bool is_time_valid() const;
bool is_time_valid(const std::chrono::system_clock::time_point& check_time) const;

Time-based access restrictions.

Usage Constraints

size_t get_max_uses() const;
void set_max_uses(size_t max_uses);

size_t get_current_uses() const;
bool increment_usage();

bool is_usage_valid() const;

Usage count limitations and tracking.

Methods

Lock Operations

bool unlock(const std::vector<std::string>& signatures);
bool unlock(const std::string& signature);

bool is_unlocked() const;
void lock();

std::string get_unlock_token() const;
bool verify_unlock_token(const std::string& token) const;

Core lock/unlock functionality with signature verification.

Key Management

std::string get_encrypted_key() const;
void set_encrypted_key(const std::string& encrypted_key);

std::vector<uint8_t> decrypt_key(const std::vector<std::string>& signatures) const;
bool verify_key_integrity() const;

Encrypted key storage and retrieval.

Policy Enforcement

bool check_access_policy(const std::string& requester_did) const;
bool check_all_policies() const;

std::vector<std::string> get_policy_violations() const;
void add_custom_policy(std::function<bool(const std::string&)> policy);

Flexible policy enforcement mechanisms.

Audit and Logging

struct access_log_entry {
    std::string requester_did;
    std::chrono::system_clock::time_point timestamp;
    bool access_granted;
    std::string reason;
};

std::vector<access_log_entry> get_access_log() const;
void log_access_attempt(const std::string& requester_did, bool granted,
                       const std::string& reason = "");

Access attempt logging and audit trails.

Serialization

std::string to_json() const;
std::string to_xml() const;
std::vector<uint8_t> to_protobuf() const;

static key_lock from_json(const std::string& json);
static key_lock from_xml(const std::string& xml);
static key_lock from_protobuf(const std::vector<uint8_t>& data);

Usage Examples

Basic Key Lock Creation

#include <keychain/keychain.h>

// Create a simple key lock
keychain::key_lock document_lock("doc_2024_q1_report");
document_lock.set_description("Access lock for Q1 2024 financial report");

// Add authorized users
document_lock.add_authorized_did("did:keychain:alice.finance");
document_lock.add_authorized_did("did:keychain:bob.management");
document_lock.add_authorized_did("did:keychain:carol.audit");

// Set time-based restrictions
auto now = std::chrono::system_clock::now();
auto valid_until = now + std::chrono::hours(24 * 30); // Valid for 30 days
document_lock.set_valid_from(now);
document_lock.set_valid_until(valid_until);

// Set usage limits
document_lock.set_max_uses(50); // Maximum 50 accesses

std::cout << "Key lock created for document access control" << std::endl;

Multi-Signature Key Lock

// Create multi-signature lock requiring 2 of 3 signatures
keychain::key_lock critical_data_lock("critical_system_backup");
critical_data_lock.set_description("Critical system backup access");

// Define required signers
std::vector<std::string> required_signers = {
    "did:keychain:admin.primary",
    "did:keychain:admin.secondary",
    "did:keychain:security.officer"
};
critical_data_lock.set_required_signatures(required_signers);
critical_data_lock.set_signature_threshold(2); // Require 2 of 3 signatures

// Set encrypted key
std::string encrypted_backup_key = gateway.encrypt_key_for_lock(backup_key, critical_data_lock);
critical_data_lock.set_encrypted_key(encrypted_backup_key);

// Access attempt with multiple signatures
std::vector<std::string> signatures = {
    gateway.sign_unlock_request(admin1, critical_data_lock),
    gateway.sign_unlock_request(security_officer, critical_data_lock)
};

if (critical_data_lock.unlock(signatures)) {
    auto decrypted_key = critical_data_lock.decrypt_key(signatures);
    std::cout << "Critical data access granted" << std::endl;
    // Use decrypted_key to access backup data
} else {
    std::cout << "Access denied - insufficient signatures" << std::endl;
}

Time-Sensitive Emergency Access

// Emergency access lock with time constraints
keychain::key_lock emergency_lock("emergency_override_2024_01");
emergency_lock.set_description("Emergency system override access");

// Emergency window: 1 hour from activation
auto emergency_start = std::chrono::system_clock::now();
auto emergency_end = emergency_start + std::chrono::hours(1);
emergency_lock.set_valid_from(emergency_start);
emergency_lock.set_valid_until(emergency_end);

// Limited uses during emergency
emergency_lock.set_max_uses(5);

// Authorized emergency responders
emergency_lock.add_authorized_did("did:keychain:emergency.response.team");
emergency_lock.add_authorized_did("did:keychain:system.administrator");

// Check if emergency window is active
if (emergency_lock.is_time_valid()) {
    std::cout << "Emergency access window is active" << std::endl;

    // Attempt access
    std::string emergency_signature = gateway.sign_emergency_request(emergency_responder, emergency_lock);

    if (emergency_lock.unlock({emergency_signature})) {
        if (emergency_lock.increment_usage()) {
            std::cout << "Emergency access granted. Uses remaining: "
                     << (emergency_lock.get_max_uses() - emergency_lock.get_current_uses()) << std::endl;
        } else {
            std::cout << "Emergency access limit exceeded" << std::endl;
        }
    }
} else {
    std::cout << "Emergency access window has expired" << std::endl;
}

Policy-Based Access Control

// Advanced policy-based key lock
keychain::key_lock policy_lock("sensitive_research_data");
policy_lock.set_description("Research data with complex access policies");

// Basic authorization
policy_lock.add_authorized_did("did:keychain:researcher.alice");
policy_lock.add_authorized_did("did:keychain:researcher.bob");
policy_lock.add_authorized_did("did:keychain:supervisor.carol");

// Custom policies
policy_lock.add_custom_policy([](const std::string& requester_did) -> bool {
    // Only allow access during business hours (9 AM - 5 PM)
    auto now = std::chrono::system_clock::now();
    auto time_t = std::chrono::system_clock::to_time_t(now);
    auto local_time = *std::localtime(&time_t);

    int hour = local_time.tm_hour;
    return (hour >= 9 && hour < 17);
});

policy_lock.add_custom_policy([](const std::string& requester_did) -> bool {
    // Only allow access on weekdays
    auto now = std::chrono::system_clock::now();
    auto time_t = std::chrono::system_clock::to_time_t(now);
    auto local_time = *std::localtime(&time_t);

    int weekday = local_time.tm_wday;
    return (weekday >= 1 && weekday <= 5); // Monday-Friday
});

// Check access with policies
bool check_research_access(const std::string& requester_did) {
    if (!policy_lock.check_access_policy(requester_did)) {
        auto violations = policy_lock.get_policy_violations();
        std::cout << "Access denied. Policy violations:" << std::endl;
        for (const auto& violation : violations) {
            std::cout << "  - " << violation << std::endl;
        }
        return false;
    }
    return true;
}

Audit Trail and Monitoring

// Monitor and audit key lock usage
void audit_key_lock_usage(const keychain::key_lock& lock) {
    auto access_log = lock.get_access_log();

    std::cout << "Access log for lock: " << lock.get_lock_id() << std::endl;
    std::cout << "Total access attempts: " << access_log.size() << std::endl;

    size_t granted_count = 0;
    size_t denied_count = 0;

    for (const auto& entry : access_log) {
        if (entry.access_granted) {
            granted_count++;
        } else {
            denied_count++;
        }

        auto time_t = std::chrono::system_clock::to_time_t(entry.timestamp);
        std::cout << "  " << std::ctime(&time_t)
                 << " - " << entry.requester_did
                 << " - " << (entry.access_granted ? "GRANTED" : "DENIED")
                 << " - " << entry.reason << std::endl;
    }

    std::cout << "Summary: " << granted_count << " granted, "
             << denied_count << " denied" << std::endl;

    // Check for suspicious patterns
    if (denied_count > granted_count * 2) {
        std::cout << "WARNING: High number of access denials detected" << std::endl;
    }
}

// Real-time monitoring
void setup_lock_monitoring(keychain::key_lock& lock) {
    // Override access attempt logging for real-time alerts
    auto original_log_function = lock.get_log_function();

    lock.set_log_function([=](const std::string& requester, bool granted, const std::string& reason) {
        // Call original logging
        original_log_function(requester, granted, reason);

        // Real-time monitoring
        if (!granted) {
            std::cout << "SECURITY ALERT: Access denied for " << requester
                     << " - Reason: " << reason << std::endl;

            // Send alert to security team
            send_security_alert("Key lock access denied", requester, reason);
        }

        // Check for repeated failed attempts
        auto recent_failures = count_recent_failures(lock, requester, std::chrono::minutes(10));
        if (recent_failures >= 3) {
            std::cout << "SECURITY WARNING: Multiple failed attempts by " << requester << std::endl;
            temporarily_block_requester(requester, std::chrono::minutes(30));
        }
    });
}

Integration with Encrypted Data

// Use key locks with encrypted data
void demonstrate_encrypted_data_integration() {
    // Create sensitive document
    std::string sensitive_document = "Confidential merger & acquisition details...";

    // Create key lock for document access
    keychain::key_lock document_lock("ma_deal_2024");
    document_lock.add_authorized_did("did:keychain:ceo");
    document_lock.add_authorized_did("did:keychain:cfo");
    document_lock.add_authorized_did("did:keychain:legal.counsel");
    document_lock.set_signature_threshold(2); // Require 2 signatures

    // Encrypt document with key lock protection
    keychain::encrypted_data protected_document = gateway.encrypt_with_lock(
        author_persona,
        sensitive_document,
        document_lock
    );

    // Store the protected document
    store_encrypted_document("ma_deal_2024.kc", protected_document);

    // Later: Access the document
    auto stored_document = load_encrypted_document("ma_deal_2024.kc");
    auto embedded_lock = stored_document.get_key_lock();

    // Provide required signatures
    std::vector<std::string> executive_signatures = {
        gateway.sign_unlock_request(ceo_persona, embedded_lock),
        gateway.sign_unlock_request(cfo_persona, embedded_lock)
    };

    if (embedded_lock.unlock(executive_signatures)) {
        std::string decrypted_content = gateway.decrypt_with_lock(
            executive_persona, stored_document, embedded_lock
        );
        std::cout << "Document accessed successfully" << std::endl;
    } else {
        std::cout << "Insufficient authorization for document access" << std::endl;
    }
}

JSON Structure

{
  "lock_id": "critical_system_backup",
  "description": "Critical system backup access",
  "authorized_dids": [
    "did:keychain:admin.primary",
    "did:keychain:admin.secondary",
    "did:keychain:security.officer"
  ],
  "required_signatures": [
    "did:keychain:admin.primary",
    "did:keychain:admin.secondary",
    "did:keychain:security.officer"
  ],
  "signature_threshold": 2,
  "time_constraints": {
    "valid_from": "2024-01-15T10:00:00Z",
    "valid_until": "2024-02-15T10:00:00Z"
  },
  "usage_constraints": {
    "max_uses": 50,
    "current_uses": 23
  },
  "encrypted_key": "AES256_ENCRYPTED_KEY_DATA...",
  "status": {
    "unlocked": false,
    "last_access": "2024-01-20T14:30:00Z"
  }
}

Security Considerations

Key Protection

  • Encrypted keys should use strong encryption

  • Key derivation should include lock-specific salt

  • Consider hardware security modules for high-value keys

Signature Verification

  • Verify signature authenticity and non-repudiation

  • Check signature timestamps for replay protection

  • Validate signer authorization at verification time

Access Logging

  • Log all access attempts (successful and failed)

  • Include sufficient detail for forensic analysis

  • Protect audit logs from tampering

See Also

  • gateway - Key lock operations

  • {access-control-models}[Access Control Models]

  • {multi-signature-schemes}[Multi-Signature Cryptography]

  • {time-based-access}[Time-Based Access Control]