zoe_wire_protocol/connection/mod.rs
1//! # Connection Management and Protocol Negotiation
2//!
3//! This module provides TLS-based connection management with embedded protocol version
4//! negotiation for the Zoe wire protocol. It implements a sophisticated handshake
5//! mechanism that combines transport security with application-layer protocol compatibility.
6//!
7//! ## Architecture Overview
8//!
9//! The connection system uses **TLS with ALPN (Application Layer Protocol Negotiation)**
10//! to establish secure connections while simultaneously negotiating protocol versions
11//! using **semantic versioning (semver)** compatibility rules.
12//!
13//! ### Key Components
14//!
15//! - **TLS Transport Security**: Ed25519 or ML-DSA-44 based certificates
16//! - **ALPN Protocol Negotiation**: Client advertises supported versions
17//! - **Certificate-Embedded Versioning**: Server embeds negotiated version in certificate
18//! - **Client-Side Validation**: Post-connection protocol compatibility verification
19//!
20//! ## Protocol Negotiation Flow
21//!
22//! ### 1. Client Connection Initiation
23//!
24//! ```text
25//! Client → Server: TLS ClientHello + ALPN Extensions
26//! ┌─────────────────────────────────────────────────────────────────┐
27//! │ ALPN Extensions (Postcard-Serialized Protocol Versions): │
28//! │ - [0x01, 0x02, 0x03, ...] → ProtocolVersion { V1, 1.2.3 } │
29//! │ - [0x01, 0x01, 0x01, ...] → ProtocolVersion { V1, 1.1.0 } │
30//! │ - [0x00, 0x00, 0x09, ...] → ProtocolVersion { V0, 0.9.5 } │
31//! └─────────────────────────────────────────────────────────────────┘
32//! ```
33//!
34//! ### 2. Server Version Negotiation
35//!
36//! The server examines client versions against its requirements:
37//!
38//! ```rust
39//! // Server configuration example
40//! let server_config = ServerProtocolConfig::new(vec![
41//! (ProtocolVariant::V1, VersionReq::parse(">=1.2.0").unwrap()),
42//! (ProtocolVariant::V0, VersionReq::parse(">=0.8.0").unwrap()),
43//! ]);
44//! ```
45//!
46//! **Negotiation Logic:**
47//! 1. **Deserialize ALPN protocols**: Server uses `postcard::from_bytes()` on each ALPN entry
48//! 2. **Parse client versions**: Extract `ProtocolVersion` structs from binary data
49//! 3. **Find highest compatible**: Server finds the **highest client version** that satisfies server requirements
50//! 4. **Embed result**: If match found, embeds negotiated version in TLS certificate extension
51//! 5. **Signal failure**: If no match, returns certificate with **empty protocol extension**
52//!
53//! ### 3. TLS Certificate Response
54//!
55//! **Success Case (Compatible Version Found):**
56//! ```text
57//! Server → Client: TLS Certificate + Extensions
58//! ┌─────────────────────────────────────────────────────────────────┐
59//! │ X.509 Certificate Extension (OID: 1.3.6.1.4.1.99999.1): │
60//! │ [0x01, 0x02, 0x03, ...] → postcard::to_stdvec(&protocol_v1_2_3) │
61//! └─────────────────────────────────────────────────────────────────┘
62//! ```
63//!
64//! **Failure Case (No Compatible Version):**
65//! ```text
66//! Server → Client: TLS Certificate + Extensions
67//! ┌─────────────────────────────────────────────────────────────────┐
68//! │ X.509 Certificate Extension (OID: 1.3.6.1.4.1.99999.1): │
69//! │ [] (Empty byte array - No compatible protocol found) │
70//! └─────────────────────────────────────────────────────────────────┘
71//! ```
72//!
73//! ### 4. Client-Side Validation
74//!
75//! After TLS handshake completion, the client validates protocol compatibility:
76//!
77//! ```rust
78//! use zoe_wire_protocol::version::{validate_server_protocol_support, ClientProtocolConfig};
79//!
80//! let client_config = ClientProtocolConfig::default();
81//! match validate_server_protocol_support(&connection, &client_config) {
82//! Ok(negotiated_version) => {
83//! println!("✅ Protocol negotiated: {}", negotiated_version);
84//! // Proceed with application protocol
85//! }
86//! Err(ProtocolVersionError::ProtocolNotSupportedByServer) => {
87//! println!("❌ Server doesn't support any client protocol versions");
88//! // Handle incompatibility (e.g., upgrade client, contact admin)
89//! }
90//! Err(e) => {
91//! println!("❌ Protocol validation failed: {}", e);
92//! }
93//! }
94//! ```
95//!
96//! ## Error Handling and Debugging
97//!
98//! ### Protocol Mismatch Detection
99//!
100//! When the server cannot find a compatible protocol version:
101//!
102//! 1. **TLS handshake succeeds** (for better debugging)
103//! 2. **Certificate contains empty protocol extension**
104//! 3. **Client detects empty extension** during validation
105//! 4. **Specific error raised**: `ProtocolNotSupportedByServer`
106//!
107//! This approach provides clear error messages instead of cryptic TLS failures:
108//!
109//! ```text
110//! ❌ OLD: "peer doesn't support any known protocol"
111//! ✅ NEW: "Protocol not supported by server: server returned empty ALPN list indicating no compatible protocol"
112//! ```
113//!
114//! ### Debugging Protocol Issues
115//!
116//! Enable debug logging to see the negotiation process:
117//!
118//! ```bash
119//! RUST_LOG=zoe_wire_protocol::connection=debug cargo run
120//! ```
121//!
122//! **Example Debug Output:**
123//! ```text
124//! DEBUG zoe_wire_protocol::connection::ed25519: 📋 Client ALPN protocols: 3
125//! DEBUG zoe_wire_protocol::connection::ed25519: ✅ Negotiated protocol version: V1(1.2.3)
126//! INFO zoe_wire_protocol::connection::client: ✅ Server Ed25519 identity verified via certificate
127//! ```
128//!
129//! ## Supported Cryptographic Algorithms
130//!
131//! ### Ed25519 (Default)
132//! - **Fast signature verification**
133//! - **Small certificate size**
134//! - **Wide compatibility**
135//!
136//! ### ML-DSA-44 (Post-Quantum)
137//! - **Quantum-resistant signatures**
138//! - **NIST standardized**
139//! - **Future-proof security**
140//!
141//! ## Configuration Examples
142//!
143//! ### Server Configuration
144//!
145//! ```rust
146//! use zoe_wire_protocol::version::{ServerProtocolConfig, ProtocolVariant};
147//! use semver::VersionReq;
148//!
149//! // Strict server - only accepts recent versions
150//! let strict_server = ServerProtocolConfig::new(vec![
151//! (ProtocolVariant::V1, VersionReq::parse(">=1.5.0").unwrap()),
152//! ]);
153//!
154//! // Permissive server - accepts older versions
155//! let permissive_server = ServerProtocolConfig::new(vec![
156//! (ProtocolVariant::V1, VersionReq::parse(">=1.0.0").unwrap()),
157//! (ProtocolVariant::V0, VersionReq::parse(">=0.5.0").unwrap()),
158//! ]);
159//! ```
160//!
161//! ### Client Configuration
162//!
163//! ```rust
164//! use zoe_wire_protocol::version::{ClientProtocolConfig, ProtocolVersion, ProtocolVariant};
165//! use semver::Version;
166//!
167//! // Client supporting multiple versions
168//! let client_config = ClientProtocolConfig::new(vec![
169//! ProtocolVersion::new(ProtocolVariant::V1, Version::new(1, 3, 0)),
170//! ProtocolVersion::new(ProtocolVariant::V1, Version::new(1, 2, 0)),
171//! ProtocolVersion::new(ProtocolVariant::V0, Version::new(0, 9, 0)),
172//! ]);
173//! ```
174//!
175//! ## Security Considerations
176//!
177//! - **Certificate validation** ensures server identity
178//! - **Protocol negotiation** prevents downgrade attacks
179//! - **Version requirements** enforce minimum security standards
180//! - **Embedded versioning** prevents protocol confusion attacks
181
182#[cfg(feature = "client")]
183pub mod client;
184
185#[cfg(feature = "server")]
186pub mod server;