# Onion Routing

KayakNet uses onion routing to provide anonymity for all network traffic.

## What is Onion Routing?

Onion routing wraps messages in multiple layers of encryption, like layers of an onion. Each node in the path can only see the previous and next hop, never the full route.

## How It Works

### Circuit Building

```
┌────────┐                                              ┌────────┐
│ Sender │                                              │Receiver│
└───┬────┘                                              └────▲───┘
    │                                                        │
    │  Encrypted for Hop 3                                   │
    │  ┌─────────────────────────────────────────────────┐   │
    │  │ Encrypted for Hop 2                             │   │
    │  │ ┌─────────────────────────────────────────────┐ │   │
    │  │ │ Encrypted for Hop 1                         │ │   │
    │  │ │ ┌─────────────────────────────────────────┐ │ │   │
    │  │ │ │           Original Message              │ │ │   │
    │  │ │ └─────────────────────────────────────────┘ │ │   │
    │  │ └─────────────────────────────────────────────┘ │   │
    │  └─────────────────────────────────────────────────┘   │
    │                                                        │
    ▼                                                        │
┌───────┐          ┌───────┐          ┌───────┐              │
│ Hop 1 │─────────▶│ Hop 2 │─────────▶│ Hop 3 │──────────────┘
└───────┘          └───────┘          └───────┘
Removes one        Removes one        Removes final
layer              layer              layer
```

### Step by Step

1. **Sender** selects 3 random nodes from the network
2. **Sender** generates session keys for each hop
3. **Message** is encrypted in layers:
   * Layer 3: Encrypted with Hop 3's key
   * Layer 2: Encrypted with Hop 2's key
   * Layer 1: Encrypted with Hop 1's key
4. **Hop 1** receives, decrypts outer layer, forwards
5. **Hop 2** receives, decrypts its layer, forwards
6. **Hop 3** receives, decrypts final layer, delivers

## KayakNet Implementation

### Circuit Parameters

| Parameter        | Value             | Rationale                        |
| ---------------- | ----------------- | -------------------------------- |
| Hops             | 3                 | Balance of anonymity and latency |
| Circuit Lifetime | 10 minutes        | Prevent long-term correlation    |
| Key Algorithm    | X25519            | Fast, secure key exchange        |
| Encryption       | ChaCha20-Poly1305 | Modern AEAD cipher               |

### Circuit Selection

Nodes are selected to maximize anonymity:

```go
// Pseudocode for node selection
func selectCircuit() []Node {
    // Avoid selecting same node twice
    // Prefer nodes from different subnets
    // Exclude recently used nodes
    // Favor nodes with good reputation
}
```

### Header Format

```
┌─────────────────────────────────────────────┐
│ Version (1 byte)                            │
├─────────────────────────────────────────────┤
│ Circuit ID (16 bytes)                       │
├─────────────────────────────────────────────┤
│ Next Hop Address (encrypted)                │
├─────────────────────────────────────────────┤
│ Ephemeral Public Key (32 bytes)             │
├─────────────────────────────────────────────┤
│ Encrypted Payload                           │
└─────────────────────────────────────────────┘
```

## Traffic Analysis Resistance

Beyond basic onion routing, KayakNet implements:

### 1. Constant Packet Size

All packets are padded to 1024 bytes, preventing size correlation.

### 2. Timing Obfuscation

Random delays (0-100ms) prevent timing analysis.

### 3. Dummy Traffic

Nodes send fake traffic to obscure real patterns.

### 4. Traffic Mixing

Packets are batched and shuffled before forwarding.

## Anonymity Properties

### What Onion Routing Provides

✅ **Sender Anonymity** - Receiver doesn't know sender ✅ **Receiver Anonymity** - Sender doesn't know receiver's IP ✅ **Relationship Anonymity** - Third parties can't link sender/receiver ✅ **Forward Secrecy** - Past traffic can't be decrypted

### What It Doesn't Provide

❌ **Global Passive Adversary** - Nation-state level monitoring may correlate ❌ **Endpoint Compromise** - If sender or receiver is compromised ❌ **Traffic Confirmation** - If adversary controls first and last hop

## Compared to Tor

| Feature            | KayakNet | Tor     |
| ------------------ | -------- | ------- |
| Default Hops       | 3        | 3       |
| Circuit Rotation   | 10 min   | 10 min  |
| Traffic Padding    | Yes      | Limited |
| Timing Obfuscation | Yes      | No      |
| Dummy Traffic      | Yes      | No      |
| Directory Servers  | No (DHT) | Yes     |

## Performance Impact

Onion routing adds latency:

| Metric     | Without Onion | With Onion  |
| ---------- | ------------- | ----------- |
| Latency    | \~50ms        | \~150-300ms |
| Throughput | High          | Moderate    |
| CPU Usage  | Low           | Moderate    |

The tradeoff is acceptable for privacy-focused applications.

## Configuration

```bash
# Use 5 hops instead of 3 (not recommended)
./kayakd --onion-hops 5

# Note: More hops = more latency, diminishing returns on security
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kayaknet.io/architecture/onion-routing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.