feat: Add comprehensive Mycelium network architecture documentation
This commit is contained in:
mik-tf
225
docs/mycelium-network/architecture.md
Normal file
225
docs/mycelium-network/architecture.md
Normal file
@@ -0,0 +1,225 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Mycelium Network Architecture
|
||||
|
||||
Understanding Mycelium's architecture reveals why it's fundamentally different from traditional networking solutions.
|
||||
|
||||
## Core Innovation: Identity = Address
|
||||
|
||||
Mycelium's architecture revolves around **peers**. Each peer has a cryptographic private/public keypair, and these are used to encrypt all messages in an end-to-end fashion.
|
||||
|
||||
The hash of the public key is used as an **IPv6 address**. This means that the cryptographic identity and the network address of each peer are **inherently linked**.
|
||||
|
||||
### What This Means in Practice
|
||||
|
||||
Think of it like a postal system where you can send a secret message to anyone just by knowing their address. The recipient can read it simply because they reside at the intended destination, without requiring any additional coordination or precommunication.
|
||||
|
||||
- **Your address IS your identity** - No separation between who you are and where you are
|
||||
- **Automatic encryption** - Messages are encrypted to the destination by design
|
||||
- **No key exchange needed** - The address itself contains the encryption key
|
||||
|
||||
<div className="info-box">
|
||||
|
||||
### 🔐 Technical Lineage
|
||||
|
||||
This innovation was pioneered by the **cjdns** network, which later inspired **Yggdrasil**, from which Mycelium is inspired. Each generation has refined and improved upon this fundamental concept.
|
||||
|
||||
</div>
|
||||
|
||||
## Why This Is More Secure Than TLS/HTTPS
|
||||
|
||||
Compare this to the regular web, where most traffic is encrypted using TLS/HTTPS:
|
||||
|
||||
### The TLS Problem
|
||||
|
||||
In traditional TLS/HTTPS:
|
||||
|
||||
- ❌ **No inherent link** between a TLS cryptographic identity (certificate) and the destination of the traffic
|
||||
- ❌ **Self-signed certificates** are rare and not considered secure (without identity-destination link, impossible to know if created by a MITM attacker)
|
||||
- ❌ **Centralized certificate authorities** - Internet devices must be loaded with a list of trusted CAs
|
||||
- ❌ **Single points of failure** - CAs can be compromised, fail, or be coerced
|
||||
|
||||
### The Mycelium Solution
|
||||
|
||||
✅ **Cryptographic identity = Network address** - MITM attacks are cryptographically impossible
|
||||
✅ **No trusted intermediaries** - No certificate authorities to compromise
|
||||
✅ **Decentralized by design** - No single point of failure
|
||||
✅ **Improved security AND resiliency** - Both benefits simultaneously
|
||||
|
||||
## Network Architecture: Underlay & Overlay
|
||||
|
||||
Mycelium creates a **mesh network** to deliver encrypted IP overlay traffic. But how do peers actually connect?
|
||||
|
||||
### The Underlay Network
|
||||
|
||||
Mycelium peers must connect somehow to form the mesh. Most commonly, peers connect **over the regular internet**, using it as an **underlay network**.
|
||||
|
||||
This is enabled by **public peers** - special nodes that are open to receive connections on the regular internet.
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ Regular Internet (Underlay) │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Public │ │ Public │ │ Public │ │
|
||||
│ │ Peer A │ │ Peer B │ │ Peer C │ │
|
||||
│ └────▲─────┘ └────▲─────┘ └────▲─────┘ │
|
||||
│ │ │ │ │
|
||||
└───────┼────────────────┼────────────────┼────────┘
|
||||
│ │ │
|
||||
┌───┴────┐ ┌───┴────┐ ┌───┴────┐
|
||||
│ Your │◄─────►│ Your │◄─────►│ Your │
|
||||
│Device 1│ Mesh │Device 2│ Mesh │Device 3│
|
||||
└────────┘ └────────┘ └────────┘
|
||||
Encrypted Mycelium Overlay Network
|
||||
```
|
||||
|
||||
### The Overlay Network
|
||||
|
||||
On top of the underlay, Mycelium creates an **encrypted overlay** where:
|
||||
|
||||
- All traffic between your devices is end-to-end encrypted
|
||||
- Routing is handled by the mesh protocol
|
||||
- Your devices appear to be on the same local IPv6 network
|
||||
|
||||
## Resilient Multi-Path Routing
|
||||
|
||||
Here's where Mycelium achieves **more resilient routing than the regular internet**:
|
||||
|
||||
### How It Works
|
||||
|
||||
Each peer generally connects to **multiple public peers**, each offering a **different potential path** for traffic.
|
||||
|
||||
```
|
||||
┌────────────────┐
|
||||
│ Your Device │
|
||||
└───┬─────┬─────┬┘
|
||||
│ │ │
|
||||
┌────────┤ │ └────────┐
|
||||
│ │ │
|
||||
┌───▼────┐ ┌───▼────┐ ┌────▼───┐
|
||||
│Public │ │Public │ │Public │
|
||||
│Peer 1 │ │Peer 2 │ │Peer 3 │
|
||||
│Germany │ │Belgium │ │Finland │
|
||||
└────────┘ └────────┘ └────────┘
|
||||
Route A Route B Route C
|
||||
```
|
||||
|
||||
### Real-World Resilience
|
||||
|
||||
If the route via one public peer is interrupted—such as by an **undersea cable cut**—there's a possibility to find another route via another public peer.
|
||||
|
||||
<div className="info-box">
|
||||
|
||||
### 🌊 Real Example
|
||||
|
||||
This isn't just theoretical. We have experienced interruptions that were traceable with good certainty to **undersea cable cuts** happening at the same time. The network automatically routed around the failure using alternative paths.
|
||||
|
||||
</div>
|
||||
|
||||
**Why the regular internet can't do this:**
|
||||
|
||||
- Most internet connections have a single ISP path
|
||||
- BGP routing changes slowly and requires coordination
|
||||
- No automatic multi-path at the user level
|
||||
- Cable cuts can disconnect entire regions
|
||||
|
||||
**Why Mycelium can:**
|
||||
|
||||
- You're connected to multiple geographically diverse peers
|
||||
- Mesh routing adapts automatically in seconds
|
||||
- No coordination needed—it's peer-to-peer
|
||||
- Traffic flows through available paths automatically
|
||||
|
||||
## Key Architectural Components
|
||||
|
||||
### 1. Cryptographic Keypair
|
||||
|
||||
Every Mycelium node generates:
|
||||
- **Private key** - Kept secret, never shared
|
||||
- **Public key** - Shared openly, identifies your node
|
||||
|
||||
### 2. IPv6 Address
|
||||
|
||||
Derived from your public key:
|
||||
- **Format**: Standard IPv6 (e.g., `5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca`)
|
||||
- **Unique**: Cryptographically guaranteed to be unique
|
||||
- **Persistent**: Doesn't change unless you generate new keys
|
||||
|
||||
### 3. Peer Connections
|
||||
|
||||
Your node maintains connections to:
|
||||
- **Public peers** - For internet connectivity and routing
|
||||
- **Direct peers** - Other nodes you explicitly connect to
|
||||
- **Discovered peers** - Nodes found through the mesh
|
||||
|
||||
### 4. Routing Table
|
||||
|
||||
Each node maintains:
|
||||
- **Known peers** and their addresses
|
||||
- **Path costs** to reach each peer
|
||||
- **Multiple routes** to most destinations
|
||||
- **Automatic updates** as the network changes
|
||||
|
||||
## Message Encryption Flow
|
||||
|
||||
When you send data to another Mycelium address:
|
||||
|
||||
1. **Lookup destination** - Find the IPv6 address
|
||||
2. **Derive public key** - Extract from the address
|
||||
3. **Encrypt message** - Using the destination's public key
|
||||
4. **Route through mesh** - Via optimal path
|
||||
5. **Decrypt at destination** - Using their private key
|
||||
|
||||
Only the destination can decrypt—not even the public peers can read the content.
|
||||
|
||||
## Benefits of This Architecture
|
||||
|
||||
### Security Benefits
|
||||
|
||||
- **End-to-end encryption** - Built into the protocol
|
||||
- **No MITM attacks** - Identity = Address prevents it
|
||||
- **No trusted third parties** - Fully peer-to-peer
|
||||
- **Private by default** - Encryption isn't optional
|
||||
|
||||
### Resilience Benefits
|
||||
|
||||
- **Multi-path routing** - Automatic failover
|
||||
- **Self-healing** - Network adapts to failures
|
||||
- **No single point of failure** - Fully distributed
|
||||
- **Works behind NAT** - Firewall traversal built-in
|
||||
|
||||
### Simplicity Benefits
|
||||
|
||||
- **Zero configuration** - Just run and connect
|
||||
- **Automatic key management** - No manual setup
|
||||
- **Plug and play** - Works immediately
|
||||
- **Cross-platform** - Same protocol everywhere
|
||||
|
||||
## Comparison with Other Technologies
|
||||
|
||||
| Feature | Mycelium | Traditional VPN | TLS/HTTPS | Tor |
|
||||
|---------|----------|----------------|-----------|-----|
|
||||
| **Identity = Address** | ✅ Yes | ❌ No | ❌ No | ❌ No |
|
||||
| **Decentralized** | ✅ Yes | ❌ Central server | ❌ Needs CAs | ✅ Yes |
|
||||
| **Multi-path routing** | ✅ Yes | ❌ Single path | ❌ Single path | ✅ Yes |
|
||||
| **Direct connections** | ✅ When possible | ❌ Via server | ✅ Yes | ❌ Via relays |
|
||||
| **Zero config** | ✅ Yes | ❌ Needs setup | ✅ Browser only | ❌ Complex |
|
||||
| **Performance** | ✅ Fast | ⚠️ Moderate | ✅ Fast | ❌ Slow |
|
||||
|
||||
## Technical Resources
|
||||
|
||||
For more technical details:
|
||||
|
||||
- **Source Code**: [github.com/threefoldtech/mycelium](https://github.com/threefoldtech/mycelium)
|
||||
- **Yggdrasil Network**: [yggdrasil-network.github.io](https://yggdrasil-network.github.io/)
|
||||
- **cjdns Project**: [github.com/cjdelisle/cjdns](https://github.com/cjdelisle/cjdns)
|
||||
|
||||
---
|
||||
|
||||
:::tip Understanding Makes It Powerful
|
||||
|
||||
Now that you understand how Mycelium works, you can appreciate why it's not just another VPN—it's a fundamentally different approach to secure networking that eliminates entire classes of security problems.
|
||||
:::
|
||||
Reference in New Issue
Block a user