encrypted_data Class

Overview

The encrypted_data class encapsulates envelope (hybrid) encryption, combining symmetric encryption for data with public-key encryption for key management. It supports multiple recipients through key locks and dynamic access control.

Constructor

encrypted_data()

Creates an empty encrypted data instance.

encrypted_data()

encrypted_data(const std::string& serialized_data)

Creates encrypted data from serialized data.

encrypted_data(const std::string& serialized_data)

Parameters:

  • serialized_data - Previously serialized encrypted data

Core Methods

get_ciphertext()

Gets the encrypted payload data.

std::string get_ciphertext() const

get_iv()

Gets the initialization vector used for encryption.

std::string get_iv() const

get_key_locks()

Gets all key locks (encrypted symmetric keys) for this data.

std::vector<key_lock> get_key_locks() const

Key Lock Management

attach_key_lock()

Attaches a key lock to enable decryption by an additional recipient.

void attach_key_lock(const key_lock& lock)

Parameters:

  • lock - Key lock containing the encrypted symmetric key for a recipient

detach_key_lock()

Detaches a key lock by index.

key_lock detach_key_lock(size_t index)

Parameters:

  • index - Index of the key lock to detach

Returns: The detached key lock

find_key_lock()

Finds a key lock for a specific public key.

key_lock* find_key_lock(const std::string& public_key_hash)

Parameters:

  • public_key_hash - Hash of the public key to find

Returns: Pointer to the key lock, or nullptr if not found

Decryption

decrypt()

Decrypts the data using a persona’s private key.

std::string decrypt(const gateway& gw, const persona& p) const

Parameters:

  • gw - Gateway instance for cryptographic operations

  • p - Persona containing the private key for decryption

Returns: Decrypted cleartext data

Serialization

serialize()

Serializes the encrypted data for storage or transmission.

std::string serialize() const

Example Usage

#include <keychain/keychain_headers.hpp>

// Encrypt data for multiple recipients
gateway gw;
persona alice = gw.get_persona("alice");
contact bob = gw.get_contact("bob");
contact charlie = gw.get_contact("charlie");

std::string secret_message = "This is confidential information";

// Encrypt for Alice (she can decrypt with her own key)
encrypted_data encrypted = gw.encrypt(secret_message, alice);

// Add Bob as a recipient
key_lock bob_lock = gw.create_key_lock_for(encrypted, bob);
encrypted.attach_key_lock(bob_lock);

// Add Charlie as a recipient
key_lock charlie_lock = gw.create_key_lock_for(encrypted, charlie);
encrypted.attach_key_lock(charlie_lock);

// Now any of the three can decrypt
std::string decrypted_by_alice = encrypted.decrypt(gw, alice);

Dynamic Access Control Example

// Start with single recipient
encrypted_data confidential = gw.encrypt("Sensitive data", original_recipient);

// Later, add new recipient without re-encrypting the data
contact new_recipient = gw.get_contact("new_user");
key_lock new_lock = gw.create_key_lock_for(confidential, new_recipient);
confidential.attach_key_lock(new_lock);

// Remove access for specific recipient
auto locks = confidential.get_key_locks();
for (size_t i = 0; i < locks.size(); ++i) {
    if (locks[i].get_public_key_hash() == revoked_user_key_hash) {
        confidential.detach_key_lock(i);
        break;
    }
}

// Serialize for storage with updated access control
std::string stored_data = confidential.serialize();

Multi-Stage Encryption Example

// Create composable encryption with signing
std::string document = "Important legal document";

// First sign the document
verifiable_data signed_doc = gw.sign(document, legal_persona);

// Then encrypt the signed document for specific recipients
encrypted_data secure_doc = gw.encrypt(signed_doc.serialize(), legal_persona);

// Add other parties as recipients
for (const auto& party : authorized_parties) {
    key_lock party_lock = gw.create_key_lock_for(secure_doc, party);
    secure_doc.attach_key_lock(party_lock);
}

// Recipients can decrypt and then verify the signature
kc::serialized_data decrypted_data = gateway.decrypt(recipient_persona, secure_doc);
kc::verifiable_data original_signed(decrypted_data);
std::vector<kc::verification_result> verification = gateway.verify(recipient_persona, original_signed);

See Also

  • key_lock - Public-key encrypted symmetric keys

  • gateway - Main API for encryption operations

  • verifiable_data - For composable sign-then-encrypt operations

  • persona - Identity for encryption/decryption