Pair your phone

Pairing lets a machine send your phone alerts and accept answers from its Lock Screen and Watch. It needs the helper on the machine and the app on the phone. Terminals and sessions work without it.

Pair#

Add the machine in the app and connect to it over SSH. If the helper is installed, the app pairs over that SSH connection. There is no code to type and no new port to open.

During pairing the phone sends the helper its device id, a name, its push tokens, the relay URL, two public keys and the public half of its SSH key. The helper answers with its host id and its own public key. An Apple Watch pairs through your phone and registers its own approval key.

Keys that are created#

  • On the phone, an X25519 key. The helper uses its public half to seal every push so only that phone can open it.
  • On the phone, an Ed25519 approval key. The helper uses its public half to check the signature on each answer sent through the relay.
  • On the machine, an X25519 key and a mailbox secret, created the first time you pair. The phone seals answers to the public half. The host id is derived from the secret, and the secret authorises the helper's connection to its relay mailbox.

The machine keeps its keys and the list of paired devices in keys/ under its Togo home, readable only by your user. Private keys never leave the device that made them.

The SSH key that logs you in is separate. It stays on the phone, in the Secure Enclave or the device-only Keychain.

See and revoke devices#

List the devices paired with a machine:

$ togo devices ls

Revoke one by its device id:

$ togo devices revoke <deviceId>

A revoked device stops getting pushes, and the helper refuses any answer it sends afterwards. The command also tries to remove that device's key line from ~/.ssh/authorized_keys and prints what it did. If it did not remove the line, delete it yourself.

Pairing the same device id again replaces its record. If you lose a phone, revoke it on every machine it was paired with.