Concepts
Security
Encryption and keys, what each part of the system can and can't see, and the controls you have.
Encryption and keys
- Traffic between devices is encrypted end to end with WireGuard.
- Each device makes its own WireGuard key pair and a separate discovery key (X25519) when it first starts. The private keys are stored only in the device's state file, readable by the system only. They're never sent anywhere.
- Discovery messages, the ones devices use to find a direct path, are encrypted with AES-256-GCM, using a key only the two devices can derive.
- HTTPS certificate keys (ECDSA P-256) are made on the machine. Only a certificate request leaves it.
What each part can see
| Part | Can see | Can't see |
|---|---|---|
| Coordination service | Public keys, device names and addresses, your settings, hashed tokens | Private keys, your traffic |
| Relay | Encrypted packets, and which two devices they're between | What's inside them |
| Your devices | Traffic meant for them | Other workspaces' devices |
Auth keys, API tokens and device tokens are stored only as SHA-256 hashes. Each key and token is shown to you once, when it's created.
Workspaces are separate
Every workspace is its own network. A device only learns about devices in its own workspace. The relay only forwards between devices of the same workspace; to anyone else, your devices look offline.
Controls
- Access controls. Rules decide which people and devices can reach each other. Once a policy is saved, everything it doesn't allow is blocked, on each receiving device.
- Device approval. New devices wait for an admin before they can reach anything.
- Key expiry. Devices sign in again after 180 days by default (you can choose 1 to 365, or turn it off). Tagged machines don't expire.
- Two-factor sign-in. Accounts can require an authenticator app. A workspace can require it for everyone, and it's enforced by the database as well as the app.
- Audit log. Every change, sign-in and refused request is recorded. Each entry includes a fingerprint of the one before it, so editing, removing or reordering entries is detectable.
Network requirements
Devices need no inbound ports. They only make outgoing connections:
- HTTPS to the coordination service
- UDP and HTTPS to the relay and STUN server
- UDP directly to other devices, when a direct path is possible
Data retention
| Data | Kept for |
|---|---|
| Audit log | 90 days |
| Network logs (off by default) | 30 days |
Reporting a vulnerability
See getunderpass.com/security for how to report a security issue.