keychain_element Class

namespace keychain → class keychain_element

Overview

The keychain_element class represents an individual cryptographic key element within a keychain, providing detailed key management, usage tracking, and lifecycle operations.

Class Hierarchy

namespace keychain {
    class keychain_element : public serializable {
        // Individual cryptographic key element
    };
}

Constructor

keychain_element();
keychain_element(const std::string& element_id);
keychain_element(const keychain_element& other);

Properties

Element Identity

std::string get_element_id() const;
void set_element_id(const std::string& id);

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

std::string get_purpose() const;
void set_purpose(const std::string& purpose);

Unique identification and descriptive information.

Key Material

std::string get_public_key() const;
std::string get_public_key_hex() const;
std::vector<uint8_t> get_public_key_bytes() const;

bool has_private_key() const;
std::string get_private_key_fingerprint() const;

Access to public key material and private key status.

Algorithm Information

encryption_scheme get_encryption_scheme() const;
void set_encryption_scheme(encryption_scheme scheme);

signature_scheme get_signature_scheme() const;
void set_signature_scheme(signature_scheme scheme);

std::string get_algorithm_identifier() const;
size_t get_key_size_bits() const;

Cryptographic algorithm and key size details.

Lifecycle Timestamps

std::chrono::system_clock::time_point get_created_time() const;
std::chrono::system_clock::time_point get_last_used_time() const;
std::chrono::system_clock::time_point get_expiration_time() const;
void set_expiration_time(const std::chrono::system_clock::time_point& time);

bool is_expired() const;
bool is_active() const;

Key lifecycle and validity tracking.

Usage Statistics

size_t get_usage_count() const;
size_t get_signature_count() const;
size_t get_encryption_count() const;
size_t get_decryption_count() const;

void increment_usage();
void reset_usage_statistics();

Detailed usage tracking and statistics.

Security Status

bool is_compromised() const;
void mark_compromised(const std::string& reason = "");
std::string get_compromise_reason() const;

bool is_revoked() const;
void revoke(const std::string& reason = "");
std::string get_revocation_reason() const;

Security incident tracking and revocation.

Methods

Key Operations

// Encryption operations (for encryption elements)
std::vector<uint8_t> encrypt(const std::vector<uint8_t>& plaintext) const;
std::vector<uint8_t> decrypt(const std::vector<uint8_t>& ciphertext) const;

// Signature operations (for signature elements)
std::vector<uint8_t> sign(const std::vector<uint8_t>& data) const;
bool verify(const std::vector<uint8_t>& data, const std::vector<uint8_t>& signature) const;

Core cryptographic operations using this element.

Key Derivation

keychain_element derive_child_element(const std::string& derivation_path) const;
keychain_element derive_element_for_purpose(const std::string& purpose) const;

bool supports_key_derivation() const;
std::vector<std::string> get_derived_element_paths() const;

Hierarchical key derivation support.

Key Export/Import

std::string export_public_key_pem() const;
std::string export_public_key_jwk() const;

std::string export_private_key_pem(const std::string& passphrase) const;
std::string export_private_key_jwk(const std::string& passphrase) const;

void import_public_key_pem(const std::string& pem_data);
void import_private_key_pem(const std::string& pem_data, const std::string& passphrase);

Key material export and import in standard formats.

Validation and Testing

bool validate_element() const;
std::vector<std::string> get_validation_errors() const;

bool test_key_operations() const;
std::vector<std::string> perform_self_test() const;

Element integrity checking and operational testing.

Serialization

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

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

Usage Examples

Creating and Managing Key Elements

#include <keychain/keychain.h>

// Create a new signature element
keychain::keychain_element signature_element;
signature_element.set_element_id("sig_elem_001");
signature_element.set_description("Primary signing key for contracts");
signature_element.set_purpose("document_signing");

// Configure algorithm
signature_element.set_signature_scheme(keychain::signature_scheme::ECDSA_P256_SHA256);

// Generate key pair (implementation would create actual keys)
// signature_element.generate_key_pair();

std::cout << "Created signature element:" << std::endl;
std::cout << "  ID: " << signature_element.get_element_id() << std::endl;
std::cout << "  Algorithm: " << signature_element.get_algorithm_identifier() << std::endl;
std::cout << "  Key size: " << signature_element.get_key_size_bits() << " bits" << std::endl;

// Set expiration (1 year from now)
auto expiration = std::chrono::system_clock::now() + std::chrono::hours(24 * 365);
signature_element.set_expiration_time(expiration);

// Check status
std::cout << "  Active: " << signature_element.is_active() << std::endl;
std::cout << "  Expired: " << signature_element.is_expired() << std::endl;

Signature Operations with Usage Tracking

// Use signature element for document signing
void demonstrate_signature_element() {
    keychain::keychain_element signing_key;
    signing_key.set_element_id("contract_signer");
    signing_key.set_signature_scheme(keychain::signature_scheme::ECDSA_P384_SHA384);

    // Document to sign
    std::string contract = "Service Agreement between Alice Corp and Bob Ltd...";
    std::vector<uint8_t> contract_data(contract.begin(), contract.end());

    // Sign the contract
    auto signature = signing_key.sign(contract_data);
    signing_key.increment_usage(); // Track usage

    std::cout << "Contract signed:" << std::endl;
    std::cout << "  Signature size: " << signature.size() << " bytes" << std::endl;
    std::cout << "  Element usage count: " << signing_key.get_usage_count() << std::endl;
    std::cout << "  Total signatures: " << signing_key.get_signature_count() << std::endl;

    // Verify the signature
    bool is_valid = signing_key.verify(contract_data, signature);
    std::cout << "  Signature verification: " << (is_valid ? "VALID" : "INVALID") << std::endl;

    // Check last used time
    auto last_used = signing_key.get_last_used_time();
    auto now = std::chrono::system_clock::now();
    auto time_since_use = std::chrono::duration_cast<std::chrono::seconds>(now - last_used);
    std::cout << "  Last used: " << time_since_use.count() << " seconds ago" << std::endl;
}

Encryption Element Operations

// Use encryption element for data protection
void demonstrate_encryption_element() {
    keychain::keychain_element encryption_key;
    encryption_key.set_element_id("data_protector");
    encryption_key.set_description("Sensitive data encryption key");
    encryption_key.set_encryption_scheme(keychain::encryption_scheme::ECIES_P256_AES_256_GCM);

    // Sensitive data to protect
    std::string sensitive_info = "Customer database backup encryption key: AES256...";
    std::vector<uint8_t> plaintext(sensitive_info.begin(), sensitive_info.end());

    // Encrypt the data
    auto ciphertext = encryption_key.encrypt(plaintext);
    encryption_key.increment_usage();

    std::cout << "Data encrypted:" << std::endl;
    std::cout << "  Original size: " << plaintext.size() << " bytes" << std::endl;
    std::cout << "  Encrypted size: " << ciphertext.size() << " bytes" << std::endl;
    std::cout << "  Encryption count: " << encryption_key.get_encryption_count() << std::endl;

    // Decrypt the data
    auto decrypted = encryption_key.decrypt(ciphertext);
    encryption_key.increment_usage();

    std::string recovered_info(decrypted.begin(), decrypted.end());
    std::cout << "  Decryption successful: " << (recovered_info == sensitive_info) << std::endl;
    std::cout << "  Decryption count: " << encryption_key.get_decryption_count() << std::endl;
    std::cout << "  Total usage: " << encryption_key.get_usage_count() << std::endl;
}

Key Derivation Example

// Demonstrate hierarchical key derivation
void demonstrate_key_derivation() {
    keychain::keychain_element master_key;
    master_key.set_element_id("master_key_001");
    master_key.set_description("Master key for derivation");

    if (master_key.supports_key_derivation()) {
        std::cout << "Master key supports derivation" << std::endl;

        // Derive keys for different purposes
        auto email_key = master_key.derive_element_for_purpose("email_encryption");
        email_key.set_description("Derived key for email encryption");

        auto file_key = master_key.derive_element_for_purpose("file_encryption");
        file_key.set_description("Derived key for file encryption");

        auto backup_key = master_key.derive_child_element("m/44'/0'/0'/0/0");
        backup_key.set_description("Derived key for backup encryption");

        std::cout << "Derived keys:" << std::endl;
        std::cout << "  Email key: " << email_key.get_element_id() << std::endl;
        std::cout << "  File key: " << file_key.get_element_id() << std::endl;
        std::cout << "  Backup key: " << backup_key.get_element_id() << std::endl;

        // List all derived paths
        auto derived_paths = master_key.get_derived_element_paths();
        std::cout << "  Total derived elements: " << derived_paths.size() << std::endl;
        for (const auto& path : derived_paths) {
            std::cout << "    Path: " << path << std::endl;
        }
    } else {
        std::cout << "Key derivation not supported for this element" << std::endl;
    }
}

Key Export and Backup

// Export key material for backup and sharing
void demonstrate_key_export() {
    keychain::keychain_element important_key;
    important_key.set_element_id("critical_signing_key");
    important_key.set_signature_scheme(keychain::signature_scheme::ECDSA_P256_SHA256);

    // Export public key in different formats
    std::string pem_public = important_key.export_public_key_pem();
    std::string jwk_public = important_key.export_public_key_jwk();

    std::cout << "Public key exports:" << std::endl;
    std::cout << "  PEM format length: " << pem_public.length() << " chars" << std::endl;
    std::cout << "  JWK format length: " << jwk_public.length() << " chars" << std::endl;

    // Export private key with encryption
    std::string backup_passphrase = "very_secure_backup_password_2024";

    if (important_key.has_private_key()) {
        std::string pem_private = important_key.export_private_key_pem(backup_passphrase);
        std::string jwk_private = important_key.export_private_key_jwk(backup_passphrase);

        std::cout << "Private key exports (encrypted):" << std::endl;
        std::cout << "  PEM format length: " << pem_private.length() << " chars" << std::endl;
        std::cout << "  JWK format length: " << jwk_private.length() << " chars" << std::endl;

        // Verify private key fingerprint
        std::string fingerprint = important_key.get_private_key_fingerprint();
        std::cout << "  Private key fingerprint: " << fingerprint << std::endl;

        // Simulate import on different system
        keychain::keychain_element restored_key;
        restored_key.import_public_key_pem(pem_public);
        restored_key.import_private_key_pem(pem_private, backup_passphrase);

        // Verify restoration
        std::string restored_fingerprint = restored_key.get_private_key_fingerprint();
        bool restore_success = (fingerprint == restored_fingerprint);
        std::cout << "  Backup restoration: " << (restore_success ? "SUCCESS" : "FAILED") << std::endl;
    }
}

Security Incident Handling

// Handle security incidents and key revocation
void demonstrate_security_incident_handling() {
    keychain::keychain_element potentially_compromised_key;
    potentially_compromised_key.set_element_id("incident_key_001");
    potentially_compromised_key.set_description("Key involved in security incident");

    // Simulate security monitoring
    bool security_breach_detected = true; // From security monitoring system

    if (security_breach_detected) {
        std::cout << "Security breach detected for key: "
                 << potentially_compromised_key.get_element_id() << std::endl;

        // Mark as compromised
        potentially_compromised_key.mark_compromised("Suspected exposure in server breach");

        std::cout << "Key marked as compromised" << std::endl;
        std::cout << "  Compromised: " << potentially_compromised_key.is_compromised() << std::endl;
        std::cout << "  Reason: " << potentially_compromised_key.get_compromise_reason() << std::endl;

        // Immediate revocation
        potentially_compromised_key.revoke("Emergency revocation due to compromise");

        std::cout << "Key revoked" << std::endl;
        std::cout << "  Revoked: " << potentially_compromised_key.is_revoked() << std::endl;
        std::cout << "  Revocation reason: " << potentially_compromised_key.get_revocation_reason() << std::endl;
        std::cout << "  Still active: " << potentially_compromised_key.is_active() << std::endl;

        // Generate replacement key
        keychain::keychain_element replacement_key;
        replacement_key.set_element_id("replacement_key_001");
        replacement_key.set_description("Emergency replacement for compromised key");
        replacement_key.set_signature_scheme(
            potentially_compromised_key.get_signature_scheme()
        );

        std::cout << "Replacement key generated: " << replacement_key.get_element_id() << std::endl;
    }
}

Element Validation and Health Monitoring

// Validate element integrity and perform health checks
void demonstrate_element_validation() {
    keychain::keychain_element test_element;
    test_element.set_element_id("health_check_key");
    test_element.set_signature_scheme(keychain::signature_scheme::ECDSA_P256_SHA256);

    // Perform comprehensive validation
    std::cout << "Performing element validation..." << std::endl;

    if (test_element.validate_element()) {
        std::cout << "Element validation: PASSED" << std::endl;
    } else {
        std::cout << "Element validation: FAILED" << std::endl;
        auto errors = test_element.get_validation_errors();
        for (const auto& error : errors) {
            std::cout << "  Validation error: " << error << std::endl;
        }
    }

    // Test key operations
    std::cout << "Testing key operations..." << std::endl;

    if (test_element.test_key_operations()) {
        std::cout << "Key operations test: PASSED" << std::endl;
    } else {
        std::cout << "Key operations test: FAILED" << std::endl;
    }

    // Perform self-test
    auto self_test_results = test_element.perform_self_test();
    std::cout << "Self-test results:" << std::endl;

    if (self_test_results.empty()) {
        std::cout << "  All self-tests PASSED" << std::endl;
    } else {
        for (const auto& result : self_test_results) {
            std::cout << "  Test result: " << result << std::endl;
        }
    }

    // Usage statistics summary
    std::cout << "Element statistics:" << std::endl;
    std::cout << "  Total usage: " << test_element.get_usage_count() << std::endl;
    std::cout << "  Signatures: " << test_element.get_signature_count() << std::endl;
    std::cout << "  Encryptions: " << test_element.get_encryption_count() << std::endl;
    std::cout << "  Decryptions: " << test_element.get_decryption_count() << std::endl;
}

JSON Structure

{
  "element_id": "sig_elem_001",
  "description": "Primary signing key for contracts",
  "purpose": "document_signing",
  "algorithm": {
    "signature_scheme": "ECDSA_P256_SHA256",
    "algorithm_identifier": "ecdsa-p256-sha256",
    "key_size_bits": 256
  },
  "keys": {
    "public_key": "04a1b2c3d4e5f6...",
    "has_private_key": true,
    "private_key_fingerprint": "sha256:abc123def456..."
  },
  "lifecycle": {
    "created_time": "2024-01-15T10:00:00Z",
    "last_used_time": "2024-01-20T14:30:00Z",
    "expiration_time": "2025-01-15T10:00:00Z",
    "active": true,
    "expired": false
  },
  "security": {
    "compromised": false,
    "revoked": false,
    "compromise_reason": null,
    "revocation_reason": null
  },
  "usage_statistics": {
    "total_usage": 157,
    "signature_count": 157,
    "encryption_count": 0,
    "decryption_count": 0
  },
  "derivation": {
    "supports_derivation": true,
    "derived_paths": [
      "email_encryption",
      "file_encryption"
    ]
  }
}

Performance Considerations

  • Cache public keys for frequently accessed elements

  • Monitor usage patterns for capacity planning

  • Implement lazy loading for large keychain collections

  • Use hardware security modules for high-value elements

  • Regular cleanup of expired or revoked elements

Security Best Practices

  • Regular validation and health checks

  • Immediate revocation upon compromise detection

  • Secure backup with strong encryption

  • Monitor unusual usage patterns

  • Implement key rotation schedules

  • Audit trail for all key operations

See Also

  • gateway - Element operations

  • persona - Identity with key elements

  • {key-lifecycle-management}[Key Lifecycle Management]

  • {cryptographic-key-security}[Cryptographic Key Security]