crypto.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2024, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include "kcenon/network/detail/protocols/quic/connection_id.h"
#include "keys.h"
#include "kcenon/network/detail/utils/result_types.h"
 
#include <cstdint>
#include <functional>
#include <map>
#include <memory>
#include <span>
#include <string>
#include <vector>
 
// Forward declarations for OpenSSL types
typedef struct ssl_ctx_st SSL_CTX;
typedef struct ssl_st SSL;
 
namespace kcenon::network::protocols::quic
{
 
// ============================================================================
// Initial Secret Derivation
// ============================================================================
 
constexpr std::array<uint8_t, 20> initial_salt_v1 = {
    0x38, 0x76, 0x2c, 0xf7, 0xf5, 0x59, 0x34, 0xb3, 0x4d, 0x17,
    0x9a, 0xe6, 0xa4, 0xc8, 0x0c, 0xad, 0xcc, 0xbb, 0x7f, 0x0a
};
 
constexpr std::array<uint8_t, 20> initial_salt_v2 = {
    0x0d, 0xed, 0xe3, 0xde, 0xf7, 0x00, 0xa6, 0xdb, 0x81, 0x93,
    0x81, 0xbe, 0x6e, 0x26, 0x9d, 0xcb, 0xf9, 0xbd, 0x2e, 0xd9
};
 
// ============================================================================
// HKDF Functions
// ============================================================================
 
class hkdf
{
public:
    [[nodiscard]] static auto extract(std::span<const uint8_t> salt,
                                       std::span<const uint8_t> ikm)
        -> Result<std::array<uint8_t, secret_size>>;
 
    [[nodiscard]] static auto expand(std::span<const uint8_t> prk,
                                      std::span<const uint8_t> info,
                                      size_t length)
        -> Result<std::vector<uint8_t>>;
 
    [[nodiscard]] static auto expand_label(std::span<const uint8_t> secret,
                                            const std::string& label,
                                            std::span<const uint8_t> context,
                                            size_t length)
        -> Result<std::vector<uint8_t>>;
};
 
// ============================================================================
// Initial Keys
// ============================================================================
 
class initial_keys
{
public:
    [[nodiscard]] static auto derive(const connection_id& dest_cid,
                                      uint32_t version = 0x00000001)
        -> Result<key_pair>;
 
    [[nodiscard]] static auto derive_keys(std::span<const uint8_t> initial_secret,
                                           bool is_client_keys)
        -> Result<quic_keys>;
};
 
// ============================================================================
// Packet Protection
// ============================================================================
 
class packet_protection
{
public:
    [[nodiscard]] static auto protect(const quic_keys& keys,
                                       std::span<const uint8_t> header,
                                       std::span<const uint8_t> payload,
                                       uint64_t packet_number)
        -> Result<std::vector<uint8_t>>;
 
    [[nodiscard]] static auto unprotect(
        const quic_keys& keys,
        std::span<const uint8_t> packet,
        size_t header_length,
        uint64_t packet_number)
        -> Result<std::pair<std::vector<uint8_t>, std::vector<uint8_t>>>;
 
    [[nodiscard]] static auto protect_header(const quic_keys& keys,
                                              std::span<uint8_t> header,
                                              size_t pn_offset,
                                              size_t pn_length,
                                              std::span<const uint8_t> sample)
        -> VoidResult;
 
    [[nodiscard]] static auto unprotect_header(const quic_keys& keys,
                                                std::span<uint8_t> header,
                                                size_t pn_offset,
                                                std::span<const uint8_t> sample)
        -> Result<std::pair<uint8_t, size_t>>;
 
    [[nodiscard]] static auto generate_hp_mask(std::span<const uint8_t> hp_key,
                                                std::span<const uint8_t> sample)
        -> Result<std::array<uint8_t, 5>>;
 
private:
    [[nodiscard]] static auto make_nonce(std::span<const uint8_t> iv,
                                          uint64_t packet_number)
        -> std::array<uint8_t, aead_iv_size>;
};
 
// ============================================================================
// QUIC Crypto Handler
// ============================================================================
 
class quic_crypto
{
public:
    quic_crypto();
 
    ~quic_crypto();
 
    // Non-copyable
    quic_crypto(const quic_crypto&) = delete;
    quic_crypto& operator=(const quic_crypto&) = delete;
 
    // Movable
    quic_crypto(quic_crypto&& other) noexcept;
    quic_crypto& operator=(quic_crypto&& other) noexcept;
 
    [[nodiscard]] auto init_client(const std::string& server_name) -> VoidResult;
 
    [[nodiscard]] auto init_server(const std::string& cert_file,
                                    const std::string& key_file) -> VoidResult;
 
    [[nodiscard]] auto derive_initial_secrets(const connection_id& dest_cid)
        -> VoidResult;
 
    [[nodiscard]] auto process_crypto_data(encryption_level level,
                                            std::span<const uint8_t> data)
        -> Result<std::vector<uint8_t>>;
 
    [[nodiscard]] auto start_handshake() -> Result<std::vector<uint8_t>>;
 
    [[nodiscard]] auto is_handshake_complete() const noexcept -> bool;
 
    [[nodiscard]] auto current_level() const noexcept -> encryption_level;
 
    [[nodiscard]] auto get_write_keys(encryption_level level) const
        -> Result<quic_keys>;
 
    [[nodiscard]] auto get_read_keys(encryption_level level) const
        -> Result<quic_keys>;
 
    void set_keys(encryption_level level,
                  const quic_keys& read_keys,
                  const quic_keys& write_keys);
 
    [[nodiscard]] auto update_keys() -> VoidResult;
 
    [[nodiscard]] auto get_alpn() const -> std::string;
 
    [[nodiscard]] auto set_alpn(const std::vector<std::string>& protocols)
        -> VoidResult;
 
    [[nodiscard]] auto is_server() const noexcept -> bool;
 
    [[nodiscard]] auto key_phase() const noexcept -> uint8_t;
 
    // =========================================================================
    // 0-RTT Session Resumption (RFC 9001 Section 4.6)
    // =========================================================================
 
    using session_ticket_callback_t = std::function<void(
        std::vector<uint8_t> ticket_data,
        uint32_t lifetime_hint,
        uint32_t ticket_age_add,
        uint32_t max_early_data)>;
 
    void set_session_ticket_callback(session_ticket_callback_t cb);
 
    [[nodiscard]] auto set_session_ticket(std::span<const uint8_t> ticket_data)
        -> VoidResult;
 
    [[nodiscard]] auto enable_early_data(uint32_t max_early_data) -> VoidResult;
 
    [[nodiscard]] auto is_early_data_accepted() const noexcept -> bool;
 
    [[nodiscard]] auto derive_zero_rtt_keys() -> VoidResult;
 
    [[nodiscard]] auto has_zero_rtt_keys() const noexcept -> bool;
 
private:
    struct impl;
    std::unique_ptr<impl> impl_;
};
 
} // namespace kcenon::network::protocols::quic