tiny.quic.crypto

1pub const Capacity = struct {2    suite: Suite,3    key_bytes: u6,4    storage_bytes: usize,56    pub const DeriveError = error{CapacityOverflow};78    pub fn derive(limits: Limits) DeriveError!Capacity {9        const key_lanes = std.math.mul(usize, key_bytes_max, 2) catch10            return error.CapacityOverflow;11        const derived_bytes = std.math.add(usize, key_lanes, iv_bytes) catch12            return error.CapacityOverflow;13        if (derived_bytes != storage_bytes) return error.CapacityOverflow;14        return .{15            .suite = limits.suite,16            .key_bytes = limits.suite.keyLength(),17            .storage_bytes = derived_bytes,18        };19    }20};

1pub const Keys = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: KeyCapacity,4    storage: []align(storage_alignment) u8,5    sealed_packets: u64,6    failed_opens: u64,78    pub const storage_alignment: usize = @alignOf(Material);9    pub const storage_bytes_max: usize = storage_bytes;10    pub const Storage = []align(storage_alignment) u8;11    pub const Limits: type = KeyLimits;12    pub const Capacity: type = KeyCapacity;13    pub const InitError = KeyCapacity.DeriveError || error{StorageTooShort};14    pub const work_limits: alloc_phase.capacity.WorkLimits = .{15        .transition_steps_max = 1,16        .cleanup_steps_per_call_max = 0,17        .cleanup_calls_at_capacity_max = 0,18    };1920    pub const claim: alloc_phase.capacity.Declaration = .{21        .source = .{22            .id = "quic.crypto_keys",23            .kind = .startup_static,24            .limit_source = .caller,25            .storage = .{26                .covered = &.{27                    .{28                        .id = "packet_key_bytes",29                        .lifetime = .steady,30                        .detail = "fixed caller-provisioned packet protection key bytes",31                    },32                    .{33                        .id = "packet_iv_bytes",34                        .lifetime = .steady,35                        .detail = "fixed caller-provisioned packet protection IV bytes",36                    },37                    .{38                        .id = "header_key_bytes",39                        .lifetime = .steady,40                        .detail = "fixed caller-provisioned header protection key bytes",41                    },42                },43                .excluded = &.{44                    "caller-owned packet and traffic secret bytes",45                    "fixed suite tag and usage counters",46                },47            },48            .capacity = .{49                .inputs = &.{},50                .type_selectors = &.{51                    alloc_phase.capacity.bindType(Material, "key_material"),52                },53                .nodes = &.{54                    .{ .constant = 1 },55                    .{ .scale = .{56                        .node = 0,57                        .coefficient = .{ .size_of_concrete_type = 0 },58                    } },59                },60                .assertions = &.{.{61                    .scope = .closure_total,62                    .measure = .retained,63                    .relation = .exact,64                    .expression = 1,65                }},66            },67            .overload = .{68                .kind = .reject_before_seal,69                .detail = "short caller storage rejects before key derivation",70            },71            .risks = .{72                .transitive = .{73                    .status = .witnessed,74                    .detail = "standard cryptographic primitives use fixed value storage",75                },76                .foreign = .{77                    .status = .excluded,78                    .detail = "key derivation and packet protection cross no foreign boundary",79                },80            },81            .work = .{ .equation = "initialization to steady transition steps <= 1" },82            .obligations = &.{83                .{ .key = "quic_crypto_keys_capacity", .role = .capacity_model },84                .{ .key = "quic_crypto_keys_overload", .role = .overload },85                .{ .key = "quic_crypto_keys_transitive", .role = .transitive_risk },86                .{ .key = "quic_crypto_keys_work", .role = .work_bound },87            },88        },89        .bindings = .{ .owner = @This() },90    };9192    pub fn init(storage: Storage, limits: KeyLimits) InitError!Keys {93        const capacity = try KeyCapacity.derive(limits);94        if (storage.len < capacity.storage_bytes) return error.StorageTooShort;95        const owned = storage[0..capacity.storage_bytes];96        @memset(owned, 0);97        return .{98            .phase = .initialization,99            .capacity = capacity,100            .storage = owned,101            .sealed_packets = 0,102            .failed_opens = 0,103        };104    }105106    pub fn activate(self: *Keys) void {107        std.debug.assert(self.phase == .initialization);108        std.debug.assert(self.storage.len == self.capacity.storage_bytes);109        self.phase = .steady;110    }111112    pub fn derive(storage: Storage, suite: Suite, secret: Secret) InitError!Keys {113        var result = try init(storage, .{ .suite = suite });114        result.writePacketMaterial(secret);115        result.writeHeaderMaterial(secret);116        result.activate();117        return result;118    }119120    pub fn deinit(self: *Keys) Storage {121        std.debug.assert(self.phase == .steady);122        std.crypto.secureZero(u8, self.storage);123        self.phase = .teardown;124        const owned = self.storage;125        self.* = undefined;126        return owned;127    }128129    fn material(self: *Keys) *Material {130        std.debug.assert(self.phase != .teardown);131        std.debug.assert(self.storage.len == storage_bytes);132        return @ptrCast(self.storage.ptr);133    }134135    fn materialConst(self: *const Keys) *const Material {136        std.debug.assert(self.phase == .steady);137        std.debug.assert(self.storage.len == storage_bytes);138        return @ptrCast(self.storage.ptr);139    }140141    fn writePacketMaterial(self: *Keys, secret: Secret) void {142        const value = self.material();143        value.key = @splat(0);144        value.iv = tls.hkdfExpandLabel(Hkdf, secret, "quic iv", "", iv_bytes);145        switch (self.capacity.suite) {146            .aes_128_gcm_sha256 => value.key[0..16].* =147                tls.hkdfExpandLabel(Hkdf, secret, "quic key", "", 16),148            .chacha20_poly1305_sha256 => value.key =149                tls.hkdfExpandLabel(Hkdf, secret, "quic key", "", 32),150        }151    }152153    fn writeHeaderMaterial(self: *Keys, secret: Secret) void {154        const value = self.material();155        value.hp = @splat(0);156        switch (self.capacity.suite) {157            .aes_128_gcm_sha256 => value.hp[0..16].* =158                tls.hkdfExpandLabel(Hkdf, secret, "quic hp", "", 16),159            .chacha20_poly1305_sha256 => value.hp =160                tls.hkdfExpandLabel(Hkdf, secret, "quic hp", "", 32),161        }162    }163164    pub fn next(suite: Suite, secret: Secret) Secret {165        return switch (suite) {166            .aes_128_gcm_sha256,167            .chacha20_poly1305_sha256,168            => tls.hkdfExpandLabel(Hkdf, secret, "quic ku", "", secret_bytes),169        };170    }171172    pub fn update(self: *Keys, secret: Secret) void {173        std.debug.assert(self.phase == .steady);174        self.writePacketMaterial(secret);175        self.sealed_packets = 0;176    }177178    pub fn packetKey(self: *const Keys) [key_bytes_max]u8 {179        return self.materialConst().key;180    }181182    pub fn initializationVector(self: *const Keys) [iv_bytes]u8 {183        return self.materialConst().iv;184    }185186    pub fn headerKey(self: *const Keys) [key_bytes_max]u8 {187        return self.materialConst().hp;188    }189190    pub fn selectedSuite(self: *const Keys) Suite {191        std.debug.assert(self.phase == .steady);192        return self.capacity.suite;193    }194195    pub fn keyLength(self: *const Keys) u6 {196        std.debug.assert(self.phase == .steady);197        return self.capacity.key_bytes;198    }199200    pub fn needsUpdate(self: *const Keys) bool {201        std.debug.assert(self.phase == .steady);202        return switch (self.capacity.suite) {203            .aes_128_gcm_sha256 => self.sealed_packets >=204                aes_confidentiality_limit - aes_update_margin,205            .chacha20_poly1305_sha256 => chacha_confidentiality_limit != null,206        };207    }208209    pub fn confidentialityExhausted(self: *const Keys) bool {210        std.debug.assert(self.phase == .steady);211        return switch (self.capacity.suite) {212            .aes_128_gcm_sha256 => self.sealed_packets >= aes_confidentiality_limit,213            .chacha20_poly1305_sha256 => chacha_confidentiality_limit != null,214        };215    }216217    pub fn integrityLimit(self: *const Keys) u64 {218        std.debug.assert(self.phase == .steady);219        return switch (self.capacity.suite) {220            .aes_128_gcm_sha256 => aes_integrity_limit,221            .chacha20_poly1305_sha256 => chacha_integrity_limit,222        };223    }224225    pub fn exhausted(self: *const Keys) bool {226        std.debug.assert(self.phase == .steady);227        return self.failed_opens >= self.integrityLimit();228    }229};

1pub const Limits = struct {2    suite: Suite,3};

1pub const Suite = enum {2    aes_128_gcm_sha256,3    chacha20_poly1305_sha256,45    pub fn keyLength(self: Suite) u6 {6        return switch (self) {7            .aes_128_gcm_sha256 => 16,8            .chacha20_poly1305_sha256 => 32,9        };10    }11};

1pub const Secret = [secret_bytes]u8;

1/// The count of packets one AES-128-GCM key may seal, which RFC 9001 section 6.6 puts at 2^23. A2/// caller compares it against the packets one key has sealed to decide when a key update is due.3/// Reaching it stops further sealing under that key.4pub const aes_confidentiality_limit: u64 = @as(u64, 1) << 23;

1/// The count of packets that may fail authentication under one AES-128-GCM key, which RFC 90012/// section 6.6 puts at 2^52. A caller compares it against failed decryptions to decide when an3/// attacker has had too many guesses. Reaching it stops further opening under that key.4pub const aes_integrity_limit: u64 = @as(u64, 1) << 52;

1/// The number of packets before the AES-GCM confidentiality limit at which an update is already2/// called for. RFC 9001 section 6.6 requires this margin, and the update comes one packet ahead of3/// the hard limit so a sender never has to stop. A key that has sealed the confidentiality limit4/// less this margin reports that it needs an update. This margin sits below the confidentiality5/// limit, which the compiler checks.6pub const aes_update_margin: u64 = 1;

1/// The count of packets that may fail authentication under one ChaCha20-Poly1305 key, which RFC2/// 9001 section 6.6 puts at 2^36. A caller compares it against failed decryptions under this suite.3/// Reaching it stops further opening under that key.4pub const chacha_integrity_limit: u64 = @as(u64, 1) << 36;

1pub const iv_bytes: usize = 12;

1pub const key_bytes_max: usize = 32;

1pub const secret_bytes: usize = 32;

1/// The absence of a confidentiality limit for ChaCha20-Poly1305, because RFC 9001 section 6.6 puts2/// the bound above the 2^62 packets a connection can number. A caller reading the limits for a3/// suite finds out that this one carries no packet count to watch. A ChaCha20-Poly1305 key4/// therefore reports that it needs no update and that its confidentiality is intact, whatever it5/// has sealed.6pub const chacha_confidentiality_limit: ?u64 = null;

1const keys = @import("keys.zig");23pub const Suite = keys.Suite;4pub const Secret = keys.Secret;5pub const Keys = keys.Keys;6pub const Limits = keys.Limits;7pub const Capacity = keys.Capacity;8pub const aes_confidentiality_limit = keys.aes_confidentiality_limit;9pub const aes_integrity_limit = keys.aes_integrity_limit;10pub const aes_update_margin = keys.aes_update_margin;11pub const chacha_confidentiality_limit = keys.chacha_confidentiality_limit;12pub const chacha_integrity_limit = keys.chacha_integrity_limit;13pub const iv_bytes = keys.iv_bytes;14pub const key_bytes_max = keys.key_bytes_max;15pub const secret_bytes = keys.secret_bytes;1617pub const header = @import("header.zig");18pub const initial = @import("initial.zig");19pub const packet = @import("packet.zig");20pub const retry = @import("retry.zig");

1pub const crypto = @import("crypto/root.zig");