Derives initial encryption keys from Destination Connection ID. More...

#include <crypto.h>

Collaboration diagram for kcenon::network::protocols::quic::initial_keys:

Static Public Member Functions
static auto	derive (const connection_id &dest_cid, uint32_t version=0x00000001) -> Result< key_pair >
	Derive client and server initial keys.

static auto	derive_keys (std::span< const uint8_t > initial_secret, bool is_client_keys) -> Result< quic_keys >
	Derive keys from an initial secret.

Detailed Description

Derives initial encryption keys from Destination Connection ID.

Initial keys are derived deterministically from the Destination Connection ID, allowing peers to decrypt Initial packets without a prior handshake.

Definition at line 110 of file crypto.h.

Member Function Documentation

◆ derive()

auto kcenon::network::protocols::quic::initial_keys::derive	(	const connection_id &	dest_cid,
		uint32_t	version = 0x00000001 ) -> Result<key_pair>

staticnodiscard

Derive client and server initial keys.

Parameters

dest_cid	Destination Connection ID (from client's perspective)
version	QUIC version (affects salt selection)

Returns: Key pair for initial encryption level or error

Definition at line 241 of file crypto.cpp.

{
    // Select salt based on version
    std::span<const uint8_t> salt;
    if (version == quic_version::version_2)
    {
        salt = initial_salt_v2;
    }
    else
    {
        salt = initial_salt_v1;
    }
 
    // Extract initial secret from destination connection ID
    auto initial_secret_result = hkdf::extract(salt, dest_cid.data());
    if (initial_secret_result.is_err())
    {
        return error<key_pair>(
            initial_secret_result.error().code,
            "Failed to derive initial secret",
            "quic::initial_keys",
            initial_secret_result.error().message);
    }
 
    auto& initial_secret = initial_secret_result.value();
 
    // Derive client initial secret
    auto client_secret_result = hkdf::expand_label(
        initial_secret,
        std::string(reinterpret_cast<const char*>(client_initial_label.data()),
                    client_initial_label.size()),
        {},
        secret_size);
    if (client_secret_result.is_err())
    {
        return error<key_pair>(
            client_secret_result.error().code,
            "Failed to derive client initial secret",
            "quic::initial_keys",
            client_secret_result.error().message);
    }
 
    // Derive server initial secret
    auto server_secret_result = hkdf::expand_label(
        initial_secret,
        std::string(reinterpret_cast<const char*>(server_initial_label.data()),
                    server_initial_label.size()),
        {},
        secret_size);
    if (server_secret_result.is_err())
    {
        return error<key_pair>(
            server_secret_result.error().code,
            "Failed to derive server initial secret",
            "quic::initial_keys",
            server_secret_result.error().message);
    }
 
    // Derive client keys
    auto client_keys_result = derive_keys(client_secret_result.value(), true);
    if (client_keys_result.is_err())
    {
        return error<key_pair>(
            client_keys_result.error().code,
            "Failed to derive client keys",
            "quic::initial_keys",
            client_keys_result.error().message);
    }
 
    // Derive server keys
    auto server_keys_result = derive_keys(server_secret_result.value(), false);
    if (server_keys_result.is_err())
    {
        return error<key_pair>(
            server_keys_result.error().code,
            "Failed to derive server keys",
            "quic::initial_keys",
            server_keys_result.error().message);
    }
 
    // Copy secrets into keys
    auto& client_keys = client_keys_result.value();
    auto& server_keys = server_keys_result.value();
 
    std::copy(client_secret_result.value().begin(),
              client_secret_result.value().end(),
              client_keys.secret.begin());
    std::copy(server_secret_result.value().begin(),
              server_secret_result.value().end(),
              server_keys.secret.begin());
 
    // For a client: write = client keys, read = server keys
    // For a server: write = server keys, read = client keys
    // This function returns from client's perspective
    key_pair result;
    result.write = std::move(client_keys);
    result.read = std::move(server_keys);
 
    return ok(std::move(result));
}

Referenced by kcenon::network::protocols::quic::quic_crypto::derive_initial_secrets().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ derive_keys()

auto kcenon::network::protocols::quic::initial_keys::derive_keys	(	std::span< const uint8_t >	initial_secret,
		bool	is_client_keys ) -> Result<quic_keys>

staticnodiscard

Derive keys from an initial secret.

Parameters

initial_secret	The initial secret
is_client_keys	true for client keys, false for server keys

Returns: QUIC keys or error

Definition at line 343 of file crypto.cpp.

{
    (void)is_client_keys; // Not used but kept for API clarity
 
    quic_keys keys;
 
    // Derive AEAD key
    auto key_result = hkdf::expand_label(
        initial_secret,
        std::string(reinterpret_cast<const char*>(quic_key_label.data()),
                    quic_key_label.size()),
        {},
        aes_128_key_size);
    if (key_result.is_err())
    {
        return error<quic_keys>(
            key_result.error().code,
            "Failed to derive AEAD key",
            "quic::initial_keys",
            key_result.error().message);
    }
    std::copy(key_result.value().begin(), key_result.value().end(),
              keys.key.begin());
 
    // Derive IV
    auto iv_result = hkdf::expand_label(
        initial_secret,
        std::string(reinterpret_cast<const char*>(quic_iv_label.data()),
                    quic_iv_label.size()),
        {},
        aead_iv_size);
    if (iv_result.is_err())
    {
        return error<quic_keys>(
            iv_result.error().code,
            "Failed to derive IV",
            "quic::initial_keys",
            iv_result.error().message);
    }
    std::copy(iv_result.value().begin(), iv_result.value().end(),
              keys.iv.begin());
 
    // Derive header protection key
    auto hp_result = hkdf::expand_label(
        initial_secret,
        std::string(reinterpret_cast<const char*>(quic_hp_label.data()),
                    quic_hp_label.size()),
        {},
        hp_key_size);
    if (hp_result.is_err())
    {
        return error<quic_keys>(
            hp_result.error().code,
            "Failed to derive HP key",
            "quic::initial_keys",
            hp_result.error().message);
    }
    std::copy(hp_result.value().begin(), hp_result.value().end(),
              keys.hp_key.begin());
 
    return ok(std::move(keys));
}

References kcenon::network::protocols::quic::aead_iv_size, kcenon::network::protocols::quic::aes_128_key_size, kcenon::network::protocols::quic::error, kcenon::network::protocols::quic::hkdf::expand_label(), kcenon::network::protocols::quic::quic_keys::hp_key, kcenon::network::protocols::quic::hp_key_size, kcenon::network::protocols::quic::quic_keys::iv, kcenon::network::protocols::quic::quic_keys::key, and kcenon::network::ok().

Referenced by kcenon::network::protocols::quic::quic_crypto::derive_zero_rtt_keys(), and kcenon::network::protocols::quic::quic_crypto::update_keys().