Skip to content

Security and pairing

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.

  • 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-Ferry network 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.
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.

  • 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).
  • 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.

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.

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.

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

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.

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.