Certificate authorities

A certificate authority (CA) signs certificates that hosts trust. Your Burrow runs its own CAs for SSH user certificates: a machine fetches a certificate from an SSH user dynamic secret, the secret's CA signs it, and every host the CA is attached to accepts it for SSH logins until it expires.

A CA's signing keys are made in your Burrow and stay there, sealed under its master key like your secrets' values. Hosts trust a CA through their node: your Burrow sends each node the keys of the CAs attached to it and the certificates they revoked, and the node sets up its host's sshd with them.

Create a certificate authority#

1. Open Certificate authorities and select the + at the top right of the table.

2. Name the CA. A name is lowercase letters, digits and hyphens, starting with a letter, up to 64 characters, and spaces turn into hyphens as you type.

3. Pick the nodes whose hosts are to trust it. A CA needs at least one.

4. Set its key rotation, described below, and select Create.

The dialog turns into the new CA's details, its trust anchor among them. Its first signing key is an Ed25519 key.

Without read and write on Nodes, the dialog says so in place of the form. With no nodes yet, it offers Add node, which opens the Nodes page's own dialog, or Go to Nodes when a node token is out and no node has registered with it yet.

Key rotation#

A CA's signing key is replaced by a handover: the new key is trusted on your hosts before it signs anything, and the key it replaces stays trusted until everything it signed has expired, so a rotation leaves every certificate working.

A new CA rotates by hand and switches to a new key 48 hours after it's prepared. Change either later with Rotation settings from the CA's row menu. A key already waiting follows the new switch setting, counted from when it was prepared.

Rotate, switch and replace keys#

The CA's row menu carries what fits where its rotation stands:

Details#

The table shows each CA's signing key fingerprint, where its rotation stands, and when it was made, with a tag beside its name counting the secrets that issue from it. Details in its row menu shows the rest, and follows changes as they happen:

• Its status, what it signs, its key algorithm, and where your Burrow's master key is kept.

• Its rotation: how often, what comes next, and when a new key switches.

• Every signing key, newest first, with its fingerprint and state: Signing, New, Retiring, Replaced or Removed.

• Its nodes, and where each host stands with it: On its host, Waiting while the node is offline or the change is on its way, or Failed, with the node's reason.

• Its trust anchor: the lines a host's TrustedUserCAKeys file holds to trust it, with a copy button.

• The secrets that issue from it, by project, environment and name, or how many to a member who can't read secrets.

Nodes#

A CA is trusted on the hosts of the nodes it's attached to. Change them in its details: pick or clear nodes, then select Save. Attaching a node puts the CA on its host, and detaching takes it off. Removing a node detaches it from its CAs.

A member without read and write on Nodes sees a CA's nodes greyed, and a member who can't read nodes sees how many there are.

On the host#

Each node is sent the keys and revocations of its CAs when it connects and whenever one of them changes, and every ten minutes it checks its host again and puts back anything that went missing. On the host it works with what's there:

• When sshd already trusts a CA file, the node keeps its keys in a marked section of that file. The keys already in it, and any added later, stay as they are.

• When sshd trusts none, the node keeps its own file in /etc/ssh/ratel-node and points sshd at it from a marked section at the top of sshd_config. The change is checked with sshd -t first and sshd is reloaded after; if sshd won't reload, sshd_config is put back as it was.

• Revocations go into the host's own revocation list when it has one, added with ssh-keygen to a binary list or as a marked section of keys in a plain-text one. Without one, the node keeps its own.

Every file is written whole and renamed into place. After the first time, a new CA, a rotation or a revocation only rewrites files, which sshd reads at its next login. SSH sessions still open with a revoked certificate are ended, as described in Dynamic secrets.

SSH trust is set up on Linux hosts with OpenSSH, by ratel-node 0.2.0 and later. Ending revoked sessions takes ratel-node 0.2.1.

Disable, delete and restore#

Audit log#

Every change to a CA is recorded in your audit log, and each event can be sent to a webhook.