lib/quic/src/tls/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! The TLS 1.3 handshake a QUIC connection needs runs as a state machine over bytes the caller
 2 //! carries.
 3 //!
 4 //! Before any application data moves, the two endpoints have to agree on a shared secret, each
 5 //! prove who it is, and exchange the settings that govern the connection. Handshake messages travel
 6 //! inside the transport's own frames. The keys a handshake message travels under are selected by an
 7 //! *encryption level*: one of Initial, Handshake, and 1-RTT, so the handshake has to hand bytes out
 8 //! 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 held
11 //! until they are whole. The frames carrying handshake bytes can be lost, so the bytes already
12 //! handed out have to stay available to be sent again. The secrets derived along the way stop being
13 //! needed at known points, and leaving them in memory past that point widens what a later
14 //! compromise reaches.
15 //!
16 //! RFC 8446 defines TLS 1.3, and this code follows its message layouts, its key schedule from the
17 //! shared secret to the application *traffic secret* (the 32 bytes from which one direction's
18 //! packet keys are derived), and its Finished verification. RFC 9001 section 4 defines how TLS
19 //! meets QUIC, and this code follows it by carrying handshake bytes per encryption level and
20 //! turning a TLS alert into a transport error code. The values two endpoints exchange inside the
21 //! TLS handshake are the *transport parameters*, and an extension carries them. RFC 7250 and RFC
22 //! 8410 define raw public keys and the Ed25519 key encoding, and identities here are Ed25519 public
23 //! keys in that 44-byte form.
24 //!
25 //! The accepted profile is narrow, taking X25519 for the key exchange, Ed25519 raw public keys for
26 //! identity, and one of two cipher suites. Both endpoints authenticate, because the server asks the
27 //! client for a certificate and rejects a client that omits it. A session ticket is parsed and
28 //! dropped, so each handshake starts fresh. A TLS KeyUpdate message is rejected, because packet key
29 //! updates are the transport's own business. The engine reaches for no allocator, so the caller
30 //! derives a byte count from one maximum message size and hands over the block the engine
31 //! partitions.
32 
33 const alert_mod = @import("alert.zig");
34 const engine_mod = @import("engine/root.zig");
35 const identity_mod = @import("identity.zig");
36 
37 pub const message = @import("message/root.zig");
38 pub const schedule = @import("schedule.zig");
39 
40 pub const Alert = alert_mod.Alert;
41 pub const PublicKey = identity_mod.PublicKey;
42 pub const Identity = identity_mod.Identity;
43 pub const spki_length = identity_mod.spki_length;
44 pub const encodeSubjectPublicKeyInfo = identity_mod.encodeSubjectPublicKeyInfo;
45 pub const decodeSubjectPublicKeyInfo = identity_mod.decodeSubjectPublicKeyInfo;
46 pub const verifySignature = identity_mod.verify;
47 
48 pub const Role = engine_mod.Role;
49 pub const Level = engine_mod.Level;
50 pub const Direction = engine_mod.Direction;
51 pub const Limits = engine_mod.Limits;
52 pub const Capacity = engine_mod.Capacity;
53 pub const Storage = engine_mod.Storage;
54 pub const Config = engine_mod.Config;
55 pub const FixedRandom = engine_mod.FixedRandom;
56 pub const Random = engine_mod.Random;
57 pub const Secret = engine_mod.Secret;
58 pub const Status = engine_mod.Status;
59 pub const Peer = engine_mod.Peer;
60 pub const Engine = engine_mod.Engine;
61 pub const Error = engine_mod.Error;
62 pub const InitError = engine_mod.InitError;