Team-pinned host keys

Every SSH host proves who it is with its host key. On your own, ZestSSH asks you to trust a new host’s key the first time you connect, and warns you when it changes (see Host key verification). In a team, someone who may edit a vault can check a host’s key once and pin it for everyone in that vault. Every member’s device then trusts exactly that key for the vault’s host, with no prompt of its own, and any other key stops them until someone who may edit the vault checks it.

How a pin works

It is an item of the vault. A pin is kept like the vault’s hosts and keys: sealed with the vault’s key and signed by whoever pinned it. ZestSSH Cloud can neither read a pin nor change one.
Only editors count. Each device takes a pin only from someone who could edit the pin’s vault when they wrote it. A pin from anyone else is ignored.
It counts only in its own vault. A pin is for the hosts of the vault it is in. Another vault’s host at the same address and port is not held to it: that vault pins the address for itself, or its members’ devices decide as they would with no pin.
One pin per host, port and route in each vault. A host reached through a jump host has a pin of its own, apart from the same host reached directly.
An exact match. A pin holds the key the host presented when it was pinned. The host has to present that very key.
Your personal space has none. Pins exist only in teams.

Pin a host’s key

You need Edit in the host’s vault (the Edit and Manage access levels include it; see Vaults, access and roles).

Connect to the host.
The prompt New host key shows the key’s fingerprint, and a box that is ticked to start with: Trust this key for everyone in Production, with the vault’s name. Under it: Their devices then connect to this host without asking, and a different key stops them.
Check the fingerprint against the host itself before you trust it. On the host, ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub prints the fingerprint of its Ed25519 key.
Choose Trust (on a phone, Accept & save). With the box ticked, the key is pinned in the host’s vault for everyone.

Untick the box to trust the key on your device only.

The same box shows in Host key changed, when a host without a pin presents a different key from the one your device trusted. Trusting the new key with the box ticked pins it for everyone.

The box shows only when a prompt does. If Ask before trusting new keys is off, a new host’s key is trusted without a prompt, and nothing is pinned. Only the host you connect to is offered for pinning, not the jump hosts on the way, though a jump host’s own pin, in the jump host’s vault, is used when there is one.

Members who cannot edit the vault get the usual prompt, without the box, until an editor pins the host.

When the key matches

The connection goes ahead without a prompt, whatever Ask before trusting new keys is set to. The Server monitor trusts a pinned key the same way.

When the key is different

The connection stops and the dialog Not the key your team pinned opens. It says that everyone in the vault trusts another key for that host, that the host’s key may have been replaced on purpose or someone may be in the way, and that nobody connects with this key until someone checks it. It shows Pinned for the team beside Received now, and a command to run on the host to print its own fingerprint.

What you can do depends on your access to the pin’s vault:

You may edit it: you can choose Replace the team’s key. Check the key on the host first: replacing it changes it for everyone in the vault.
You may not: the only choice is Cancel and disconnect. Someone who may edit the vault checks the key on the host itself and replaces the team’s pin.

A run with nobody at the screen (an automation’s task) asks nothing: a different key stops it, and so does a new host’s key. The Server monitor refuses a different key and never changes a pin.

Replace a pin (editors)

Connect. Not the key your team pinned opens.
On the host itself (its console, or a session you already trust), print its fingerprint with the command the dialog shows, and compare it with Received now.
If they match, choose Replace the team’s key. Otherwise choose Cancel and disconnect and find out why the key changed.

Everyone else who can open the vault is told, for example “The key of web-01.example.com:22 changed in Example Ops”, with “alex@example.com replaced the host key your team trusts. Your devices use the new key from now on.”

See or remove a pin

On a computer, select the host on Hosts. Under Host key, its panel shows each pin of the host’s vault for that address: Pinned for everyone in Production and Every device in the team trusts only this key here., with the type and SHA256 fingerprint of the pinned key. Where a pin is for connections through a jump host, it says so, for example For connections through the jump host bastion.example.com:22., and the pin for direct connections beside it says For direct connections, not through a jump host.

To remove the pin you need Delete in its vault:

Choose Remove the team’s pin.
Confirm Remove the team’s pin for this host?. It says that everyone in the vault is told.

Each device then decides on its own again for that host, as it does for any host without a pin. Everyone else who can open the vault is told, for example “web-01.example.com:22 is no longer pinned in Example Ops”, with “Your devices ask again before trusting this host’s key.”

What members are told

A pin replaced with another key, and who replaced it.
A pin removed.

You are not told of your own changes. A device that looks at the pins for the first time notes where they stand and tells its person nothing.

Limits

Pinning and replacing need Edit; removing needs Delete. Adding items alone is not enough to pin.
One key per pin. A pin holds the single key the host presented.
The pin’s panel is on computers. The host panel that shows a pin is on the computer’s Hosts page. Phones use pins when they connect, and offer to pin a new host, but do not show a pin or remove one.
A vault’s pins are its own. A pin made in one vault never counts for another vault’s hosts, even at the same address. Move a host to another vault and that vault’s pins are the ones its connections go by.
A pin outlives its author’s access. Each device judges a pin by what its author could do when they wrote it, so a pin stays after its author loses access. An editor replaces or removes it if it should go.

Next steps

Host key verification: how ZestSSH checks host keys on each device.
Certificate authority: short-lived certificates for members instead of shared keys.
Trash, history and activity: earlier versions of the vault’s items, pins included.
Setting up jump hosts: how routes through jump hosts work.