diff --git a/docs/RFC-0014_Secure_Relay.md b/docs/RFC-0014_Secure_Relay.md new file mode 100644 index 0000000..ee7c356 --- /dev/null +++ b/docs/RFC-0014_Secure_Relay.md @@ -0,0 +1,48 @@ +# RFC-0014: Secure Relay Protocol + +## Overview +The Secure Relay Protocol (Layer 2) enables private, onion-routed communication within the Libertaria network. It upgrades the transport layer with privacy-preserving encryption, forward secrecy, and session binding. + +## 1. Cryptographic Primitive +- **Encryption:** `XChaCha20-Poly1305` (Authenticated Encryption with Associated Data). +- **Key Exchange:** `X25519` (Elliptic Curve Diffie-Hellman) for ephemeral shared secrets. +- **Forward Secrecy:** Yes. Each circuit uses ephemeral keys. + +## 2. Session Binding & Usage + +### 2.1 The "Sticky" Session +To balance privacy with network health (spam protection), sessions are **pseudo-anonymous but stable**. +- **Session ID:** 16 bytes. Generated randomly by the **Client** (Initiator). +- **Stickiness:** Packets within a context flow re-use the Session ID. +- **Privacy:** Routers see only the Session ID (for rate-limiting) but cannot correlate it to a user Identity (DID) without owning the private key. + +### 2.2 Nonce Construction +Strict binding of Session ID to the Encryption Nonce prevents replay and context-confusion attacks. +**Warning:** The protocol **REJECTS** any packet where the nonce does not match the session. + +**Nonce Format (24 bytes):** +``` +| Session ID (16 bytes) | Counter/Random (8 bytes) | +``` +- **Byte 0-15:** MUST match the declared Session ID. +- **Byte 16-23:** Monotonically increasing counter or random salt (Client controlled). + +### 2.3 Key Management +- **Relay Keys:** Public X25519 keys are distributed via the DHT/Federation (`dht_nodes` message). +- **Circuit Keys:** Ephemeral keys are generated per circuit (or per packet in stateless mode). +- **Optimization:** Sticky Sessions allow reusing the Ephemeral Key Pair for multiple packets, reducing ECDH overhead for high-throughput flows. + +## 3. Wire Format (RelayPacket) +```zig +struct RelayPacket { + ephemeral_key: [32]u8, // Network Byte Order + nonce: [24]u8, // [SessionID (16) | Rand (8)] + ciphertext: []u8, // Encrypted [NextHop + Payload] +} +``` + +## 4. Privacy Considerations +- **Timestamp Leakage:** The protocol deliberately **excludes** unencrypted timestamps in the header to prevent traffic correlation attacks. +- **Client Sovereignty:** The Client generates the Session ID. Bridges/Guards cannot force a tracking ID onto the client. +- **Verification:** Relays verify the Tag (Poly1305) and Session Binding before forwarding. + diff --git a/docs/RFC-0105_Sovereign_Time_Protocol.md b/docs/RFC-0105_Sovereign_Time_Protocol.md new file mode 100644 index 0000000..e1fa91d --- /dev/null +++ b/docs/RFC-0105_Sovereign_Time_Protocol.md @@ -0,0 +1,52 @@ +# RFC-0105: Sovereign Time Protocol (STP) + +## Overview +The Sovereign Time Protocol (STP) defines the temporal dimension of the Libertaria network. It rejects the limitations of relative system ticks in favor of a sovereign, absolute, and ultra-high-precision time coordinate system. + +## 1. Sovereign Timestamp +Time is represented as **Attoseconds (10^-18 s)** since an absolute **Anchor Epoch**. +- **Type:** `u128` (128-bit unsigned integer). +- **Range:** ~10^21 years (exceeds Heat Death of the Universe). +- **Precision:** Sub-atomic timescale precision. + +### 1.1 Anchor Epochs +To allow interoperability with legacy systems ("The Old World") and objective reality, STP supports multiple anchors: +- `Unix1970`: 1970-01-01 00:00:00 UTC (Legacy compatibility). +- `BitcoinGenesis`: 2009-01-03 18:15:05 UTC (The Immutable Anchor). +- `SystemBoot`: Monotonic relative time (Local/Ephemeral). +- `GPSEpoch`: 1980-01-06 (Precision GNSS). + +## 2. Temporal Epochs (Discretized Time) +To facilitate synchronization, key rotation, and periodic maintainence without central coordination, time is divided into **Epochs**. + +### 2.1 Definition +An **Epoch** is a fixed duration slice of the timeline. +- **Duration:** 1 Hour (`3600` seconds). +- **Boundary:** Aligned to the Anchor. (e.g., Top of the hour). + +### 2.2 Usage +Epochs serve as the heartbeat of the Sovereign Node: +1. **Key Rotation:** Ephemeral encryption keys expire at Epoch boundaries. +2. **Session Renewal:** Long-lived sessions must re-handshake every $N$ epochs. +3. **Cron Scheduling:** Nodes use `Epoch.timeRemaining()` to sleep efficiently until the next synchronization window. +4. **Rate Limiting:** Resource quotas are reset per Epoch. + +### 2.3 Implementation +```zig +const time = @import("l0-transport/time.zig"); +const now = time.SovereignTimestamp.now(); +const epoch = time.Epoch.fromTimestamp(now); + +// Check if we need to rotate keys +if (epoch.index > last_rotation_epoch) { + rotateKeys(); +} + +// Sleep until next epoch +const sleep_duration = epoch.timeRemaining(now); +``` + +## 3. Wire Format +- **SovereignTimestamp:** 17 bytes (`u128` + `u8` Anchor). +- **CompactTimestamp:** 9 bytes (`u64` nanoseconds + `u8` Anchor) - used for Kenya devices (IoT). +