Security and pairing
תוכן זה אינו זמין עדיין בשפה שלך.
Threat model
Section titled “Threat model”The Wi-Fi password is not a secret per computer: everyone who has seen it has it.
- Under WPA2-PSK, a member who knows the password and captures another computer’s handshake can decrypt that computer’s traffic.
- A fake network with the same name and password receives everything.
- WPA3 for groups needs recent hardware, and still doesn’t stop a fake network.
So authentication happens in Ferry, with a long-term key per device. Out of scope: an attacker with no radio nearby, and a compromised operating system.
The promise
Section titled “The promise”- Only a computer you paired gets through the phone.
- A computer only sends traffic to the phone it paired with.
- A neighbour’s
DIRECT-xx-Ferrynetwork is never used: an unknown one is joined only while a QR is on screen, and it can’t pass pairing without that QR. - No custom cryptography: Noise through
snow, a widely used open-source implementation.
Handshakes at a glance
Section titled “Handshakes at a glance”| Use | Noise protocol |
|---|---|
| Pairing | Noise_KXpsk0_25519_ChaChaPoly_BLAKE2s |
| Every later connection | Noise_IK_25519_ChaChaPoly_BLAKE2s |
Both use the prologue "Ferry Link v1", so a peer speaking another version fails the
handshake instead of being misread. A version mismatch tells the user to update Ferry on both
devices.
What this gives you
Section titled “What this gives you”- Mutual authentication: both sides prove they hold the private key the other pinned.
- Confidentiality and integrity of everything on the link, on top of WPA2.
- Forward secrecy: every connection mixes in fresh ephemeral keys, so a key stolen later doesn’t decrypt recorded traffic.
- Replay resistance: a recorded handshake can’t be played back (TAI64N timestamps).
What it doesn’t
Section titled “What it doesn’t”- It doesn’t hide that a Ferry network exists, or the computer’s and phone’s MAC addresses.
- It doesn’t protect traffic after the phone: from the phone to the internet, your traffic is as protected as the apps make it (HTTPS, for example), the same as on the phone itself.
- It doesn’t defend against malware on either device.
Pairing
Section titled “Pairing”The computer always dials. Pairing happens once, by QR:
sequenceDiagram participant PC as Computer participant Phone PC->>PC: Show QR: PC public key + 128-bit one-time secret Phone->>PC: Scan (camera), only while "Add PC" is open PC->>Phone: Noise KXpsk0, secret as the PSK Note over PC,Phone: Proves the PC holds its private key<br/>and the phone saw this QR Phone-->>PC: Phone's public key PC->>PC: "Pair with <phone>?" confirmed on screen PC->>PC: Pin the phone's key under its network name Phone->>Phone: Add the PC's key to the allowlist
- A QR is valid for 120 seconds.
- The secret is spent by the first attempt that proves it. A stranger who got in first is revealed (“This code was already used”). A failed attempt spends nothing.
Reconnecting
Section titled “Reconnecting”Every later link is a Noise IK handshake against the pinned key, with a TAI64N timestamp
that stops replays. The prologue is "Ferry Link v1". Keys are rotated every 2^20 messages
or 1 GiB. Reconnecting never falls back to pairing.
Where keys live
Section titled “Where keys live”| Device | Storage |
|---|---|
| Phone | Wrapped by an AES-GCM key in Android Keystore, excluded from backup |
| Computer | DPAPI (machine scope) in a folder only SYSTEM and Administrators can read |
Before a peer is authenticated
Section titled “Before a peer is authenticated”At most 4 handshakes in progress at once and 1 per source address, a 10-second timeout and messages of at most 512 bytes, all separate from the slots of paired computers. The parsers that run before authentication are fuzzed nightly.
What we rejected, and why
Section titled “What we rejected, and why”| Option | Why not |
|---|---|
| Numeric comparison | Users approve without comparing (“method confusion”) |
The key in the QR with XXpsk |
The key adds nothing there |
| SPAKE2 with a 6-digit code | An unaudited dependency |
| Noise inside QUIC | Unmaintained, and QUIC lost on measurement anyway |
Found a problem? See Contributing for how to report it.