https://github.com/north9-labs/seam
Post-quantum encrypted transport protocol — UDP, multi-stream, built-in FEC, Noise_XX + ML-KEM-768
https://github.com/north9-labs/seam
cryptography forward-error-correction ml-kem networking post-quantum protocol rust udp
Last synced: 11 days ago
JSON representation
Post-quantum encrypted transport protocol — UDP, multi-stream, built-in FEC, Noise_XX + ML-KEM-768
- Host: GitHub
- URL: https://github.com/north9-labs/seam
- Owner: North9-Labs
- License: agpl-3.0
- Created: 2026-05-10T06:01:15.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-05T07:13:34.000Z (17 days ago)
- Last Synced: 2026-06-05T07:16:02.516Z (17 days ago)
- Topics: cryptography, forward-error-correction, ml-kem, networking, post-quantum, protocol, rust, udp
- Language: Rust
- Homepage: https://north9.org
- Size: 284 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: docs/security.md
Awesome Lists containing this project
README
# Seam
**Post-quantum encrypted communications over UDP — written in Rust.**
[](https://github.com/North9-Labs/Seam/actions/workflows/ci.yml)
[](https://github.com/North9-Labs/Seam/actions/workflows/security.yml)
[](LICENSE)
[](#build-from-source)
```sh
curl -fsSL https://install.north9.org/seam.sh | sh
```
Seam replaces `scp`, `netcat`, and `ssh -L` with a single tool that is faster on real-world links and safe against quantum computers. All traffic uses a hybrid Noise_XX + ML-KEM-768 handshake so session keys cannot be decrypted even if elliptic-curve cryptography is broken in the future.
---
## Why seam
TCP was designed in 1974. SSH was bolted on top. The result is a stack that:
- **Stalls on packet loss** — one lost packet blocks all subsequent data until it is retransmitted (head-of-line blocking)
- **Caps out early on high-latency links** — the congestion window math means a 100 ms RTT link with 0.1% loss can only push ~30% of its nominal bandwidth over TCP
- **Is not quantum-safe** — session keys established today with classical ECDH can be decrypted later once a cryptographically-relevant quantum computer exists
Seam fixes all three.
### Speed comparison
> Measured on loopback (single core, x86_64). WAN advantage is larger — TCP degrades at high latency and loss where seam does not.
| | seam | scp (OpenSSH) | rsync over SSH | netcat (no encryption) |
|---|---:|---:|---:|---:|
| **Encrypted throughput** | **568 MiB/s** | ~400 MiB/s | ~380 MiB/s | n/a |
| **Handshake latency** | **247 µs** | ~10 ms | ~10 ms | ~1 ms |
| **Quantum-safe** | ✅ ML-KEM-768 | ❌ | ❌ | ❌ |
| **Head-of-line blocking** | none (UDP + FEC) | yes | yes | yes |
| **High-latency WAN** | ✅ approaches line rate | degrades | degrades | degrades |
| **Multi-stream mux** | ✅ | ❌ | ❌ | ❌ |
seam transfers the same data in about 30% less wall time than scp on a clean local link. On a WAN path with 100 ms RTT and 0.5% loss the gap widens to 2–4×, because seam's forward error correction absorbs most lost packets without a round-trip retransmit.
The FEC arbiter adapts in real time: on high-latency links (RTT > 100 ms) seam proactively adds light FEC repair symbols even before any loss is observed, trading ~10% overhead for zero ARQ round-trips on those paths.
---
## How Seam compares
| Feature | Seam | WireGuard | SSH | QuSecure QuProtect |
|---|---|---|---|---|
| Post-quantum KEM | ✅ ML-KEM-768 (FIPS 203) | ❌ | ❌ | ✅ |
| PQ identity signing | ✅ ML-DSA-65 (FIPS 204) | ❌ | ❌ | Unknown |
| Transport protocol | UDP (custom) | UDP | TCP | Varies |
| Head-of-line blocking | None (FEC) | None | Yes | Unknown |
| Forward secrecy | ✅ Double ratchet | ✅ per-session | ✅ per-session | Unknown |
| Traffic analysis resistance | ✅ padding + chaff + jitter | ❌ | ❌ | ❌ |
| Multi-path anti-jamming | ✅ PathScheduler | ❌ | ❌ | ❌ |
| Session resumption | ✅ zero-RTT | ❌ | ❌ | Unknown |
| FIPS mode | ✅ --fips-mode | ❌ | Partial | ✅ |
| Audit logging (SP 800-53) | ✅ | ❌ | Partial | Unknown |
| Open source | ✅ AGPL-3.0 | ✅ MIT | ✅ | ❌ closed |
| Air-gap traversal | ✅ --via relay | ❌ | ❌ | ❌ |
| File transfer built-in | ✅ seam cp/sync | ❌ | ✅ scp | ❌ |
| Port scanner built-in | ✅ seam scan | ❌ | ❌ | ❌ |
| Proxy (SOCKS5) built-in | ✅ seam proxy | ❌ | ✅ | ❌ |
WireGuard and SSH rely on classical elliptic-curve cryptography and will be vulnerable to harvest-now-decrypt-later attacks once cryptographically-relevant quantum computers exist. QuSecure QuProtect addresses the quantum risk but is closed-source and targets enterprise licensing. Seam is the only open-source protocol combining FIPS 203/204 post-quantum cryptography with traffic analysis resistance and multi-path anti-jamming.
---
## Install
```sh
curl -fsSL https://install.north9.org/seam.sh | sh
```
Installs to `~/.local/bin/seam`. Override:
```sh
SEAM_INSTALL_DIR=/usr/local/bin curl -fsSL https://install.north9.org/seam.sh | sh
```
The installer verifies a SHA-256 checksum before placing the binary.
### Shell completions
```sh
seam completions bash > /etc/bash_completion.d/seam # system-wide
seam completions zsh > ~/.zsh/completions/_seam # user
seam completions fish > ~/.config/fish/completions/seam.fish
```
### First-time setup
```sh
seam doctor # check system readiness
```
Seam respects your `~/.ssh/config` (Host aliases, User, Port, IdentityFile) and stores a persistent identity key in `~/.config/seam/identity` so peers can recognise you across sessions.
---
## Commands
### `seam cp` — file transfer
```sh
# Send a file (zstd-compressed by default)
seam cp ./report.pdf alice@server:/home/alice/report.pdf
# Send a directory
seam cp ./dataset/ alice@server:/data/dataset
# Receive from remote (pull)
seam cp alice@server:/remote/logs ./local-backup/
# Resume an interrupted transfer
seam cp --resume ./large.iso alice@server:/data/
# Raw transfer, no compression (already-compressed files)
seam cp --no-compress ./archive.tar.gz alice@server:/backups/
```
seam bootstraps itself on the remote over SSH if it is not already installed — no manual setup on the server side.
---
### `seam pipe` — bidirectional pipe
Netcat, but post-quantum encrypted and fast.
```sh
# Open a remote shell
seam pipe alice@server -- bash
# Run a command, stream its output locally
seam pipe alice@server -- journalctl -f
# Pipe data between machines
tar cf - ./project | seam pipe alice@server -- tar xf - -C /dest
# Remote port scan (pipe through any tool)
seam pipe alice@server -- nmap -sV 10.0.0.0/24
```
---
### `seam tunnel` — TCP port forward
SSH `-L`, but over seam's UDP transport. Multiple concurrent connections share one post-quantum session.
```sh
# Forward local:8080 → server:localhost:3000
seam tunnel 8080:alice@server:3000
# Access a private database through a jump host
seam tunnel 5432:alice@server:db.internal:5432
# Then connect normally — seam is invisible
psql -h localhost -p 5432 -U myuser mydb
```
---
### `seam fwd` — reverse port forward
Expose a port from a remote machine back to your local machine. Like `ssh -R` but over seam's UDP transport — works through double-NAT, adapts to lossy paths.
```sh
# Remote server listens on :3000, forwards connections to local :8080
seam fwd alice@server:3000 8080
# Expose a local dev service to a remote machine
seam fwd alice@bastion:9090 8080 --local-host 0.0.0.0
# Custom SSH port
seam fwd -p 2222 alice@server:5432 5432
```
Useful for:
- Exposing a local dev server to a remote machine for testing
- Reverse tunneling without a full Seamless relay setup
- Giving a temporary remote endpoint to your laptop
---
### `seam stats` — connection statistics
Measure real-time connection quality to a remote host.
```sh
seam stats alice@server # 5-second measurement window
seam stats alice@server --duration 10
```
```
Seam connection stats alice@server (5s window)
─────────────────────────────────────────────────
RTT min 44ms avg 51ms max 79ms
Throughput recv 234 MiB/s
Path MTU 1400 bytes
cwnd 512 KiB
```
---
### `seam bench` — throughput test
Measure actual seam speed to a host and compare against known baselines.
```sh
seam bench alice@server # 100 MiB test
seam bench alice@server --mib 1000
# Use BBR congestion control instead of CUBIC
SEAM_CC=bbr seam bench alice@server
```
```
────────────────────────────────────────────────────────────────────
tool throughput MiB/s notes
────────────────────────────────────────────────────────────────────
seam █████████████████████████████████ 847 0.706 Gbps ← measured
scp █████████████████░░░░░░░░░░░░░░░░ 400 encrypted TCP (est.)
rsync ████████████████░░░░░░░░░░░░░░░░░ 380 encrypted TCP (est.)
netcat ██████████████████████████████████░ 950 unencrypted TCP (est.)
────────────────────────────────────────────────────────────────────
seam is 2.1× faster than scp on this path
post-quantum safe · UDP · FEC recovery · 247 µs handshake
```
---
### `seam ls` — remote directory listing
```sh
seam ls alice@server:/var/log
seam ls alice@server:/data # trailing slash optional
```
Lists files with Unix-style permissions, human-readable sizes, and names.
---
### `seam config` — persistent settings
Manage defaults so you don't have to pass flags every time.
```sh
seam config init # create ~/.config/seam/config.toml
seam config list # show all settings
seam config get cc # current value
seam config set cc bbr # switch default CC to BBR
seam config set compress false # disable zstd by default
```
Config file location: `~/.config/seam/config.toml`.
---
### `seam update` — self-update
```sh
seam update # download and replace the binary
seam update --check # just print available version
```
---
## How It Works
Every seam command follows the same pattern:
1. **SSH bootstrap** — seam uses your existing SSH config to reach the remote, starts a receiver process, and reads back connection parameters. No new ports need to be opened.
2. **Post-quantum handshake** — client and server perform Noise_XX augmented with ML-KEM-768 in ~247 µs. Each side contributes randomness; neither can force a weak key.
3. **Encrypted UDP transport** — all data flows over a direct UDP path. The transport layer handles loss recovery, ordering, flow control, and multiplexing internally.
### Transport features
| Feature | What it does |
|---|---|
| **CUBIC congestion control** | Fills the pipe without overwhelming routers (switch to BBR with `SEAM_CC=bbr`) |
| **ARQ retransmission** | Resends dropped packets with exponential backoff |
| **GF(2⁸) Reed-Solomon FEC** | Recovers up to *r* losses per *k*-packet group without a round-trip; adapts overhead dynamically via EWMA loss tracking |
| **Adaptive FEC arbiter** | Pure ARQ on clean links, hybrid FEC+ARQ at moderate loss, pure FEC above 15% loss; automatically adds light FEC on high-latency paths (RTT > 100 ms) to avoid ARQ round-trips |
| **Multi-stream mux** | Tunnel, bench, and pipe share one session; streams are independent |
| **DDoS-resistant handshake** | BLAKE3 cookie challenge before any per-client state is allocated |
| **Header protection** | Session ID and packet number encrypted in addition to payload |
| **Flow control** | Dynamic 16 MiB windows extended via MaxData frames; control packets bypass congestion control |
| **Keepalive** | Automatic Ping/Pong every 15 s; idle timeout after 60 s |
---
## Security
### What is protected
Every byte sent over seam is encrypted with **ChaCha20-Poly1305**, an AEAD cipher with a 256-bit key. The packet header — session ID, packet number, flags — is additionally encrypted so passive observers cannot correlate traffic to sessions.
### The handshake
Seam uses **Noise_XX** (mutual authentication with forward secrecy) combined with **ML-KEM-768** (CRYSTALS-Kyber, NIST post-quantum standard). The hybrid construction means:
- A classical adversary cannot break the session (x25519 elliptic-curve hardness)
- A quantum adversary cannot break the session (ML-KEM-768 hardness)
- Traffic recorded today cannot be decrypted later even if one primitive is broken in the future
Both parties authenticate with long-term identity keypairs and exchange ephemeral keys for forward secrecy.
### Anti-replay
Each packet carries a 64-bit sequence number. The receiver maintains a sliding bitmap window; duplicate or out-of-window packets are silently dropped. An attacker who captures and replays a packet cannot cause it to be accepted a second time.
### DDoS resistance
The server commits no per-client memory until the client echoes a valid BLAKE3 cookie that is tied to its source IP and expires after 30 seconds. This prevents an attacker from exhausting server memory by spoofing connection requests.
### Honest disclaimer
Seam is pre-1.0 software. The cryptographic design follows well-established patterns and uses audited primitives, but the protocol itself has not undergone a third-party security audit. Do not use it where your threat model requires independently audited software.
---
## Troubleshooting
### "handshake timed out"
- Seam automatically retries the handshake up to 3 times with exponential backoff.
- If it still fails, check that UDP is not blocked by a firewall.
- Increase kernel socket buffers:
```sh
sudo sysctl -w net.core.rmem_max=8388608
sudo sysctl -w net.core.wmem_max=8388608
```
### "seam not found on remote"
- seam bootstraps automatically, but if the remote has no internet access, copy the binary manually to `~/.local/bin/seam`.
### Slow throughput on LAN
- seam is optimised for lossy / high-latency paths. On pristine LAN, scp may be similar. Use `seam bench` to verify.
### Verbose logging
- Add `-v` (info), `-vv` (debug), or `-vvv` (trace) to any command:
```sh
seam -vv cp ./data user@host:/dest
```
---
## Build from Source
```sh
# Prerequisites: Rust 1.88+
git clone https://github.com/North9-Labs/Seam
cd Seam
cargo build --release --bin seam
./target/release/seam --version # Linux / macOS
# target\release\seam.exe --version # Windows
```
Test suite:
```sh
cargo test
```
Benchmarks (Criterion, single-core loopback):
```sh
cargo bench
```
Fuzz targets:
```sh
cargo install cargo-fuzz
cargo fuzz run packet_decode
```
---
## Library Usage
```toml
# Cargo.toml
seam-protocol = { git = "https://github.com/North9-Labs/Seam" }
```
### Client / Server
```rust
use seam_protocol::{api::{Client, Server}, handshake::IdentityKeypair};
// Server — bind and wait for a connection
let id = IdentityKeypair::generate();
let mut server = Server::bind("0.0.0.0:4433".parse()?, id).await?;
let conn = server.accept().await.unwrap();
// Client — connect to the server
let id = IdentityKeypair::generate();
let client = Client::bind("0.0.0.0:0".parse()?, id).await?;
let conn = client.connect(server_addr, &server_x25519, &server_kem_pk).await?;
```
### Multiplexed streams
Streams implement `AsyncRead + AsyncWrite + Unpin` and compose directly with tokio I/O utilities.
```rust
use seam_protocol::tunnel::SeamMux;
let mux = SeamMux::new(conn); // wraps a SeamConn
// Open a stream from either side
let mut stream = mux.open_stream().await; // locally-initiated
let mut stream = mux.accept_stream().await.unwrap(); // remote-initiated
// Drop in anywhere tokio I/O is expected
tokio::io::copy_bidirectional(&mut stream, &mut tcp_socket).await?;
```
### Datagrams
```rust
// Unreliable, unordered — useful for real-time data
conn.send_datagram(b"ping").await?;
```
---
## Performance
> Single-core, loopback, x86_64. Numbers vary with hardware and kernel UDP buffer limits.
**568 MiB/s (~4.76 Gbps) encrypted throughput at 1400 B MTU. 247 µs full Noise_XX + ML-KEM-768 handshake.**
| Payload size | Encrypt + send | Throughput |
|---|---|---:|
| 64 B | 350 ns | ~303 MiB/s |
| 256 B | 644 ns | ~455 MiB/s |
| 512 B | 1.03 µs | ~519 MiB/s |
| 1400 B | 2.43 µs | **~568 MiB/s** |
| Operation | Time |
|---|---:|
| `IdentityKeypair::generate` | 17.8 µs |
| `PacketKeys::derive_from_secret` | 370 ns |
| Full handshake (Noise_XX + ML-KEM-768, 3 messages) | **247 µs** |
---
## Repository Layout
```
src/
├── api.rs # Client, Server, SeamConn
├── tunnel.rs # SeamMux + SeamStream (AsyncRead + AsyncWrite)
├── crypto/ # ChaCha20-Poly1305, header protection, anti-replay
├── handshake/ # Noise_XX + ML-KEM-768, DDoS-resistant cookie
├── session/ # Streams, ARQ, flow control, priority scheduling
├── fec/ # GF(2⁸) arithmetic, systematic RS codec, adaptive FEC/ARQ arbiter
└── transport/ # Connection, endpoint, CUBIC/BBR CC, pacer, path probing
src/bin/seam/
├── main.rs # CLI entry point
├── copy.rs # seam cp
├── pipe.rs # seam pipe
├── tunnel.rs # seam tunnel (local port forward, ssh -L)
├── fwd.rs # seam fwd (reverse port forward, ssh -R)
├── bench.rs # seam bench
├── stats.rs # seam stats (live connection metrics)
├── ls.rs # seam ls
└── config.rs # seam config
benches/ # Criterion benchmarks
fuzz/ # cargo-fuzz targets
```
---
## License
Seam is dual-licensed:
- **Open source:** [GNU Affero General Public License v3.0](LICENSE) — free for open source projects and personal use
- **Commercial:** contact [licensing@north9.org](mailto:licensing@north9.org) for proprietary, SaaS, government, or OEM use
See [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL) for details.