gateway Class

#include <keychain/gateway/gateway.hpp>

Namespace: keychain (alias: kc)

Inheritance: public kc::monitor

Overview

The gateway class is the primary interface for all cryptographic identity management operations in {keychain-core} 3.0. It provides comprehensive functionality for creating and managing personas, contacts, and executing cryptographic operations including encryption, decryption, digital signing, and verification.

The gateway implements a sophisticated cryptographic identity system with support for:

  • Decentralized Identifiers (DIDs) - W3C-compliant identity resolution

  • Composable Cryptography - Flexible combination of cryptographic operations

  • Multi-recipient Encryption - Dynamic access control without re-encryption

  • Verifiable Credentials - W3C verifiable credentials support

  • Consensus Transactions - Application-level consensus protocols

  • Multiple Security Levels - From lightweight IoT to ultra-secure enterprise

The gateway works in conjunction with the monitor to maintain real-time PKI state synchronization.

Since: v2.0 (completely redesigned in v3.0)

Static Initialization

init()

static kc::code init(kc::settings& out_settings, std::string config_path)

Initializes the Keychain library and creates settings. Must be called before any gateway operations.

Parameters:

  • out_settings - Output settings object for gateway construction

  • config_path - Path to configuration file (e.g., keychain.cfg)

Returns: kc::code indicating success or failure

close()

static void close()

Cleans up static library resources. Should be called at application shutdown.

Constructors

Constructors: All constructors are private. Gateway instances are created through the gateway_manager class.

Copy and Move Operations: Explicitly deleted for thread safety

Static Utility Methods

hash()

static std::string hash(const std::string& clear_text)

Computes SHA-256 hash of input data.

generate_signature()

static std::string generate_signature(
    const std::string& cleartext,
    const std::string& private_key_hex,
    kc::signature_scheme algorithm
)

Generates a signature using an external private key. Use only when the signature must be produced from an external private key. Use gateway::sign() for normal operations.

verify()

static bool verify(
    const std::string& cleartext,
    const std::string& public_key_hex,
    const std::string& signature_hex,
    kc::signature_scheme algorithm
)

Verifies a signature against a public key. This is the companion function of generate_signature() for external key scenarios.

Persona Management

create_persona() (Basic)

kc::persona create_persona(
    std::string name,
    std::string sub_name,
    kc::security_level sec_level,
    bool auto_renew = true
)

Creates a persona with automatic algorithm selection based on security level.

create_persona() (Algorithm Classes)

kc::persona create_persona(
    std::string name,
    std::string sub_name,
    kc::security_level sec_level,
    kc::encryption_algorithm_class encrypt_class,
    kc::signature_algorithm_class sign_class,
    kc::cipher_class cipher_class,
    bool auto_renew = true
)

Creates a persona with specific algorithm classes.

create_persona() (Explicit Parameters)

kc::persona create_persona(
    std::string name,
    std::string sub_name,
    kc::security_level sec_level,
    kc::encryption_scheme encrypt_algorithm,
    size_t encrypt_key_size_bits,
    kc::signature_scheme sign_algorithm,
    size_t sign_key_size_bits,
    kc::cipher cipher,
    bool auto_renew = true
)

Creates a persona with fully explicit cryptographic parameters.

find_persona()

kc::persona find_persona(std::string name, std::string subname)
kc::persona find_persona(const kc::persona_did& did)

Finds an existing persona by name/subname or by DID.

retrieve_personas()

std::vector<kc::persona> retrieve_personas()

Retrieves all personas in the gateway.

refresh_persona()

kc::code refresh_persona(kc::persona& in_out_persona)

Refreshes persona state from database.

Contact Management

add_contact()

kc::contact add_contact(
    kc::persona& in_out_persona,
    const std::string& name,
    const std::string& sub_name,
    const kc::persona_did& did
)

Adds a contact to a persona using a DID.

Cryptographic Operations

encrypt()

kc::encrypted_data encrypt(
    const kc::persona& persona,
    const kc::serialized_data& clear_text,
    const std::vector<kc::contact>& recipients
)

Encrypts data for multiple recipients using envelope encryption.

decrypt()

kc::serialized_data decrypt(
    const kc::persona& persona,
    const kc::encrypted_data& ciphertext
)

Decrypts data using persona’s private key.

sign()

kc::verifiable_data sign(
    const kc::persona& persona,
    const kc::serialized_data& cleartext,
    bool approval = true,
    const kc::tag_set& tags = kc::tag_set(),
    const kc::tag_set& variables = kc::tag_set()
)

Signs data creating verifiable data with attestation.

verify()

std::vector<kc::verification_result> verify(
    const kc::persona& persona,
    const kc::verifiable& signed_msg
)

Verifies signatures on verifiable data, credentials, or transactions.

Credential and Transaction Operations

create_credential()

kc::credential create_credential(
    const kc::persona& persona,
    const std::string& id,
    const std::string& type,
    const std::string& subject,
    kc::timestamp_t start_timestamp,
    kc::timestamp_t end_timestamp,
    const kc::tag_set& claims,
    const kc::tag_set& tags = kc::tag_set(),
    const kc::tag_set& variables = kc::tag_set()
)

Creates a W3C verifiable credential.

create_transaction()

kc::transaction create_transaction(
    const kc::persona& persona,
    kc::consensus_algorithm consensus,
    const kc::quorum& quorum,
    const kc::tag_set& tags,
    const kc::tag_set& variables
)

Creates a consensus transaction for ledger operations.

add_signature()

kc::attestation add_signature(
    kc::verifiable& in_out_signed_verifiable,
    const kc::persona& persona,
    bool is_approval = true,
    const kc::tag_set& tags = kc::tag_set(),
    const kc::tag_set& vars = kc::tag_set()
)

Adds a signature to a verifiable object (verifiable data, credential, or transaction).

Ledger Consensus Operations

ledger_start()

kc::transaction ledger_start(
    const kc::persona& persona,
    kc::consensus_algorithm consensus,
    const std::vector<kc::contact> contacts,
    kc::tag_set tags = kc::tag_set(),
    kc::tag_set variables = kc::tag_set()
)

Initiates a ledger consensus process.

ledger_receive()

kc::ledger_result ledger_receive(
    const kc::persona& persona,
    kc::transaction& transaction
)

Processes a received ledger transaction.

ledger_check_state_transition()

void ledger_check_state_transition(
    const kc::persona& persona,
    kc::transaction& transaction
)

Progresses the consensus stage based on signatures received.

ledger_sign()

void ledger_sign(
    const kc::persona& persona,
    kc::transaction& transaction,
    bool approval,
    kc::tag_set tags = kc::tag_set(),
    kc::tag_set variables = kc::tag_set()
)

Signs a ledger transaction during consensus.

Storage Operations

persist()

bool persist(const kc::verifiable_data& data)
bool persist(const kc::credential& data)
bool persist(const kc::transaction& data)
bool persist(const kc::encrypted_data& data)

Persists verifiable objects to local storage.

purge()

void purge(const kc::verifiable_data& data)
void purge(const kc::credential& data)
void purge(const kc::transaction& data)
void purge(const kc::encrypted_data& data)

Removes verifiable objects from local storage.

retrieve_verifiable_data() / retrieve_credential() / retrieve_transaction_history() / retrieve_encrypted_data()

kc::verifiable_data retrieve_verifiable_data(
    kc::timestamp_t timestamp,
    const std::string& base_hash
)

kc::credential retrieve_credential(
    kc::timestamp_t timestamp,
    const std::string& base_hash
)

std::vector<kc::transaction> retrieve_transaction_history(
    kc::timestamp_t timestamp,
    const std::string& base_hash
)

kc::encrypted_data retrieve_encrypted_data(
    const std::string& ciphertext_hash
)

Retrieves stored objects by timestamp and hash.

Additional Operations

add_decrypt_access()

kc::key_lock add_decrypt_access(
    kc::encrypted_data& in_out_ciphertext,
    const kc::persona& persona,
    const kc::contact& new_recipient,
    bool attachable = true
)

Adds decrypt access to existing encrypted data for a new recipient.

delete_facade() / rename_facade()

kc::code delete_facade(const kc::facade& facade)
kc::code rename_facade(
    const kc::facade& facade,
    std::string new_name,
    std::string new_subname
)

Deletes or renames a facade (persona or contact).

set_auto_renew() / renew_certificate()

kc::code set_auto_renew(kc::persona& in_out_persona, bool auto_renew)
kc::code renew_certificate(kc::persona& in_out_persona)

Configures or manually triggers certificate renewal.

force_update_cache()

kc::code force_update_cache()

Manually triggers PKI cache update.

await_new_block_height() / await_persona_maturity()

void await_new_block_height()
void await_persona_maturity(kc::persona& persona)

Blocks execution until PKI events occur.

Monitor Operations

The gateway inherits from kc::monitor and provides PKI monitoring capabilities. Refer to the monitor class documentation for detailed monitor operations.

Example Usage

Basic Gateway Setup

#include <keychain/keychain_headers.hpp>

int main() {
    try {
        // Initialize the library
        kc::settings settings;
        kc::code result = kc::gateway::init(settings, "~/.keychain/keychain.cfg");
        if (result != kc::error::success) {
            // Handle initialization error
            return 1;
        }

        // Gateway instances are created through gateway_manager
        // (See gateway_manager documentation for details)

        // Your application logic here...

        // Cleanup
        kc::gateway::close();
        return 0;
    } catch (const kc::exception& e) {
        std::cerr << "Keychain error: " << e.what() << std::endl;
        return 1;
    }
}

Creating Personas

// Create a basic persona with medium security
kc::persona alice = gateway.create_persona(
    "alice", "personal",
    kc::security_level::medium
);

// Create a high-security persona with specific algorithms
kc::persona enterprise = gateway.create_persona(
    "enterprise", "server",
    kc::security_level::high,
    kc::encryption_algorithm_class::ecies,
    kc::signature_algorithm_class::ecdsa,
    kc::cipher_class::aes
);

// Create persona with fully explicit parameters
kc::persona custom = gateway.create_persona(
    "custom", "device",
    kc::security_level::low,
    kc::encryption_scheme::ecies_ecp_secp256r1,
    256, // key size
    kc::signature_scheme::ecdsa_ecp_secp256r1,
    256, // key size
    kc::cipher::aes_gcm_256
);

Encryption and Decryption

// Add contacts
kc::contact bob = gateway.add_contact(
    alice, "bob", "work", bob_persona_did
);
kc::contact charlie = gateway.add_contact(
    alice, "charlie", "team", charlie_persona_did
);

// Encrypt for multiple recipients
std::string message = "Confidential project information";
kc::serialized_data cleartext(message);
std::vector<kc::contact> recipients = {bob, charlie};

kc::encrypted_data encrypted = gateway.encrypt(
    alice, cleartext, recipients
);

// Recipients can decrypt
kc::serialized_data decrypted = gateway.decrypt(bob_persona, encrypted);
std::string original_message = decrypted.utf8_string();

Digital Signatures

// Sign a document
std::string document = "Important legal contract";
kc::serialized_data doc_data(document);

kc::verifiable_data signed_doc = gateway.sign(
    alice, doc_data, true // approval signature
);

// Add metadata
kc::tag_set tags;
tags.set_tag("document", "type", kc::serialized_data("contract"));
tags.set_tag("legal", "binding", kc::serialized_data(true));

kc::verifiable_data signed_with_tags = gateway.sign(
    alice, doc_data, true, tags
);

// Verify signatures
std::vector<kc::verification_result> results = gateway.verify(
    bob_persona, signed_doc
);

for (const auto& result : results) {
    if (result.is_verified()) {
        std::cout << "Valid signature from known contact" << std::endl;
    }
}

W3C Verifiable Credentials

// Create university degree credential
kc::tag_set claims;
claims.set_tag("degree", "type", kc::serialized_data("Bachelor of Science"));
claims.set_tag("degree", "major", kc::serialized_data("Computer Science"));
claims.set_tag("academic", "gpa", kc::serialized_data("3.85"));
claims.set_tag("graduation", "date", kc::serialized_data("2024-05-15"));

kc::credential degree = gateway.create_credential(
    university_registrar_persona,
    "https://university.edu/credentials/degree-2024-001",
    "UniversityDegreeCredential",
    alice.did().serialize(),
    time(nullptr), // start timestamp
    time(nullptr) + (10 * 365 * 24 * 60 * 60), // valid for 10 years
    claims
);

// Verify credential
std::vector<kc::verification_result> verification = gateway.verify(
    alice, degree
);

Consensus Transactions

// Setup consensus participants
std::vector<kc::contact> participants = {alice_contact, bob_contact, charlie_contact};

// Start consensus transaction
kc::tag_set initial_state;
initial_state.set_tag("proposal", "amount", kc::serialized_data(1000));
initial_state.set_tag("proposal", "recipient", kc::serialized_data("dave"));

kc::transaction consensus_tx = gateway.ledger_start(
    alice,
    kc::consensus_algorithm::three_phase_commit,
    participants,
    kc::tag_set(), // tags
    initial_state  // variables
);

// Process received transaction (on other nodes)
kc::ledger_result result = gateway.ledger_receive(bob_persona, consensus_tx);
if (result == kc::ledger_result::response_needed) {
    // Sign approval
    gateway.ledger_sign(bob_persona, consensus_tx, true);
}

Composable Operations

// Sign then encrypt
kc::verifiable_data signed = gateway.sign(alice, cleartext);
kc::serialized_data signed_serialized(signed.serialize());
kc::encrypted_data signed_then_encrypted = gateway.encrypt(
    alice, signed_serialized, recipients
);

// Recipients decrypt then verify
kc::serialized_data decrypted_data = gateway.decrypt(bob_persona, signed_then_encrypted);
// Correct: deserialize verifiable_data from serialized_data
kc::verifiable_data original_signed(decrypted_data);
std::vector<kc::verification_result> verification = gateway.verify(
    bob_persona, original_signed
);

Error Handling

try {
    kc::persona persona = gateway.create_persona(
        "test", "user", kc::security_level::medium
    );

    // Operations...

} catch (const kc::exception& e) {
    std::cerr << "Keychain error: " << e.what() << std::endl;
    std::cerr << "Error code: " << e.error_code() << std::endl;
} catch (const std::exception& e) {
    std::cerr << "General error: " << e.what() << std::endl;
}

Threading and Lifecycle

// The gateway is not thread-safe; use one per thread or synchronize access
class ThreadSafeGateway {
private:
    std::mutex gateway_mutex;
    std::unique_ptr<kc::gateway> gateway_ptr;

public:
    void encrypt_safely(/* parameters */) {
        std::lock_guard<std::mutex> lock(gateway_mutex);
        // Use gateway_ptr safely
    }
};

// Monitor operations are inherited from kc::monitor
// Refer to monitor class documentation for lifecycle management

See Also