Connecting a phone

Connecting puts a phone and a computer on the same signed device list, called the roster. It is the only way a phone gets onto a computer’s list, and it is built so that a stranger who sees the QR code, or who sits between the two devices, can’t end up connected.

The steps for you are in Connect your phone. This page is what happens underneath.

The pieces

• The QR code. The computer shows it. It holds the computer’s key, its address (its relay address if it uses one, and its IP addresses on the network), a one-time secret of 16 random bytes, and the time it expires. It works for 10 minutes and once. Treat it like a password while it is on the screen. You can paste its text instead of scanning it (“Paste the code” on the phone), which is how you connect a computer you reach over SSH.
• The connection door. A computer accepts connection attempts only while a QR code is showing. At most 4 connections are open at once, each one is closed after 150 seconds, and the whole connection must finish within 2 minutes. Five wrong attempts burn the code.
• The check code. Eight characters such as ABCD EFGH. Each device computes it itself from both devices’ keys and the QR code’s secret. It is never sent over the network and never logged.
• The roster. The list of your devices with their names, keys and kinds. The phone signs it with its device key, and each new version is chained to the one before by a hash. A computer talks only to devices on its roster.

The steps

1. The computer shows a QR code. From a terminal that is tealhand-host connect. This opens the connection door.
2. The phone scans it (or you paste its text). The phone reads the code strictly and connects to the computer by the key in the code, and to no other key. Connecting works on the same network in M1. Once connected, control also works through a relay.
3. The phone proves it knows the secret. Its first message carries a proof made with the secret over both devices’ keys, its name and its two public hardware keys. It also asks for your fingerprint or PIN: both of its hardware keys sign a proof that they belong to this connection.
4. The computer answers with its own proof, plus its name and its operating system. Neither side has trusted the other yet; each has shown it saw the QR code.
5. Both screens show the check code. The phone shows it with the computer’s name. The computer shows it with the phone’s name. If the codes are the same, nobody sits in between.
6. You tap “Yes, connect” on the phone. The phone signs the roster and sends it to the computer. The computer keeps nothing yet.
7. You click on the computer too. The computer shows the phone’s name and the check code and waits. In a terminal that is Connect? [y/N]. Only y connects. Nothing is stored before this click. It stops someone who photographed the QR code from connecting their own phone.
8. Done. The computer stores the roster and answers. The phone stores it too.

Both sides can say no. If you tap “They don’t match” or answer n, nothing was changed.

The first roster

For a first connection, the phone makes version 1: the phone as the owner, plus the computer. The roster lists each device’s key, name, kind (phone or computer), the phone’s device and presence public keys, when it was added and when it expires.

The computer accepts a first roster only through a connection you clicked on, and only if it lists the computer’s own key and its owner is the key the phone announced. A computer belongs to one owner. If it was connected to another phone, it refuses until you forget that phone (Lost or stolen phone).

Connecting a second computer makes version 2: the same owner and devices, plus the new computer, chained to version 1. Later changes (a rename, a removal) make later versions.

After connecting

• The phone sends the new roster to every computer it knows over ctl/1, and uploads it to your relay if you use one, on every start, reconnect and change. A computer that is offline gets it when it is back.
• A roster the phone pushes later can remove, rename or expire devices and add computers. It can’t add a phone, or change the keys of a device already listed. A new phone comes in only through connecting and a click at the computer, so a thief with an unlocked phone can’t enrol their own key.
• When a new roster no longer lists a computer, that computer forgets its saved connection and its rules.

Why it holds

Attack	What stops it
A stranger photographs or sees the QR code	The computer waits for your click. Without it nothing is stored
Someone swaps the QR code for their own	The phone talks only to the key in the code, and both proofs depend on the secret in it. At worst the connection fails
Someone sits between the phone and the computer	The check codes differ. You tap “They don’t match” and nothing is connected
A second phone tries to take over a connected computer	The computer belongs to one owner and refuses a second one

The proofs and the byte-level details are on How commands are signed. The phone reads the QR code with open-source code on the phone. No camera picture leaves it.