keychain Class

namespace keychain → class keychain

Overview

The keychain class represents a collection of cryptographic keys with a specific purpose (encryption or signature), providing organized key management and lifecycle operations.

Class Hierarchy

namespace keychain {
    class keychain : public serializable {
        // Collection of cryptographic keys
    };
}

Constructor

keychain();
keychain(keychain_type type);
keychain(keychain_type type, security_level level);
keychain(const keychain& other);

Properties

Keychain Identity

std::string get_keychain_id() const;
void set_keychain_id(const std::string& id);

std::string get_name() const;
void set_name(const std::string& name);

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

Unique identification and descriptive information.

Type and Configuration

keychain_type get_type() const;
void set_type(keychain_type type);

security_level get_security_level() const;
void set_security_level(security_level level);

bool is_encryption_keychain() const;
bool is_signature_keychain() const;

Keychain purpose and security configuration.

Key Elements

size_t get_element_count() const;
std::vector<keychain_element> get_elements() const;
keychain_element get_primary_element() const;

void add_element(const keychain_element& element);
bool remove_element(const std::string& element_id);
keychain_element get_element(const std::string& element_id) const;

Management of individual cryptographic key elements.

Algorithm Support

// For encryption keychains
std::vector<encryption_scheme> get_supported_encryption_schemes() const;
encryption_scheme get_primary_encryption_scheme() const;
void set_primary_encryption_scheme(encryption_scheme scheme);

// For signature keychains
std::vector<signature_scheme> get_supported_signature_schemes() const;
signature_scheme get_primary_signature_scheme() const;
void set_primary_signature_scheme(signature_scheme scheme);

Cryptographic algorithm configuration.

Lifecycle Management

std::chrono::system_clock::time_point get_created_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;
bool is_renewable() const;

void renew();
void revoke();

Key lifecycle and validity management.

Methods

Key Generation

keychain_element generate_new_element();
keychain_element generate_element_with_scheme(encryption_scheme scheme);
keychain_element generate_element_with_scheme(signature_scheme scheme);

void generate_key_pair();
void regenerate_keys();

Creation of new cryptographic key material.

Key Operations

// Encryption operations (encryption keychains only)
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 (signature keychains only)
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 keychain keys.

Key Export/Import

std::string export_public_keys() const;
std::string export_private_keys(const std::string& passphrase) const;

void import_public_keys(const std::string& keys_data);
void import_private_keys(const std::string& keys_data, const std::string& passphrase);

std::vector<uint8_t> export_keychain_backup() const;
void import_keychain_backup(const std::vector<uint8_t>& backup_data);

Key material export and import for backup and sharing.

Validation and Health

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

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

Keychain integrity checking and health monitoring.

Serialization

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

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

Usage Examples

Creating Different Types of Keychains

#include <keychain/keychain.h>

// Create encryption keychain
keychain::keychain encryption_keys(keychain::keychain_type::ENCRYPTION);
encryption_keys.set_name("alice_encryption");
encryption_keys.set_description("Alice's encryption keychain for confidential data");
encryption_keys.set_security_level(keychain::security_level::HIGH);

// Set preferred encryption scheme
encryption_keys.set_primary_encryption_scheme(
    keychain::encryption_scheme::ECIES_P256_AES_256_GCM
);

// Generate initial key elements
auto enc_element = encryption_keys.generate_new_element();
std::cout << "Generated encryption element: " << enc_element.get_element_id() << std::endl;

// Create signature keychain
keychain::keychain signature_keys(keychain::keychain_type::SIGNATURE);
signature_keys.set_name("alice_signatures");
signature_keys.set_description("Alice's signature keychain for authentication");
signature_keys.set_security_level(keychain::security_level::HIGH);

// Set preferred signature scheme
signature_keys.set_primary_signature_scheme(
    keychain::signature_scheme::ECDSA_P256_SHA256
);

// Generate signature key elements
auto sig_element = signature_keys.generate_new_element();
std::cout << "Generated signature element: " << sig_element.get_element_id() << std::endl;

Encryption Keychain Operations

// Use encryption keychain for data protection
void demonstrate_encryption_keychain() {
    keychain::keychain enc_keychain(keychain::keychain_type::ENCRYPTION);
    enc_keychain.set_security_level(keychain::security_level::MEDIUM);
    enc_keychain.generate_key_pair();

    // Encrypt sensitive data
    std::string sensitive_data = "Confidential business information";
    std::vector<uint8_t> plaintext(sensitive_data.begin(), sensitive_data.end());

    auto ciphertext = enc_keychain.encrypt(plaintext);
    std::cout << "Encrypted " << plaintext.size() << " bytes to "
             << ciphertext.size() << " bytes" << std::endl;

    // Decrypt the data
    auto decrypted = enc_keychain.decrypt(ciphertext);
    std::string recovered_data(decrypted.begin(), decrypted.end());

    assert(recovered_data == sensitive_data);
    std::cout << "Successfully decrypted: " << recovered_data << std::endl;

    // Export public key for sharing
    std::string public_key = enc_keychain.export_public_keys();
    std::cout << "Public key (first 50 chars): "
             << public_key.substr(0, 50) << "..." << std::endl;
}

Signature Keychain Operations

// Use signature keychain for authentication
void demonstrate_signature_keychain() {
    keychain::keychain sig_keychain(keychain::keychain_type::SIGNATURE);
    sig_keychain.set_security_level(keychain::security_level::HIGH);
    sig_keychain.generate_key_pair();

    // Sign important document
    std::string document = "Important contract terms and conditions";
    std::vector<uint8_t> doc_data(document.begin(), document.end());

    auto signature = sig_keychain.sign(doc_data);
    std::cout << "Generated signature of " << signature.size() << " bytes" << std::endl;

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

    // Test with modified data (should fail)
    std::string modified_doc = document + " MODIFIED";
    std::vector<uint8_t> modified_data(modified_doc.begin(), modified_doc.end());

    bool modified_valid = sig_keychain.verify(modified_data, signature);
    std::cout << "Modified document verification: "
             << (modified_valid ? "VALID" : "INVALID") << std::endl;
    assert(!modified_valid); // Should be invalid
}

Multi-Element Keychain Management

// Manage multiple key elements for different purposes
void demonstrate_multi_element_keychain() {
    keychain::keychain multi_keychain(keychain::keychain_type::SIGNATURE);
    multi_keychain.set_name("multi_purpose_signatures");

    // Generate elements for different security levels
    auto high_sec_element = multi_keychain.generate_element_with_scheme(
        keychain::signature_scheme::ECDSA_P521_SHA512
    );
    high_sec_element.set_description("High security operations");
    multi_keychain.add_element(high_sec_element);

    auto standard_element = multi_keychain.generate_element_with_scheme(
        keychain::signature_scheme::ECDSA_P256_SHA256
    );
    standard_element.set_description("Standard operations");
    multi_keychain.add_element(standard_element);

    auto fast_element = multi_keychain.generate_element_with_scheme(
        keychain::signature_scheme::EDDSA_ED25519
    );
    fast_element.set_description("High-performance operations");
    multi_keychain.add_element(fast_element);

    // List all elements
    auto elements = multi_keychain.get_elements();
    std::cout << "Keychain contains " << elements.size() << " elements:" << std::endl;

    for (const auto& element : elements) {
        std::cout << "  - " << element.get_element_id()
                 << ": " << element.get_description() << std::endl;
    }

    // Set primary element for default operations
    multi_keychain.set_primary_signature_scheme(
        keychain::signature_scheme::ECDSA_P256_SHA256
    );

    auto primary = multi_keychain.get_primary_element();
    std::cout << "Primary element: " << primary.get_element_id() << std::endl;
}

Keychain Lifecycle Management

// Manage keychain lifecycle and renewal
void demonstrate_keychain_lifecycle() {
    keychain::keychain lifecycle_keychain(keychain::keychain_type::ENCRYPTION);
    lifecycle_keychain.set_name("temporary_encryption");

    // Set expiration for 30 days
    auto now = std::chrono::system_clock::now();
    auto expiration = now + std::chrono::hours(24 * 30);
    lifecycle_keychain.set_expiration_time(expiration);

    // Generate keys
    lifecycle_keychain.generate_key_pair();

    // Check status
    std::cout << "Keychain active: " << lifecycle_keychain.is_active() << std::endl;
    std::cout << "Keychain expired: " << lifecycle_keychain.is_expired() << std::endl;
    std::cout << "Keychain renewable: " << lifecycle_keychain.is_renewable() << std::endl;

    // Health check
    if (lifecycle_keychain.validate_keychain()) {
        std::cout << "Keychain validation: PASSED" << std::endl;
    } else {
        auto errors = lifecycle_keychain.get_validation_errors();
        std::cout << "Keychain validation: FAILED" << std::endl;
        for (const auto& error : errors) {
            std::cout << "  Error: " << error << std::endl;
        }
    }

    // Test key operations
    if (lifecycle_keychain.test_key_operations()) {
        std::cout << "Key operations test: PASSED" << std::endl;
    } else {
        auto status = lifecycle_keychain.get_health_status();
        std::cout << "Key operations test: FAILED" << std::endl;
        for (const auto& issue : status) {
            std::cout << "  Issue: " << issue << std::endl;
        }
    }

    // Renewal before expiration
    if (lifecycle_keychain.is_renewable()) {
        std::cout << "Renewing keychain..." << std::endl;
        lifecycle_keychain.renew();

        // Check new expiration
        auto new_expiration = lifecycle_keychain.get_expiration_time();
        std::cout << "New expiration set" << std::endl;
    }
}

Keychain Backup and Recovery

// Backup and restore keychain data
void demonstrate_keychain_backup() {
    // Create original keychain
    keychain::keychain original_keychain(keychain::keychain_type::SIGNATURE);
    original_keychain.set_name("important_signatures");
    original_keychain.set_description("Critical business signatures");
    original_keychain.generate_key_pair();

    // Create some test data to sign
    std::string test_data = "Test document for backup verification";
    std::vector<uint8_t> data_bytes(test_data.begin(), test_data.end());
    auto original_signature = original_keychain.sign(data_bytes);

    // Create encrypted backup
    std::string backup_passphrase = "secure_backup_password_2024";
    std::string private_key_backup = original_keychain.export_private_keys(backup_passphrase);
    std::string public_key_backup = original_keychain.export_public_keys();

    // Full keychain backup
    auto full_backup = original_keychain.export_keychain_backup();

    std::cout << "Backup created:" << std::endl;
    std::cout << "  Private key backup size: " << private_key_backup.size() << " bytes" << std::endl;
    std::cout << "  Public key backup size: " << public_key_backup.size() << " bytes" << std::endl;
    std::cout << "  Full backup size: " << full_backup.size() << " bytes" << std::endl;

    // Simulate restoration on new system
    keychain::keychain restored_keychain(keychain::keychain_type::SIGNATURE);

    // Restore from full backup
    restored_keychain.import_keychain_backup(full_backup);

    // Verify restoration by testing signature verification
    bool signature_valid = restored_keychain.verify(data_bytes, original_signature);
    std::cout << "Backup restoration verification: "
             << (signature_valid ? "SUCCESS" : "FAILED") << std::endl;

    // Verify keychain properties
    assert(restored_keychain.get_name() == original_keychain.get_name());
    assert(restored_keychain.get_type() == original_keychain.get_type());
    assert(restored_keychain.get_element_count() == original_keychain.get_element_count());

    std::cout << "Keychain backup and restoration completed successfully" << std::endl;
}

Algorithm Migration

// Migrate keychain to new cryptographic algorithms
void demonstrate_algorithm_migration() {
    // Create keychain with legacy algorithm
    keychain::keychain legacy_keychain(keychain::keychain_type::SIGNATURE);
    legacy_keychain.set_primary_signature_scheme(
        keychain::signature_scheme::RSASS_2048_PKCS1_SHA256  // Legacy
    );
    legacy_keychain.generate_key_pair();

    // Sign something with legacy key
    std::string document = "Important legacy document";
    std::vector<uint8_t> doc_data(document.begin(), document.end());
    auto legacy_signature = legacy_keychain.sign(doc_data);

    std::cout << "Created legacy signature with "
             << to_string(legacy_keychain.get_primary_signature_scheme()) << std::endl;

    // Add modern algorithm element
    auto modern_element = legacy_keychain.generate_element_with_scheme(
        keychain::signature_scheme::EDDSA_ED25519  // Modern
    );
    modern_element.set_description("Modern high-performance signatures");
    legacy_keychain.add_element(modern_element);

    // Update primary scheme to modern algorithm
    legacy_keychain.set_primary_signature_scheme(
        keychain::signature_scheme::EDDSA_ED25519
    );

    // New signatures will use modern algorithm
    auto modern_signature = legacy_keychain.sign(doc_data);

    std::cout << "Created modern signature with "
             << to_string(legacy_keychain.get_primary_signature_scheme()) << std::endl;

    // Both signatures should verify
    bool legacy_valid = legacy_keychain.verify(doc_data, legacy_signature);
    bool modern_valid = legacy_keychain.verify(doc_data, modern_signature);

    std::cout << "Legacy signature valid: " << legacy_valid << std::endl;
    std::cout << "Modern signature valid: " << modern_valid << std::endl;

    assert(legacy_valid && modern_valid);
    std::cout << "Algorithm migration completed successfully" << std::endl;
}

JSON Structure

{
  "keychain_id": "alice_encryption_001",
  "name": "alice_encryption",
  "description": "Alice's encryption keychain for confidential data",
  "type": "ENCRYPTION",
  "security_level": "HIGH",
  "created_time": "2024-01-15T10:00:00Z",
  "expiration_time": "2025-01-15T10:00:00Z",
  "status": {
    "active": true,
    "expired": false,
    "renewable": true
  },
  "algorithms": {
    "primary_encryption_scheme": "ECIES_P256_AES_256_GCM",
    "supported_schemes": [
      "ECIES_P256_AES_256_GCM",
      "ECIES_P384_AES_256_GCM",
      "RSA_3072_OAEP_SHA256"
    ]
  },
  "elements": [
    {
      "element_id": "elem_001",
      "description": "Primary encryption element",
      "algorithm": "ECIES_P256_AES_256_GCM",
      "created_time": "2024-01-15T10:00:00Z",
      "status": "active"
    }
  ],
  "metadata": {
    "element_count": 1,
    "last_used": "2024-01-20T14:30:00Z",
    "usage_count": 157
  }
}

Best Practices

Security Considerations

  • Use separate keychains for encryption and signature operations

  • Set appropriate expiration times for key rotation

  • Regular backup of keychain data with strong passphrases

  • Monitor keychain health and validate regularly

  • Migrate to modern algorithms when legacy ones become weak

Performance Optimization

  • Choose algorithms appropriate for your use case (speed vs security)

  • Minimize keychain element count for better performance

  • Cache public keys for frequently used operations

  • Use hardware security modules for high-value keychains

Operational Guidelines

  • Implement automated key rotation schedules

  • Monitor keychain expiration and renewal needs

  • Test backup and recovery procedures regularly

  • Document keychain purposes and algorithms used

See Also

  • gateway - Keychain operations

  • persona - Identity with keychains

  • {key-management-best-practices}[Key Management Best Practices]

  • {cryptographic-key-lifecycle}[Cryptographic Key Lifecycle]