Keys, rotating and resetting

Which keys there are #

Each device has its own keys. Its WireGuard and sealing keys protect its tunnels and the messages sealed to it. Its identity key identifies it in the membership log.

The network also has a group secret, which all members share and use to find each other. Admin keys belong to people and approve changes (Several admins).

Replacing keys is called rotating them. A new key is a change to the log, so the admins approve it like any other.

Rotating keys #

Use juist rotate to give new keys to a device you still trust. If the device holds an admin key of the network and the quorum needs only one vote, the change takes effect immediately:

$ juist rotate
new keys cfe695661243
new keys live
rotated this device's keys

If the change needs another admin, it waits for their approval, and the new keys stay staged until the log contains them. juist rotate abandon drops a rotation that is still waiting for approval.

Connections keep running while the device switches to its new keys. A device that runs a relay restarts its tunnels instead.

juist rotate identity changes the device’s IPv6 address, which ends the connections that used the old one. It needs the network at schema 19; below it, it stops with juist: the network predates rotating an identity key until an admin runs juist log upgrade (Updating juist).

Starting a device over #

juist reset takes a device out of the network and leaves it as if freshly installed. It forgets the network along with everything it kept for it: its keys, log, peers and operator. Admin keys are kept. In this example, phone had already been removed from the network:

$ juist reset
forget "home" and reset this device, with new keys? [y/N] y
reset; new keys, no network

If your keystore holds admin keys, it adds the line admin keys kept in ~/.config/juist/admins, with the full path.

If the network still lists the device, juist reset needs --force. Where you can, remove the device from an admin’s device first, so that the other devices stop trusting it too.

On a device in several networks, only the network you name is forgotten: juist reset work --force. Its juistd is removed too, unless it is the first network’s. The other networks keep their keys.

When a device is lost #

juist remove phone

juist admins remove nid:…

A replacement device joins with a new invite, like any new device (Invites). If the old device turns up again, its juist status says removed. Join it again with a new invite, or run juist reset on it.

Backing up admin keys #

An admin key exists only in the keystore of the machine it was created on. To keep a copy in a password manager, print it as a single line and pipe it there. juist admins lists the keys on this machine under KEY HERE:

juist admins export alice@home | pass insert -m juist/alice

To restore it on any machine, pipe the line back in:

$ pass show juist/alice | juist admins import alice@home
imported admin key "alice@home"
it casts 1 vote in "home"

The line always goes through a pipe, never onto the command line. Its checksum refuses a truncated line. It also covers the key’s quantum-safe signing key, which derives from it. An import never replaces an existing key. If the key was removed from the network since the backup, the import warns "home" gives it no vote.

Keep the break-glass line that juist create showed the same way, but separately from the admin keys (Ending the network).

A device’s own keys cannot be exported: a copy on another machine would be a second device under the first one’s name. Instead, remove a lost device and invite a new one.

Good to know #

• Only root and the device’s operator can rotate, reset and remove. Approving takes an admin key.
• juist reset warns when this device is the only one in the network, since the network ends with it.
• juist log shows every rotation and who approved it.

Why juist accepts this is explained under trade-offs.

Troubleshooting #