Managing devices and keys

Each device has its own key, and one device, the home device, manages the others. Devices and keys explains why; this page is the reference for doing it.

Where

Settings ▸ Sync & Devices ▸ Device Keys shows this device’s name and id, Require Face ID to Open (Touch ID, or the passcode, on devices without Face ID), and Devices, the device list. On the Mac, View ▸ Vault Keys (⌥⌘K) opens the same list in a window.

The list shows:

• Devices: each with its name, This Device, Manages devices on the home device, when and by whom it was added, and when it last synced. On the home device, touch and hold a device (secondary-click on the Mac) for Rename…, Make Home… and Remove…, and Add Device… is at the end of the list. Elsewhere, the footer names the device that manages devices.
• Recovery Kit: when the current kit was made, whether a Passphrase Copy is in the vault, and on the home device Replace Recovery Kit… and Re-encrypt Everything…; on other devices Take Over with Recovery Kit….
• History: every device change, such as “Old Mac removed by iPad” or a takeover, with its date.
• Repair: files from before a device change, and device lists a sync could not check (below).

Before any change, the home device syncs with each of the vault’s targets for up to ten seconds, so the change includes what others uploaded. Skip the Rest goes ahead at once; the targets it did not reach are named afterward, and the devices that wrote there catch up by themselves.

Add a device

On the new device, open the vault and choose Join This Device…; on the home device, Add Device… and type the six words the new device shows. The full steps: Add a second device. Adding a device rewrites no file.

Rename

Rename… on the home device. Names are stored unencrypted in vault.json, so the storage can read them (it cannot change them). Keep them plain, like “iPad” or “Work Mac”.

Remove a device

Remove… on the home device opens a sheet that says:

• when the device last synced. Changes it made since then and did not sync stay on it;
• that it can still reach your storage, and what to change: the password of a WebDAV target, or its iCloud sign-in. Sempere cannot take storage access away;
• with Lost or Stolen on, the devices it approved while it managed devices, checked so they go too, and whether it made the current recovery kit.

Tap Remove. The vault gets a new key at once. Notes from before stay readable to the removed device (it already had them); nothing written after reaches it. When the removed device next syncs, it learns it was removed and stops writing (below). If it made the current recovery kit, replace the kit too.

Make another device home

Make Home… on the home device, for example before you retire it. From then on only that device can add, rename and remove devices and replace the recovery kit. The vault gets a new key.

Removing a vault from the home device (Delete from This Device… on the welcome screen) warns about this and offers Open to Make Another Device Home first; otherwise only the recovery kit can manage devices afterward.

Replace the recovery kit

Replace Recovery Kit… on the home device: confirm with Face ID, Touch ID or your passcode, then Keep or Remove each listed device (devices added by a takeover since the current kit are marked), print or save the new kit, and type one line of its key back. You can add a passphrase copy of the new key (any old copy is deleted) and, if you still have it, the old kit’s key as a record that its holder agreed. The vault gets a new key, and from then on no device that has seen the change accepts a takeover with the old kit.

Files written before still open with the old kit, through old copies of the vault. If that matters, re-encrypt instead.

Re-encrypt everything

Re-encrypt Everything… on the home device is for when nothing in the vault should open with an old key any more: the kit was lost, or a removed device’s key must not open even old files. It makes a new vault key and a new recovery kit (the same steps as Replace Recovery Kit), then encrypts every file again. Every sync target must be reachable to start.

The progress sheet shows this device’s files and each target. Continue goes on; Stop pauses, and nothing done is lost. Other devices follow when they sync. Once it finishes, the old kit and removed devices’ keys open nothing in the vault or on its targets. It does not reach your backups, a provider’s version history, or copies made elsewhere.

Take over with the recovery kit

When the home device is lost, stolen or broken: Take Over with Recovery Kit… on another device (in the device list, or on the unlock screen of a device with no key for the vault).

1. Scan the kit’s two QR codes, or type the key and the 16 groups of the root printed under it. Or type the passphrase of the vault’s passphrase copy. A device that has opened the vault before does not need the root.
2. Continue. Under Keep these devices, uncheck any device you no longer have. If a stolen home device made changes after this device’s last check, they are listed under The takeover undoes.
3. Take Over. This device manages devices from now on. The recovery key is used for this one signature and is not kept.

Every other device shows an alert about the takeover. A takeover keeps the current kit; replace it afterward if someone else may have it.

When a device is removed

A device that finds it is not on the newest device list shows Not on the Device List: who made the change and when, how many of its changes no other device or target has, and:

• Save Files…: copies those changes, encrypted, to a folder;
• Export Those Notes… or Export All Notes…: readable copies;
• Remove from This Device…: deletes this device’s copy of the vault.

It writes nothing more to the vault. If the removal was a mistake (for example made by a stolen home device), a takeover with the kit that keeps this device undoes it, and the device carries on by itself.

Repair

• From Before a Device Change: files under an earlier key that no device change accounts for, for example written by a removed device after its removal. They are never read as notes and never deleted unless you do it. Touch and hold one for Export…, Keep in Vault… (added again under the current key; keep only what you recognize) and Delete from This Device. Clear Superseded removes those the vault already holds with the same content.
• Device Lists Not Taken: device lists a sync met that this device could not check yet. Anyone who can write to a sync target can leave an unchecked one. Forget Unchecked Lists forgets those; Forget All… also the checked ones, after a warning.

A banner on the note list says when sync has been held back for more than a day by such a list, when another device took over, or when the device list was changed in two places at once.

This device’s key

A device’s key for a vault is deleted with the vault (Delete from This Device…). If the key can no longer be read (for example after Face ID was set up again with Require Face ID to Open on), the unlock screen offers Forget This Device’s Key…; the device then joins again or takes over.

With the CLI

The CLI is a device too, with its own key in ~/.local/state/sempere/devices/.

sempere devices list                         # devices, the recovery kit, join requests
sempere device init --name "linux box"       # on a new machine: ask to join, prints six words
sempere devices approve WORD WORD WORD WORD WORD WORD    # on home; prints six words back
sempere device confirm WORD WORD WORD WORD WORD WORD     # on the new machine
sempere devices rename ID "Work Mac"
sempere devices remove ID
sempere devices handoff ID
sempere devices takeover --recovery-key key.txt --root "THE 16 GROUPS"     # shows the devices to keep
sempere recovery replace --recovery-out new-recovery.txt --keep ID --yes
sempere vault reencrypt --recovery-out new-recovery.txt --keep ID --yes    # then --resume until done
sempere devices history
sempere devices status                       # this machine: listed, waiting or removed
sempere set-aside list

Each takes --vault (or SEMPERE_VAULT). The full reference is in docs/cli.md.