Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions docs/protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ from a provider that claimed the capabilities relied on.
| [scallion-network.md](scallion-network.md) | **Scallion Network:** experimental three-hop route planner, sticky sessions, HQTerm integration boundaries and security backlog |
| [scallion-exit-policy.md](scallion-exit-policy.md) | Opt-in exit admission guard: block private IPs, local DNS and DNS rebinding |
| [scallion-clients.md](scallion-clients.md) | Independent native and OpenVPN Connect client modes, profile security requirements and rollout gates |
| [scallion-frames.md](scallion-frames.md) | Experimental X25519/HKDF/AES-GCM hop frames, replay tests and unimplemented security boundaries |

## Implementation

Expand Down
87 changes: 87 additions & 0 deletions docs/protocol/scallion-frames.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Experimental Scallion encrypted hop frames (v1)

**Status: isolated cryptographic unit-test primitive, NOT a functional
privacy network, VPN, OpenVPN server, or audited cryptographic protocol.**

`c0mpute_net::scallion_frames` implements nested ciphertext for three
configured hops and verifies that each relay can open only its own
layer. It does not connect to any network socket and has no exit path.

## What is actually implemented

- Exactly three hop layers in the order **guard → middle → exit**.
- The client chooses three externally authenticated and distinct
X25519 relay public keys and distinct peer identifiers.
- Per-circuit random 128-bit ID and a fresh client X25519 ephemeral
keypair per hop.
- Each layer derives a different AES-256-GCM key with X25519 ECDH +
HKDF-SHA256. The HKDF context binds the circuit, role, client
ephemeral key and relay public key.
- Binary frames have a length bound, version, circuit ID, hop index,
sender ephemeral key, monotonic sequence and AEAD-authenticated
header. Nonces are unique within one live client circuit because
the sender internally increments the sequence number.
- A relay decrypts one layer into the next peer ID plus opaque
nested frame, or the exit's plaintext. It checks the circuit, role,
AEAD authentication and rejects duplicate/out-of-order sequence
numbers. A failed decryption does not advance replay state.
- Malformed lengths, oversized payloads, low-order relay keys,
duplicate relay identifiers/keys, header/ciphertext modification,
wrong relay keys and replayed packets are tested.

```sh
cargo test -p c0mpute-net scallion_frames --locked
```

## Critical security limitations

This is **NOT Tor / a full anonymity protocol**:

- The relay X25519 key must be securely bound to the intended libp2p
peer identity, but the key authentication and identity-binding
handshake are **not implemented** here. Unauthenticated peer keys
invite active man-in-the-middle attacks.
- Long-lived relay static keys provide **no forward secrecy
against later compromise of those keys**. An authenticated
ephemeral-ephemeral handshake with replay-protected circuit setup,
key rotation, revocation and forward secrecy is required.
- No actual forwarding, multiplexing, flow control, padding, path
diversity attestations, congestion control, traffic shaping,
privacy-preserving probing or packet loss recovery is implemented.
- The strict increasing replay check only suits **one ordered stream**.
Reordering would be rejected. A production transport needs
independent stream keys/counters and a bounded sliding replay window.
- A guard sees the client's network IP and next hop; an exit sees the
destination and plaintext if the application doesn't use TLS.
Global observers can correlate timing and bytes. No anonymity claim
is justified by layer encryption alone.
- In-memory counters must not be rolled back or resumed from a stale
checkpoint. Every new circuit needs fresh keys and a random ID.
- A middle hop is not verified to be independent of its neighbors.
Claimed operator IDs/ASNs are not authenticated proof.
- An opt-in, egress-restricted exit service, TUN/SOCKS5 interface,
DNS/IPv6 fail-closed behavior, OpenVPN-compatible gateway,
independent multi-node tests and outside security review remain
**mandatory before user-facing connections can be enabled**.

## Follow-up implementation sequence

1. Specify and review an authenticated ephemeral relay handshake with
forward secrecy, circuit teardown, limits and anti-replay.
2. Bind relay keys and capabilities to signed libp2p identities and
operator consent.
3. Carry these frames over authenticated P2P streams through exactly
three independent relay nodes, with bounded per-circuit memory,
bandwidth, connection counts and explicit exit policy.
4. Add ordered stream multiplexing with distinct traffic keys and
rekeying, and test relay churn/failures. Do not pretend arbitrary
established TCP sockets survive an exit-IP change.
5. Integrate with a native OS-specific TUN client, **separately**
support OpenVPN Connect via an opted-in OpenVPN-protocol entry
gateway. Complete IPv4/IPv6/DNS/killswitch leak tests.
6. Run adversarial E2E tests across real independent hosts and obtain
independent security assessment before any production anonymity
or VPN branding.

See [Scallion architecture](scallion-network.md),
[client modes](scallion-clients.md), #386 and #389.
2 changes: 2 additions & 0 deletions node/crates/c0mpute-net/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ futures = { workspace = true }
libp2p = { workspace = true }
serde_json = { workspace = true }
zeroize = { workspace = true }
aes-gcm = { workspace = true }
x25519-dalek = { workspace = true }
hkdf = { workspace = true }
sha2 = { workspace = true }
rand = { workspace = true }
Expand Down
1 change: 1 addition & 0 deletions node/crates/c0mpute-net/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ pub mod identity;
pub mod scallion;
pub mod scallion_exit;
pub mod scallion_clients;
pub mod scallion_frames;
pub mod swarm;
pub mod topics;

Expand Down
Loading
Loading