tiny.quic.tls

1pub const Alert = enum(u8) {2    unexpected_message = 10,3    handshake_failure = 40,4    bad_certificate = 42,5    unsupported_certificate = 43,6    illegal_parameter = 47,7    decode_error = 50,8    decrypt_error = 51,9    protocol_version = 70,10    internal_error = 80,11    missing_extension = 109,12    unsupported_extension = 110,13    unrecognized_name = 112,14    certificate_required = 116,15    no_application_protocol = 120,1617    /// Returns the QUIC transport error code for one TLS alert. A connection closing after a18    /// handshake failure calls it to get the code it puts in the CONNECTION_CLOSE frame. RFC 900119    /// section 4.8 forms the code by adding the alert number to 0x0100. Distinct alerts give20    /// distinct codes, so the peer learns which check failed.21    pub fn quicError(self: Alert) u16 {22        return 0x0100 + @as(u16, @backingInt(self));23    }24};

1pub const Engine = struct {2    config: model.Config,3    limits: storage_mod.Storage.Limits,4    storage: *storage_mod.Storage,5    phase: Phase,6    transcript: Sha256,7    key_pair: X25519.KeyPair,8    hello_random: [32]u8,9    schedule: ?tls.schedule.Schedule,10    application: ?tls.schedule.Application,11    receive_length: usize,12    receive_total: usize,13    receive_level: ?model.Level,14    initial_length: usize,15    initial_offset: usize,16    handshake_length: usize,17    handshake_offset: usize,18    peer_key: tls.PublicKey,19    peer_key_present: bool,20    peer_verified: bool,21    peer_parameters_length: usize,22    pending_alert: ?tls.Alert,23    cipher_suite: ?std.crypto.tls.CipherSuite,24    handshake_secrets_present: bool,2526    pub fn init(27        config: model.Config,28        limits: storage_mod.Storage.Limits,29        storage: *storage_mod.Storage,30    ) InitError!Engine {31        try validateConfig(config, limits, storage);32        var random = try config.random.values();33        defer std.crypto.secureZero(u8, std.mem.asBytes(&random));34        var key_pair = X25519.KeyPair.generateDeterministic(random.key_exchange) catch {35            return error.InvalidKey;36        };37        defer std.crypto.secureZero(u8, &key_pair.secret_key);38        var self = Engine{39            .config = config,40            .limits = limits,41            .storage = storage,42            .phase = if (config.role == .client)43                .client_wait_server_hello44            else45                .server_wait_client_hello,46            .transcript = Sha256.init(.{}),47            .key_pair = key_pair,48            .hello_random = random.hello,49            .schedule = null,50            .application = null,51            .receive_length = 0,52            .receive_total = 0,53            .receive_level = null,54            .initial_length = 0,55            .initial_offset = 0,56            .handshake_length = 0,57            .handshake_offset = 0,58            .peer_key = undefined,59            .peer_key_present = false,60            .peer_verified = false,61            .peer_parameters_length = 0,62            .pending_alert = null,63            .cipher_suite = null,64            .handshake_secrets_present = false,65        };66        errdefer std.crypto.secureZero(u8, std.mem.asBytes(&self));67        if (config.role == .client) {68            try self.queueClientHello(random.hello, storage.initialBytesForInitialization());69        }70        storage.activate();71        return self;72    }7374    /// Overwrites every retained handshake secret and every region of the engine's storage with75    /// zeros so a caller finishing with a connection leaves no key material behind in the block it76    /// hands back. The four storage regions and the engine value itself are all covered. The call77    /// frees nothing, because the caller owns the block.78    pub fn deinit(self: *Engine) void {79        const storage = self.storage;80        std.crypto.secureZero(u8, storage.receiveBytes());81        std.crypto.secureZero(u8, storage.initialBytes());82        std.crypto.secureZero(u8, storage.handshakeBytes());83        std.crypto.secureZero(u8, storage.peerBytes());84        std.crypto.secureZero(u8, std.mem.asBytes(self));85    }8687    pub fn receive(self: *Engine, level: model.Level, bytes: []const u8) Error!void {88        if (self.pending_alert != null) return error.TlsAlert;89        if (self.receive_level) |partial_level| {90            if (partial_level != level) return self.reject(.unexpected_message);91        }92        for (bytes) |byte| {93            const input = self.storage.receiveBytes();94            if (self.receive_length >= input.len) return self.reject(.decode_error);95            input[self.receive_length] = byte;96            self.receive_length += 1;97            if (self.receive_length == 1) self.receive_level = level;98            if (self.receive_length == 4) try self.readMessageLength(input[0..4]);99            if (self.receive_total == 0) continue;100            if (self.receive_length != self.receive_total) continue;101            try self.process(level, input[0..self.receive_total]);102            self.receive_length = 0;103            self.receive_total = 0;104        }105        if (self.receive_length == 0) self.receive_level = null;106    }107108    pub fn emit(self: *Engine, level: model.Level, output: []u8) usize {109        if (self.pending_alert != null) return 0;110        const written = switch (level) {111            .initial => emitQueue(112                self.storage.initialBytes(),113                &self.initial_offset,114                self.initial_length,115                output,116            ),117            .handshake => emitQueue(118                self.storage.handshakeBytes(),119                &self.handshake_offset,120                self.handshake_length,121                output,122            ),123            .one_rtt => 0,124        };125        if (self.phase == .client_sending_finished) {126            if (self.handshake_offset == self.handshake_length) self.phase = .client_complete;127        }128        return written;129    }130131    /// Returns the handshake bytes the caller has already taken at one encryption level. The bytes132    /// stay in the engine's storage, so an endpoint that lost a CRYPTO frame retransmits from them,133    /// which RFC 9000 section 13.3 asks of a sender. The 1-RTT level gives an empty slice, because134    /// it carries no handshake bytes. The slice stays valid while the engine does, because it135    /// points into the engine's storage.136    pub fn emitted(self: *const Engine, level: model.Level) []const u8 {137        std.debug.assert(self.initial_offset <= self.initial_length);138        std.debug.assert(self.handshake_offset <= self.handshake_length);139        return switch (level) {140            .initial => self.storage.initialBytes()[0..self.initial_offset],141            .handshake => self.storage.handshakeBytes()[0..self.handshake_offset],142            .one_rtt => &.{},143        };144    }145146    pub fn secret(147        self: *const Engine,148        level: model.Level,149        direction: model.Direction,150    ) ?model.Secret {151        if (self.pending_alert != null) return null;152        return switch (level) {153            .initial => null,154            .handshake => self.handshakeSecret(direction),155            .one_rtt => self.applicationSecret(direction),156        };157    }158159    pub fn state(self: *const Engine) model.Status {160        return switch (self.phase) {161            .client_complete => .handshake_complete,162            .client_confirmed, .server_confirmed => .handshake_confirmed,163            else => .handshaking,164        };165    }166167    pub fn confirm(self: *Engine) void {168        if (self.phase == .client_complete) {169            self.eraseHandshakeTrafficSecrets();170            self.phase = .client_confirmed;171        }172    }173174    pub fn peer(self: *const Engine) ?model.Peer {175        if (self.pending_alert != null) return null;176        if (!self.peer_verified) return null;177        const peer_bytes = self.storage.peerBytes();178        return .{179            .public_key = self.peer_key,180            .alpn = self.config.alpn,181            .transport_parameters = peer_bytes[0..self.peer_parameters_length],182        };183    }184185    pub fn alert(self: *const Engine) ?tls.Alert {186        return self.pending_alert;187    }188189    pub fn cipherSuite(self: *const Engine) ?std.crypto.tls.CipherSuite {190        return self.cipher_suite;191    }192193    fn readMessageLength(self: *Engine, header: []const u8) Error!void {194        std.debug.assert(header.len == 4);195        const body_length = (@as(usize, header[1]) << 16) |196            (@as(usize, header[2]) << 8) | header[3];197        if (body_length > self.limits.max_message) {198            self.pending_alert = .decode_error;199            self.phase = .alerted;200            return error.MessageTooLarge;201        }202        self.receive_total = body_length + 4;203    }204205    fn process(self: *Engine, level: model.Level, bytes: []const u8) Error!void {206        const value = tls.message.decode(bytes) catch return self.reject(.decode_error);207        if (value.kind == .key_update) return self.reject(.unexpected_message);208        if (value.kind == .new_session_ticket) {209            if (level != .one_rtt) return self.reject(.unexpected_message);210            if (self.config.role == .server) return self.reject(.unexpected_message);211            _ = tls.message.decodeNewSessionTicket(bytes) catch return self.reject(.decode_error);212            return;213        }214        if (self.config.role == .client) return self.processClient(level, bytes);215        return self.processServer(level, bytes);216    }217218    fn processClient(219        self: *Engine,220        level: model.Level,221        bytes: []const u8,222    ) Error!void {223        return switch (self.phase) {224            .client_wait_server_hello => self.clientServerHello(level, bytes),225            .client_wait_encrypted_extensions => self.clientEncrypted(level, bytes),226            .client_wait_certificate_request => self.clientRequest(level, bytes),227            .client_wait_certificate => self.receiveCertificate(level, bytes, false),228            .client_wait_certificate_verify => self.receiveCertificateVerify(level, bytes, false),229            .client_wait_finished => self.clientFinished(level, bytes),230            else => self.reject(.unexpected_message),231        };232    }233234    fn processServer(235        self: *Engine,236        level: model.Level,237        bytes: []const u8,238    ) Error!void {239        return switch (self.phase) {240            .server_wait_client_hello => self.serverClientHello(level, bytes),241            .server_wait_certificate => self.receiveCertificate(level, bytes, true),242            .server_wait_certificate_verify => self.receiveCertificateVerify(level, bytes, true),243            .server_wait_finished => self.serverFinished(level, bytes),244            else => self.reject(.unexpected_message),245        };246    }247248    fn clientServerHello(self: *Engine, level: model.Level, bytes: []const u8) Error!void {249        if (level != .initial) return self.reject(.unexpected_message);250        const hello = tls.message.decodeServerHello(bytes) catch return self.reject(.decode_error);251        if (std.mem.eql(u8, &hello.random, &std.crypto.tls.hello_retry_request_sequence)) {252            return self.reject(.handshake_failure);253        }254        const suite = validServerHello(hello) orelse return self.reject(.illegal_parameter);255        const selected = extension.serverSelection(hello.extensions) catch |err| {256            return self.reject(extensionAlert(err));257        };258        if (!selected.tls_1_3) {259            if (hasDowngradeSentinel(hello.random)) return self.reject(.illegal_parameter);260            return self.reject(.protocol_version);261        }262        const peer_share = selected.key_share orelse return self.reject(.missing_extension);263        self.transcript.update(bytes);264        try self.installSchedule(peer_share);265        self.cipher_suite = suite;266        self.phase = .client_wait_encrypted_extensions;267    }268269    fn clientEncrypted(self: *Engine, level: model.Level, bytes: []const u8) Error!void {270        if (level != .handshake) return self.reject(.unexpected_message);271        const encrypted = tls.message.decodeEncryptedExtensions(bytes) catch {272            return self.reject(.decode_error);273        };274        const selected = extension.encryptedSelection(275            encrypted.extensions,276            self.config.alpn,277            self.config.server_name != null,278        ) catch |err| return self.reject(extensionAlert(err));279        if (selected.alpn == null) return self.reject(.no_application_protocol);280        const parameters = selected.transport_parameters orelse {281            return self.reject(.missing_extension);282        };283        if (!selected.server_raw_key) return self.reject(.unsupported_certificate);284        if (!selected.client_raw_key) return self.reject(.unsupported_certificate);285        try self.retainParameters(parameters);286        self.transcript.update(bytes);287        self.phase = .client_wait_certificate_request;288    }289290    fn clientRequest(self: *Engine, level: model.Level, bytes: []const u8) Error!void {291        if (level != .handshake) return self.reject(.unexpected_message);292        const request = tls.message.decodeCertificateRequest(bytes) catch {293            return self.reject(.decode_error);294        };295        if (request.context.len != 0) return self.reject(.illegal_parameter);296        const offered = extension.requestOffersEd25519(request.extensions) catch |err| {297            return self.reject(extensionAlert(err));298        };299        if (!offered) return self.reject(.handshake_failure);300        self.transcript.update(bytes);301        self.phase = .client_wait_certificate;302    }303304    fn serverClientHello(self: *Engine, level: model.Level, bytes: []const u8) Error!void {305        if (level != .initial) return self.reject(.unexpected_message);306        const hello = tls.message.decodeClientHello(bytes) catch return self.reject(.decode_error);307        const suite = validClientHello(hello, self.config.cipher_suite) orelse308            return self.reject(.illegal_parameter);309        const offer = extension.clientOffer(hello.extensions, self.config.alpn) catch |err| {310            return self.reject(extensionAlert(err));311        };312        try self.validateOffer(offer);313        const peer_share = offer.key_share orelse return self.reject(.missing_extension);314        try self.retainParameters(offer.transport_parameters.?);315        self.transcript.update(bytes);316        try self.queueServerFlight(peer_share, offer.server_name != null, suite);317        self.cipher_suite = suite;318        self.phase = .server_wait_certificate;319    }320321    fn validateOffer(self: *Engine, offer: extension.ClientOffer) Error!void {322        if (!offer.tls_1_3) return self.reject(.protocol_version);323        if (!offer.x25519_group) return self.reject(.handshake_failure);324        if (!offer.ed25519_signature) return self.reject(.handshake_failure);325        if (offer.alpn == null) return self.reject(.no_application_protocol);326        if (offer.transport_parameters == null) return self.reject(.missing_extension);327        if (!offer.server_raw_key) return self.reject(.unsupported_certificate);328        if (!offer.client_raw_key) return self.reject(.unsupported_certificate);329        if (self.config.server_name) |wanted| {330            const received = offer.server_name orelse return self.reject(.unrecognized_name);331            if (!std.mem.eql(u8, wanted, received)) return self.reject(.unrecognized_name);332        }333    }334335    fn receiveCertificate(336        self: *Engine,337        level: model.Level,338        bytes: []const u8,339        client_certificate: bool,340    ) Error!void {341        if (level != .handshake) return self.reject(.unexpected_message);342        const certificate = tls.message.decodeCertificate(bytes) catch {343            return self.reject(.decode_error);344        };345        if (certificate.request_context.len != 0) return self.reject(.illegal_parameter);346        var entries = certificate.entries.iterator();347        const entry = entries.next() catch return self.reject(.decode_error);348        if (entry == null) {349            if (client_certificate) return self.reject(.certificate_required);350            return self.reject(.decode_error);351        }352        const second = entries.next() catch return self.reject(.decode_error);353        if (second != null) return self.reject(.unsupported_certificate);354        var entry_extensions = entry.?.extensions.iterator();355        if ((entry_extensions.next() catch return self.reject(.decode_error)) != null) {356            return self.reject(.unsupported_extension);357        }358        self.peer_key = tls.decodeSubjectPublicKeyInfo(entry.?.data) catch {359            return self.reject(.bad_certificate);360        };361        self.peer_key_present = true;362        if (self.config.expected_peer) |expected| {363            if (!std.crypto.timing_safe.eql(tls.PublicKey, expected, self.peer_key)) {364                return self.reject(.bad_certificate);365            }366        }367        self.transcript.update(bytes);368        self.phase = if (client_certificate)369            .server_wait_certificate_verify370        else371            .client_wait_certificate_verify;372    }373374    fn receiveCertificateVerify(375        self: *Engine,376        level: model.Level,377        bytes: []const u8,378        client_signature: bool,379    ) Error!void {380        if (level != .handshake) return self.reject(.unexpected_message);381        if (!self.peer_key_present) return self.reject(.unexpected_message);382        const value = tls.message.decodeCertificateVerify(bytes) catch {383            return self.reject(.decode_error);384        };385        if (value.algorithm != .ed25519) return self.reject(.illegal_parameter);386        if (value.signature.len != 64) return self.reject(.decrypt_error);387        const hash = self.transcriptHash();388        const content = certificateVerifyContent(client_signature, hash);389        tls.verifySignature(390            self.peer_key,391            &content,392            value.signature[0..64].*,393        ) catch return self.reject(.decrypt_error);394        self.transcript.update(bytes);395        self.peer_verified = true;396        self.phase = if (client_signature) .server_wait_finished else .client_wait_finished;397    }398399    fn clientFinished(self: *Engine, level: model.Level, bytes: []const u8) Error!void {400        if (level != .handshake) return self.reject(.unexpected_message);401        try self.verifyFinished(bytes, self.schedule.?.server_handshake);402        self.transcript.update(bytes);403        self.application = self.schedule.?.application(self.transcriptHash());404        self.schedule.?.eraseMasterSecret();405        try self.queueClientFlight();406        self.phase = .client_sending_finished;407    }408409    fn serverFinished(self: *Engine, level: model.Level, bytes: []const u8) Error!void {410        if (level != .handshake) return self.reject(.unexpected_message);411        try self.verifyFinished(bytes, self.schedule.?.client_handshake);412        self.transcript.update(bytes);413        self.eraseHandshakeTrafficSecrets();414        self.phase = .server_confirmed;415    }416417    fn verifyFinished(418        self: *Engine,419        bytes: []const u8,420        traffic_secret: model.Secret,421    ) Error!void {422        const value = tls.message.decodeFinished(bytes) catch return self.reject(.decode_error);423        if (value.verify_data.len != 32) return self.reject(.decrypt_error);424        const expected = tls.schedule.finishedVerifyData(traffic_secret, self.transcriptHash());425        if (!std.crypto.timing_safe.eql(model.Secret, expected, value.verify_data[0..32].*)) {426            return self.reject(.decrypt_error);427        }428    }429430    fn installSchedule(self: *Engine, peer_share: [32]u8) Error!void {431        var shared = X25519.scalarmult(self.key_pair.secret_key, peer_share) catch {432            std.crypto.secureZero(u8, &self.key_pair.secret_key);433            return self.reject(.illegal_parameter);434        };435        defer std.crypto.secureZero(u8, &shared);436        std.crypto.secureZero(u8, &self.key_pair.secret_key);437        var installed = tls.schedule.Schedule.init(shared, self.transcriptHash());438        installed.eraseDerivationSecrets();439        self.schedule = installed;440        self.handshake_secrets_present = true;441    }442443    fn queueClientHello(444        self: *Engine,445        random: [32]u8,446        output_bytes: []u8,447    ) InitError!void {448        var output = quic.cursor.Write.init(output_bytes);449        tls.message.profile.encodeClientHello(.{450            .random = random,451            .key_share = self.key_pair.public_key,452            .alpn = self.config.alpn,453            .transport_parameters = self.config.transport_parameters,454            .server_name = self.config.server_name,455            .cipher_suite = self.config.cipher_suite,456        }, &output) catch return error.EncodingFailed;457        self.initial_length = output.index;458        self.transcript.update(output.written());459    }460461    fn queueServerFlight(462        self: *Engine,463        peer_share: [32]u8,464        acknowledge_name: bool,465        suite: std.crypto.tls.CipherSuite,466    ) Error!void {467        var initial = quic.cursor.Write.init(self.storage.initialBytes());468        tls.message.profile.encodeServerHello(.{469            .random = self.hello_random,470            .key_share = self.key_pair.public_key,471            .cipher_suite = suite,472        }, &initial) catch return self.reject(.internal_error);473        self.initial_length = initial.index;474        self.transcript.update(initial.written());475        try self.installSchedule(peer_share);476        try self.queueServerAuthentication(acknowledge_name);477    }478479    fn queueServerAuthentication(self: *Engine, acknowledge_name: bool) Error!void {480        var output = quic.cursor.Write.init(self.storage.handshakeBytes());481        tls.message.profile.encodeEncryptedExtensions(.{482            .alpn = self.config.alpn,483            .transport_parameters = self.config.transport_parameters,484            .acknowledge_server_name = acknowledge_name,485        }, &output) catch return self.reject(.internal_error);486        self.hashNew(output.written(), &self.handshake_length);487        tls.message.profile.encodeCertificateRequest(&output) catch {488            return self.reject(.internal_error);489        };490        self.hashNew(output.written(), &self.handshake_length);491        tls.message.profile.encodeCertificate(self.config.identity.public(), &output) catch {492            return self.reject(.internal_error);493        };494        self.hashNew(output.written(), &self.handshake_length);495        try self.queueSignedAndFinished(&output, false);496        self.application = self.schedule.?.application(self.transcriptHash());497        self.schedule.?.eraseMasterSecret();498    }499500    fn queueClientFlight(self: *Engine) Error!void {501        var output = quic.cursor.Write.init(self.storage.handshakeBytes());502        tls.message.profile.encodeCertificate(503            self.config.identity.public(),504            &output,505        ) catch return self.reject(.internal_error);506        self.hashNew(output.written(), &self.handshake_length);507        try self.queueSignedAndFinished(&output, true);508    }509510    fn queueSignedAndFinished(511        self: *Engine,512        output: *quic.cursor.Write,513        client_signature: bool,514    ) Error!void {515        const hash = self.transcriptHash();516        const content = certificateVerifyContent(client_signature, hash);517        const signature = self.config.identity.sign(&content) catch {518            return self.reject(.internal_error);519        };520        tls.message.profile.encodeCertificateVerify(signature, output) catch {521            return self.reject(.internal_error);522        };523        self.hashNew(output.written(), &self.handshake_length);524        const traffic = if (client_signature)525            self.schedule.?.client_handshake526        else527            self.schedule.?.server_handshake;528        const verify_data = tls.schedule.finishedVerifyData(traffic, self.transcriptHash());529        tls.message.profile.encodeFinished(verify_data, output) catch {530            return self.reject(.internal_error);531        };532        self.hashNew(output.written(), &self.handshake_length);533    }534535    fn hashNew(self: *Engine, bytes: []const u8, previous_length: *usize) void {536        std.debug.assert(previous_length.* <= bytes.len);537        self.transcript.update(bytes[previous_length.*..]);538        previous_length.* = bytes.len;539    }540541    fn retainParameters(self: *Engine, parameters: []const u8) Error!void {542        const output = self.storage.peerBytes();543        if (parameters.len > output.len) return self.reject(.internal_error);544        @memcpy(output[0..parameters.len], parameters);545        self.peer_parameters_length = parameters.len;546    }547548    fn transcriptHash(self: *const Engine) model.Secret {549        var transcript = self.transcript;550        var digest: model.Secret = undefined;551        transcript.final(&digest);552        return digest;553    }554555    fn handshakeSecret(self: *const Engine, direction: model.Direction) ?model.Secret {556        if (!self.handshake_secrets_present) return null;557        const value = self.schedule orelse return null;558        return switch (self.config.role) {559            .client => if (direction == .write) value.client_handshake else value.server_handshake,560            .server => if (direction == .write) value.server_handshake else value.client_handshake,561        };562    }563564    fn applicationSecret(self: *const Engine, direction: model.Direction) ?model.Secret {565        if (self.config.role == .server and direction == .read) {566            if (self.phase != .server_confirmed) return null;567        }568        const value = self.application orelse return null;569        return switch (self.config.role) {570            .client => if (direction == .write) value.client else value.server,571            .server => if (direction == .write) value.server else value.client,572        };573    }574575    fn eraseHandshakeTrafficSecrets(self: *Engine) void {576        if (!self.handshake_secrets_present) return;577        self.schedule.?.eraseHandshakeTrafficSecrets();578        self.handshake_secrets_present = false;579    }580581    fn reject(self: *Engine, alert_value: tls.Alert) Error {582        self.pending_alert = alert_value;583        self.phase = .alerted;584        return error.TlsAlert;585    }586};

1pub const Error = error{ TlsAlert, MessageTooLarge };

1pub const Config = struct {2    role: Role,3    identity: tls.Identity,4    expected_peer: ?tls.PublicKey,5    alpn: []const u8,6    transport_parameters: []const u8,7    server_name: ?[]const u8,8    random: Random,9    cipher_suite: std.crypto.tls.CipherSuite = .AES_128_GCM_SHA256,10};

1pub const Direction = enum { read, write };

1pub const FixedRandom = struct {2    hello: [32]u8,3    key_exchange: [32]u8,4};

1pub const Level = enum { initial, handshake, one_rtt };

1pub const Peer = struct {2    public_key: tls.PublicKey,3    alpn: []const u8,4    transport_parameters: []const u8,5};

1pub const Random = union(enum) {2    secure: std.Io,3    fixed_for_testing: FixedRandom,45    /// Builds a random source whose bytes the caller fixed in advance. The engine takes the hello6    /// random and the key exchange secret from it, so a handshake built this way repeats exactly. A7    /// test uses this form, and the other form of the source takes its bytes from the caller's I/O8    /// interface through a secure-random call.9    pub fn testing(value: FixedRandom) Random {10        return .{ .fixed_for_testing = value };11    }1213    pub fn values(self: Random) error{RandomFailed}!FixedRandom {14        return switch (self) {15            .fixed_for_testing => |value| value,16            .secure => |io| blk: {17                var value: FixedRandom = undefined;18                io.randomSecure(&value.hello) catch return error.RandomFailed;19                io.randomSecure(&value.key_exchange) catch return error.RandomFailed;20                break :blk value;21            },22        };23    }24};

1pub const Role = enum { client, server };

1/// How far the handshake has reached: still running, complete, or confirmed. A client passes2/// through completion first and reaches confirmation when the caller confirms it, which also erases3/// the handshake traffic secrets. A server reports confirmation directly, once the client's4/// Finished message verifies. A caller therefore treats a server's confirmation as both completion5/// and confirmation.6pub const Status = enum {7    handshaking,8    handshake_complete,9    handshake_confirmed,10};

1pub const Storage = struct {2    pub const storage_alignment: usize = 16;3    pub const Storage = []align(storage_alignment) u8;4    pub const Limits = struct { max_message: u16 };5    pub const Capacity = struct {6        message_bytes: usize,7        receive_bytes: usize,8        initial_bytes: usize,9        handshake_bytes: usize,10        peer_bytes: usize,11        storage_bytes: usize,1213        pub const DeriveError = error{ MessageLimitEmpty, CapacityOverflow };1415        pub fn derive(limits: Limits) DeriveError!Capacity {16            if (limits.max_message == 0) return error.MessageLimitEmpty;17            const message_bytes = std.math.add(18                usize,19                limits.max_message,20                4,21            ) catch return error.CapacityOverflow;22            const handshake_bytes = std.math.mul(23                usize,24                message_bytes,25                server_flight_messages_max,26            ) catch return error.CapacityOverflow;27            const message_regions = std.math.mul(28                usize,29                message_bytes,30                7,31            ) catch return error.CapacityOverflow;32            const storage_bytes = std.math.add(33                usize,34                message_regions,35                limits.max_message,36            ) catch return error.CapacityOverflow;37            return .{38                .message_bytes = message_bytes,39                .receive_bytes = message_bytes,40                .initial_bytes = message_bytes,41                .handshake_bytes = handshake_bytes,42                .peer_bytes = limits.max_message,43                .storage_bytes = storage_bytes,44            };45        }46    };47    pub const InitError = Capacity.DeriveError || error{StorageTooShort};48    pub const work_limits: alloc_phase.capacity.WorkLimits = .{49        .transition_steps_max = 1,50        .cleanup_steps_per_call_max = 0,51        .cleanup_calls_at_capacity_max = 0,52    };5354    pub const claim: alloc_phase.capacity.Declaration = .{55        .source = .{56            .id = "quic.tls_storage",57            .kind = .phase_static,58            .limit_source = .caller,59            .storage = .{60                .covered = &.{61                    .{62                        .id = "handshake_input_output_and_peer_bytes",63                        .lifetime = .steady,64                        .detail = "one receive message, two flights, and peer parameters",65                    },66                },67                .excluded = &.{68                    "caller configuration and identity key storage",69                    "QUIC CRYPTO reassembly and packet protection storage",70                    "cryptographic primitive stack storage and external I/O state",71                },72            },73            .capacity = .{74                .inputs = &.{75                    alloc_phase.capacity.bindInput(Limits, "max_message", "max_message"),76                },77                .type_selectors = &.{},78                .nodes = &.{79                    .{ .input = 0 },80                    .{ .constant = 4 },81                    .{ .add = .{ .left = 0, .right = 1 } },82                    .{83                        .scale = .{ .node = 2, .coefficient = .{ .literal = 7 } },84                    },85                    .{ .add = .{ .left = 3, .right = 0 } },86                },87                .assertions = &.{.{88                    .scope = .closure_total,89                    .measure = .retained,90                    .relation = .exact,91                    .expression = 4,92                }},93            },94            .overload = .{95                .kind = .reject_before_seal,96                .detail = "empty limits and short storage reject before activation",97            },98            .risks = .{99                .transitive = .{100                    .status = .witnessed,101                    .detail = "message parsing and emission use caller storage only",102                },103                .foreign = .{104                    .status = .excluded,105                    .detail = "standard cryptography retains no dynamic engine storage",106                },107            },108            .work = .{ .equation = "initialization to handshake transition steps <= 1" },109            .obligations = &.{110                .{ .key = "quic_tls_capacity", .role = .capacity_model },111                .{ .key = "quic_tls_boundary", .role = .overload },112                .{ .key = "quic_tls_transitive", .role = .transitive_risk },113                .{ .key = "quic_tls_foreign", .role = .foreign_risk },114                .{ .key = "quic_tls_work", .role = .work_bound },115                .{ .key = "quic_tls_root", .role = .custom },116            },117        },118        .bindings = .{119            .owner = @This(),120            .seal = .{121                .family = alloc_phase.capacity.selector(@This().activate),122                .premise = .{123                    .class = .checked_semantic_fact,124                    .authority = .checker,125                },126            },127            .teardown = .{128                .family = alloc_phase.capacity.selector(@This().deinit),129                .premise = .{130                    .class = .checked_semantic_fact,131                    .authority = .checker,132                },133            },134        },135    };136137    phase: alloc_phase.capacity.Phase,138    capacity: Capacity,139    storage: []align(storage_alignment) u8,140141    pub fn init(bytes: @This().Storage, limits: Limits) InitError!@This() {142        const capacity = try Capacity.derive(limits);143        if (bytes.len < capacity.storage_bytes) return error.StorageTooShort;144        return .{145            .phase = .initialization,146            .capacity = capacity,147            .storage = bytes[0..capacity.storage_bytes],148        };149    }150151    pub fn activate(self: *@This()) void {152        std.debug.assert(self.phase == .initialization);153        self.phase = .steady;154    }155156    pub fn deinit(self: *@This()) @This().Storage {157        std.debug.assert(self.phase == .steady);158        std.crypto.secureZero(u8, self.storage);159        self.phase = .teardown;160        const bytes = self.storage;161        self.* = undefined;162        return bytes;163    }164165    /// A client engine writes its ClientHello into the Initial flight region during startup, before166    /// the storage is sealed into its steady phase. The ordinary accessor requires the steady167    /// phase, so this function returns that region while the storage is still in its initialization168    /// phase. The call returns the same bytes the steady accessor later returns.169    pub fn initialBytesForInitialization(self: *@This()) []u8 {170        std.debug.assert(self.phase == .initialization);171        const start = self.capacity.receive_bytes;172        return self.storage[start..][0..self.capacity.initial_bytes];173    }174175    pub fn receiveBytes(self: *@This()) []u8 {176        self.assertSteady();177        return self.storage[0..self.capacity.receive_bytes];178    }179180    pub fn initialBytes(self: *@This()) []u8 {181        self.assertSteady();182        const start = self.capacity.receive_bytes;183        return self.storage[start..][0..self.capacity.initial_bytes];184    }185186    pub fn handshakeBytes(self: *@This()) []u8 {187        self.assertSteady();188        const start = self.capacity.receive_bytes + self.capacity.initial_bytes;189        return self.storage[start..][0..self.capacity.handshake_bytes];190    }191192    pub fn peerBytes(self: *@This()) []u8 {193        self.assertSteady();194        const start = self.capacity.receive_bytes +195            self.capacity.initial_bytes + self.capacity.handshake_bytes;196        return self.storage[start..][0..self.capacity.peer_bytes];197    }198199    fn assertSteady(self: *const @This()) void {200        std.debug.assert(self.phase == .steady);201        std.debug.assert(self.storage.len >= self.capacity.storage_bytes);202    }203};

1pub const Identity = struct {2    key_pair: Ed25519.KeyPair,34    pub fn fromSeed(seed: [Ed25519.KeyPair.seed_length]u8) error{InvalidSeed}!Identity {5        const key_pair = Ed25519.KeyPair.generateDeterministic(seed) catch {6            return error.InvalidSeed;7        };8        return .{ .key_pair = key_pair };9    }1011    pub fn public(self: Identity) PublicKey {12        return self.key_pair.public_key.toBytes();13    }1415    pub fn sign(self: Identity, content: []const u8) error{SigningFailed}![64]u8 {16        const signature = self.key_pair.sign(content, null) catch {17            return error.SigningFailed;18        };19        return signature.toBytes();20    }21};

1pub const InitError = storage_mod.Storage.InitError || InitSpecific;

1pub const PublicKey = [Ed25519.PublicKey.encoded_length]u8;

1pub fn decodeSubjectPublicKeyInfo(2    encoded: []const u8,3) error{ InvalidLength, InvalidPrefix }!PublicKey {4    if (encoded.len != spki_length) return error.InvalidLength;5    if (!std.mem.eql(u8, encoded[0..spki_prefix.len], &spki_prefix)) {6        return error.InvalidPrefix;7    }8    return encoded[spki_prefix.len..][0..@sizeOf(PublicKey)].*;9}

1pub fn encodeSubjectPublicKeyInfo(public_key: PublicKey) [spki_length]u8 {2    var encoded: [spki_length]u8 = undefined;3    encoded[0..spki_prefix.len].* = spki_prefix;4    encoded[spki_prefix.len..].* = public_key;5    return encoded;6}

1pub const spki_length: usize = 44;

1pub fn verify(public_key: PublicKey, content: []const u8, signature: [64]u8) !void {2    const parsed_key = try Ed25519.PublicKey.fromBytes(public_key);3    const parsed_signature = Ed25519.Signature.fromBytes(signature);4    try parsed_signature.verify(content, parsed_key);5}

1pub const Secret = tls.schedule.Secret;

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

1//! The TLS 1.3 handshake a QUIC connection needs runs as a state machine over bytes the caller2//! carries.3//!4//! Before any application data moves, the two endpoints have to agree on a shared secret, each5//! prove who it is, and exchange the settings that govern the connection. Handshake messages travel6//! inside the transport's own frames. The keys a handshake message travels under are selected by an7//! *encryption level*: one of Initial, Handshake, and 1-RTT, so the handshake has to hand bytes out8//! and take bytes in one level at a time.9//!10//! A message can arrive split across more than one delivery, so partial messages have to be held11//! until they are whole. The frames carrying handshake bytes can be lost, so the bytes already12//! handed out have to stay available to be sent again. The secrets derived along the way stop being13//! needed at known points, and leaving them in memory past that point widens what a later14//! compromise reaches.15//!16//! RFC 8446 defines TLS 1.3, and this code follows its message layouts, its key schedule from the17//! shared secret to the application *traffic secret* (the 32 bytes from which one direction's18//! packet keys are derived), and its Finished verification. RFC 9001 section 4 defines how TLS19//! meets QUIC, and this code follows it by carrying handshake bytes per encryption level and20//! turning a TLS alert into a transport error code. The values two endpoints exchange inside the21//! TLS handshake are the *transport parameters*, and an extension carries them. RFC 7250 and RFC22//! 8410 define raw public keys and the Ed25519 key encoding, and identities here are Ed25519 public23//! keys in that 44-byte form.24//!25//! The accepted profile is narrow, taking X25519 for the key exchange, Ed25519 raw public keys for26//! identity, and one of two cipher suites. Both endpoints authenticate, because the server asks the27//! client for a certificate and rejects a client that omits it. A session ticket is parsed and28//! dropped, so each handshake starts fresh. A TLS KeyUpdate message is rejected, because packet key29//! updates are the transport's own business. The engine reaches for no allocator, so the caller30//! derives a byte count from one maximum message size and hands over the block the engine31//! partitions.3233const alert_mod = @import("alert.zig");34const engine_mod = @import("engine/root.zig");35const identity_mod = @import("identity.zig");3637pub const message = @import("message/root.zig");38pub const schedule = @import("schedule.zig");3940pub const Alert = alert_mod.Alert;41pub const PublicKey = identity_mod.PublicKey;42pub const Identity = identity_mod.Identity;43pub const spki_length = identity_mod.spki_length;44pub const encodeSubjectPublicKeyInfo = identity_mod.encodeSubjectPublicKeyInfo;45pub const decodeSubjectPublicKeyInfo = identity_mod.decodeSubjectPublicKeyInfo;46pub const verifySignature = identity_mod.verify;4748pub const Role = engine_mod.Role;49pub const Level = engine_mod.Level;50pub const Direction = engine_mod.Direction;51pub const Limits = engine_mod.Limits;52pub const Capacity = engine_mod.Capacity;53pub const Storage = engine_mod.Storage;54pub const Config = engine_mod.Config;55pub const FixedRandom = engine_mod.FixedRandom;56pub const Random = engine_mod.Random;57pub const Secret = engine_mod.Secret;58pub const Status = engine_mod.Status;59pub const Peer = engine_mod.Peer;60pub const Engine = engine_mod.Engine;61pub const Error = engine_mod.Error;62pub const InitError = engine_mod.InitError;