Certificate authority

A team’s shared vault can have its own SSH certificate authority. Its hosts trust the authority, and each member’s device connects with a key of its own that never leaves the device, plus a short-lived certificate that an owner’s device signed for that key. No shared password or key for those hosts has to be kept in the vault, so there is nothing in it for anyone to copy and keep.

Certificates are off until an owner sets them up for a vault.

How it works

1. Owners hold the authority’s key. It is an SSH key kept in another vault that only owners open. Nobody else ever holds it.
2. Each device has its own key. The first time a device needs a certificate in a team, it makes an Ed25519 key for that team. The key stays on the device and is never synced or sent; only its public half is.
3. The device asks. It sends a request for a certificate for that key, signed with the member’s account keys, so nobody can ask in a member’s name.
4. An owner’s device signs. Any owner’s device that is running checks the request against the team’s record (the member is active, may open the vault now, signed with their current keys, asked within the last day, and their role signs in as someone) and only then signs a certificate.
5. The member’s device checks it. It keeps the certificate only when the vault’s authority, as the record names it, signed it for this device’s own key.
6. The host checks it. sshd trusts the authority’s public key, so it lets the member in as one of the user names in the certificate.

An owner’s own device signs its own certificates on the spot, with nobody to wait for.

Set up certificates for a vault (owners)

1. Open Team, then Vaults. On a computer, click the vault: its pane opens on the right. On a phone, each vault is a card with its settings under it; with more than three vaults, open a card’s settings with What it allows.
2. Under Certificates, on the SSH certificates row, choose Set up certificates.
3. Under Keep the authority’s key in, pick a vault only owners open, or A new vault only owners open. A new one is named Owner keys.
4. Under Each certificate lasts, pick 1 hour, 8 hours, 24 hours or 7 days. 24 hours is picked to start with.
5. Under User names each role signs in as, type the account names on the hosts for each role, for example deploy. Separate names with spaces. A role left empty gets no certificate, and at least one role needs a name.
6. Choose Turn on. If your last sign-in was more than 10 minutes ago, Confirm it’s you asks you to sign in again.

On a computer, the vault’s pane then shows On under Certificates, with “Each lasts 24 hours. An owner’s device signs them.”, and the vault’s card in the list is marked Certificates. On a phone, the SSH certificates row says, for example, On, each lasts 24 hours, and the card shows Certificates on. Members who can open the vault see the user names their role signs in as, such as “You sign in as deploy”.

A user name starts with a lowercase letter or an underscore and has up to 32 lowercase letters, digits, dots, dashes or underscores. A role can have up to 16 of them.

Set up the hosts

Each host of the vault has to trust the authority once.

1. In the vault’s pane (on a phone, its card), under Certificates, on the Hosts that trust it row, choose Set up hosts.
2. Check the line Authority key: and its fingerprint.
3. Choose Copy commands, and run them as root on each host of the vault.

The commands:

• add the authority’s public key to the file that sshd’s TrustedUserCAKeys already names, or, when there is none, to /etc/ssh/zestssh_user_ca.pub, with a drop-in /etc/ssh/sshd_config.d/10-zestssh.conf that names it;
• leave any other authority the host trusts in place;
• after a new key, remove the authority’s earlier keys from that file;
• check sshd’s configuration with sshd -t, say so when sshd does not read /etc/ssh/sshd_config.d, and reload sshd with systemctl.

Running them again changes nothing. On a host without systemctl the last command fails: the key is in place, so reload sshd the way that host does.

Connect with a team certificate (members)

The hosts need a key that uses the vault’s certificates. It holds nothing secret, so one such key in the vault serves everyone.

1. On Hosts, pick the vault, so new items go to it: on a computer with the vault button at the top of the page (it says All vaults or a vault’s name), on a phone with the vault chips above the host list.
2. Open Keys and add a key. Under Authentication, choose Team certificate. The option is there only while the key’s vault has certificates on.
3. As the user name, use one of the names the vault’s roles sign in as. The key’s page lists them.
4. Give the vault’s hosts this key.

When you connect, your device uses a certificate it already holds. If it holds none, it asks for one and waits up to 20 seconds for an owner’s device to sign it. Certificates are renewed once half their time has passed, whenever the app syncs.

How long a certificate lasts

• As long as Each certificate lasts says: 1 hour, 8 hours, 24 hours or 7 days.
• It starts 5 minutes before it was signed, for hosts whose clocks run a little behind.
• It never lasts longer than your own access does: when your membership has an end date, or a vault was given to you until a set time (see Access on request), the certificate ends then at the latest.
• A certificate cannot be taken back before it ends. Shorter is safer, but an owner’s device has to be running to sign new ones.

What a certificate carries

• User names: the ones your role signs in as in that vault.
• A key ID that hosts write to their logs: your address and the request’s id, such as priya@example.com (zestssh <request id>).
• Permissions: a terminal always. Port forwarding and agent forwarding only when you may use them in that vault, as its Allowed here setting and your access say, so the hosts hold you to the same.

Certificates-only vaults

A vault is certificates-only when its hosts use a Team certificate key and the vault keeps no password or key for them. There is no switch for it: turning certificates on does not remove or block passwords and keys in the vault, and Password and SSH key stay on offer for its keys. To make a vault certificates-only:

1. Set up certificates and the hosts as above.
2. Give every host in the vault a Team certificate key.
3. Delete the shared passwords and keys from the vault, and remove the matching public keys from the hosts’ authorized_keys.

Who holds the authority’s key

• The key is an Ed25519 key named after the vault, for example “Production certificate authority”, kept in the owners-only vault you picked. That vault’s pane (on a phone, its card) says, under Certificates, Keeps the certificate authority key of and the vault’s name.
• Every owner can open that vault, so every owner’s device can sign once the key has reached it by sync. Admins cannot open owners-only vaults (see Vaults, access and roles).
• A vault that keeps an authority’s key cannot be opened up to everyone.
• Deleting the key asks Delete a certificate authority’s key? first: without it, the vault’s members stop getting in once their certificates end.

Give the authority a new key

When someone who could open the vault that keeps the key no longer can (they left, were suspended or lost that access), or was recovered under new keys after losing their devices, they may still hold the old key. Hosts trust whatever it signs until they stop trusting it. Owners then see New key needed: someone who could open its key no longer can under the vault’s Certificates, and the team’s Overview says, for example, “Production’s certificate authority needs a new key”.

1. Open the vault’s certificate settings: on a computer, Settings in the header of the pane’s Certificates section; on a phone, Certificate settings on the vault’s card. Choose New key, and confirm Give the authority a new key?.
2. Choose Set up hosts again and run the new commands on every host. They add the new key and remove the old one, so certificates the old key signed stop working there.

From then on owners’ devices sign only with the new key, and members get new certificates at their next sync. The old key leaves the vault that keeps it.

Turn certificates off

Open the vault’s certificate settings (Settings in the pane’s Certificates header on a computer, Certificate settings on the card on a phone), choose Turn off, and confirm Turn certificates off for Production?. Owners’ devices stop signing. Certificates already signed work until they end. Turning certificates on again later keeps the same key.

When ZestSSH Cloud cannot carry a request

ZestSSH Cloud normally carries the request to an owner’s device and the certificate back. When it cannot:

1. The member opens the vault (its pane on a computer, its card on a phone) and, on the Certificate from an owner row, chooses Ask. When a connection fails for want of a certificate, its error offers Certificate from an owner too. The member shows the owner the code, or sends the text with Copy as text by whatever still works. Nothing secret is in it.
2. The owner opens the vault the same way and, on the Requests from members row, chooses Sign a request. They paste the text and choose Read it (or scan the code, on a phone), check who asks and for what, and choose Sign and hand back.
3. The member pastes the owner’s answer (or scans the owner’s code, on a phone) and chooses Use it.

The certificate works only on the device that asked. An owner’s device refuses a request that is more than a day old, or that comes from someone who is not an active member or cannot open the vault. When ZestSSH Cloud is not answering, the owner’s device checks the request against what it last had of the team, and changes made since are not in that check.

What ZestSSH Cloud does, and never does

• It never holds the authority’s private key. The key is an item in an owners-only vault, sealed with that vault’s key.
• It never signs. There is no signing service: certificates are signed on owners’ devices only.
• It cannot ask in your name. It checks each request’s signature against the keys the record holds for you, and an owner’s device checks it again.
• It checks what owners hand back. A certificate is taken only when the vault’s authority signed it, for the key asked for, with the user names of the member’s role, no longer than the vault’s lifetime allows, and no longer than the member’s access lasts.
• It keeps requests and certificates for members to fetch. Both are public data. Requests nobody signed are dropped after a day.

Limits

• No early revocation. A certificate works until it ends. Removing someone stops their renewals, and only a new key with the hosts updated stops what the old key signed. ZestSSH does not send revocation lists to hosts.
• An owner’s device has to run. With no owner’s device running, members wait: “Your certificate is waiting for an owner’s device to sign it.”
• One certificate per device. Each device has its own key, so a certificate from one device is no use on another.
• Server monitor never asks. It uses only a certificate the device already holds.
• Ed25519 only. The authority, the device keys and the certificates are all Ed25519.
• Approved devices. Where the team lets in Approved devices only, certificates go only to approved devices (see Approved devices).

When a connection gets no certificate

What the app says	What to do
Your certificate is waiting for an owner’s device to sign it. It is signed when an owner opens ZestSSH; connect again then.	Ask an owner to open ZestSSH, or use Certificate from an owner.
Your role does not sign in to this vault’s hosts. An owner can give it a user name.	An owner adds user names for your role in Certificate settings.
Your role does not sign in as root here. It signs in as deploy.	Change the key’s user name to one your role signs in as.
This key’s vault does not sign certificates now. An owner can turn its certificate authority on.	An owner sets up or turns on certificates for the vault.
You cannot open this key’s vault now.	Ask an owner about your access to the vault.

Next steps

• OpenSSH certificates: certificates you sign with your own CA key, outside a team.
• Vaults, access and roles: roles, access levels and owners-only vaults.
• Team-pinned host keys: trust each host’s key once for the whole team.
• Team recovery: what happens when an owner who held the key loses every device.
• Trash, history and activity: see who connected, when the team records activity.