Documentation / Guides

Pairing in detail

This page explains what happens when two devices pair, why the six digits matter and what you can do afterwards. For the steps, see First pairing.

The pairing code #

The code that easysync pair prints is a link. It contains the name of the inviting device, its public key, a way to reach it (addresses on the local network, a relay, or both) and a one-time secret, the capability. The capability is 16 random bytes. It can be used once, for at most three minutes, and it is cancelled as soon as the pairing completes or you cancel it.

Treat the whole link as sensitive until it has expired. If someone else uses it first, they can try to pair with your device; they still need the other person to confirm the six digits, and the pairing does nothing without that.

The link is an ordinary web address that starts with the host of the pairing page. The pairing page is a small static page that only builds a link to the web app or the app from the part of the address after the #. That part is not sent to the server of the page. The page is not trusted with anything else: the secret in the link alone gives nobody a pairing.

What happens #

  1. The joining device connects to the inviting device, directly or through a relay. A relay finds the pairing by a value derived from the capability, not by the capability itself; what a relay can see of this is on What the relay sees.
  2. The two devices start an encrypted connection. The joining device checks that the key it received is the key from the link. If it is not, it stops without revealing its own key or its random value.
  3. The joining device proves that it holds the capability. The proof is tied to this one connection, so it cannot be replayed. Only after a valid proof does the inviting device go on.
  4. Both devices compute the same six digits from the connection, and each device shows them.
  5. Each person compares the digits and confirms or rejects. If both confirm, the devices exchange the secrets they need to find each other and to reconnect later. No long-term secret is sent before both people have confirmed.
  6. Each device stores the other as trusted. The pairing connection is closed. From then on the devices use a new encrypted connection that is set up from the keys they stored.

Why you compare six digits #

An attacker who is in the middle could pair with each device separately and pass messages between them. The comparison of the digits detects that: the two devices would show different digits.

Six digits are only a million possibilities, so the digits are made so that the attacker cannot choose or search for them. One device commits to a random value before it learns the other's value, and reveals it later. The attacker therefore gets a single guess per pairing, a chance of one in a million. For this to hold, a joining device never retries with the same code once the inviting device has proved itself with a valid reply: it asks for a new code.

If the digits differ, answer no and start a new invitation. If they differ again, do not continue and check your network.

After pairing #

  • The two devices recognise each other by their keys. Names and network addresses are only labels. A new name from the other device does not change who it is.
  • easysync peer show <peer> shows the fingerprint of the other device. Compare fingerprints through another channel if you want to be sure of a particular device.
  • If the other device is reinstalled and gets a new identity, the old pairing no longer works. The device that still trusts the old identity is told so and asks you to pair again. It does not fall back to a new pairing by itself.

Revoking a device #

easysync peer revoke <peer>

Revoking is local. This device stops trusting the other one, rejects its connections, cancels the transfers with it, and replaces the secret that your trusted devices use to find this device with a new one, which it passes on to the devices that stay paired. No notice is sent to other devices. The revoked device finds out only when its connection attempts are refused with E_PEER_NOT_TRUSTED, and until then it may still list this device as paired. If you lose a device, revoke it on every device that was paired with it, one by one.