Security → Architecture
Security architecture
TunnelCrib has four components. Only two of them ever see Service traffic; the Central Server only ever sees control-plane and signaling messages.
| Component | Role | Sees Service traffic? |
|---|---|---|
| TunnelCrib Client | Requests a Tunnel, opens a local listener, forwards Service traffic to the Agent. | Yes (it is one endpoint of the Tunnel) |
| Central Server | Authenticates Devices, enforces organization isolation, allocates sessions, relays signaling messages. | No — signaling only |
| TunnelCrib Agent | Advertises approved Services, serves the requested Service over the established transport. | Yes (it is the other endpoint) |
TunnelCrib Relay (tunnelcrib-bridge) | Optional data-plane hop, used only when a Direct Tunnel cannot be established. | See What the Relay can see |
Direct Tunnel first, Relay only on failure
Every Tunnel attempt tries a direct Client–Agent path before ever involving a Relay, using three fallback tiers:
| Tier | Mechanism | Falls back when |
|---|---|---|
| 0 | UDP + KCP, STUN-assisted NAT traversal | STUN unreachable, no peer candidate, or punch timeout |
| 1 | TCP simultaneous-open punch (SO_REUSEPORT) | Tier 0 fails within the shared punch budget |
| 2 | TunnelCrib Relay (tunnelcrib-bridge), hosted or a Private Relay | Tier 1 also fails within the total punch budget (10s) |
Whichever tier wins, SSH is the only authentication and encryption layer. UDP and TCP punching only establish the underlying byte stream; the SSH handshake, host-key pinning, and public-key authentication are identical in every tier.
Registration and authorization sequence
- TunnelCrib Client and TunnelCrib Agent each register with the Central Server (
hostname,uuid, and, for Agents, advertisedprotocols). - The Central Server validates each Device against the organization's registry by organization, UUID, and Device type.
- The Central Server issues a nonce challenge to both peers.
- Client and Agent sign the nonce with their per-Device identity key (see Device identity).
- The Central Server verifies the signature against the registered public key. Connections failing this check are rejected.
- When a Client requests a Tunnel, the Central Server checks the requested protocol against the Agent's advertised list and organization boundary before signaling either peer.
Independently of the registration handshake, every Direct Tunnel's SSH layer separately pins a per-session Client public key and, after first use, the Agent's host key — so a Direct Tunnel cannot be impersonated even if the transport-level address exchange were spoofed.