Skip to content
downpipes docs

Rotating your keys: what to expect

There are three different things people mean by changing their keys, and they have different consequences for what still verifies, what still opens, and what you have to keep. This page sets out each one, what the console shows you before you commit to it, and what to do afterwards, so a key change is a deliberate step with no surprises. It is written for a self-hoster who has already run the key ceremony and now needs to rotate the break-glass key, add an operational key, or re-key from scratch.

The reassuring frame first. None of these changes can lose the data you already have. Every archive stays recoverable by the key that sealed it, so the whole subject of this page is which key opens which archive after a change, never whether an archive is still recoverable at all.

Three different key changes

The change What it touches What still verifies and opens What you keep
Rotate the break-glass key The break-glass key only. Your signer and any operational key are unchanged. Every existing run still verifies under your unchanged signer. Archives sealed before the rotation open with the old identity.key; archives sealed after open with the new one. The old identity.key, for as long as the old archives matter.
Add an operational key (from offline-key-only) The operational key only. Your signer and break-glass key are unchanged. Every existing run still verifies, and every archive stays recoverable with your break-glass key exactly as before. The new operational key lets your engine read new runs back in place. Nothing new. There is no new identity.key to save. This is not a re-key.
Full re-key ceremony The signer and the break-glass key together. A new signer and a new break-glass pair. Runs signed by your previous signer stop verifying through this console; you verify those with the offline reader and the old signer.pub. Archives sealed before it open with the old identity.key. The new identity.key offline, plus the old identity.key and old signer.pub for the old archives.

The rest of this page takes each one in turn.

What you see before you commit

A re-key cannot happen silently. The engine refuses to replace an existing signer unless you confirm the re-key, so an install that would overwrite your signer without that confirmation is turned away rather than applied. That refusal is the guarantee you can lean on: you cannot rotate your signer by pressing through a default, because the confirmation is enforced at the engine, not merely asked for in the console.

When the console offers the re-key path, it states the consequence before the generate control, in these words: a new key set reissues your signer and your break-glass key, every run signed by your current signer then stops verifying through this console, and you verify those earlier runs with the offline reader and the matching old signer.pub instead. You also get a new identity.key to save offline. The card says plainly that most returning owners do not want to re-key.

On an offline-key-only estate, the default card is “Add an operational key”, not the re-key ceremony. The full re-key sits behind a collapsed “Advanced: run the full re-key ceremony instead” option, and choosing it warns you, before you proceed, that specific older runs stop opening through this console afterwards.

The confirmation is enforced, not assumed

Because the engine is the one refusing an unconfirmed re-key, the safeguard holds regardless of which card the console shows you. The console also shows your current posture as two-recipient or break-glass-only, so you can see which key set a change would touch before you touch it.

Rotating the break-glass key: two vintages

Rotating the break-glass key generates a new break-glass pair in your browser, offers the new private key to you as a local download, and applies only the new public key to your engine with a one-shot token. Your signer and any operational key are untouched, so every run you already have still verifies.

What the rotation does create is two vintages of archive. Runs sealed before the rotation are wrapped to the old break-glass key; runs sealed after are wrapped to the new one. The old identity.key opens the old vintage and the new identity.key opens the new one, and neither opens the other’s. The Rotate tab states this directly: archives sealed before this rotation can only be opened by the old identity.key, so keep it.

The Rotate tab also lists the vintages themselves, under “Which key opens which vintage”. Your engine reads each completed run’s signed manifest back without any private key and reports the public fingerprint of the key that run is wrapped to, how many runs each key holds, whether your engine still has that key, and how many runs are stranded to a key it no longer has. It reports the signature side separately, because a signer change stops old receipts verifying even while every archive is still openable.

Two readings on that panel are deliberately not all-clears. If your run history could not be read, the panel says so and states that its counts are not a verdict. If the pass stopped short of your oldest runs, it says that too. In both cases the honest conclusion is that nothing older has been checked, not that nothing older is stranded.

Keep your own record too

The panel tells you which keys your archives need; it cannot tell you where you put those files. Your recovery sheet is where that lives: note the public fingerprint of the retiring key beside the new one, and the run index at which the new key took over, so a future recovery knows which identity.key to reach for. Retain the old key and the old sheet for as long as those old archives matter.

Adding an operational key is not a re-key

If you started in the offline-key-only posture and later want your engine to read its own backups back (to run scheduled restore tests, the canary and in-console restore without a person present), you add an operational key. This installs only the operational pair. It does not touch your signer and it does not touch your break-glass key, so it is not a rotation of either.

The card states four facts before you apply. Archives sealed before you add this key stay recoverable with your break-glass identity.key only, forever. Your signer is unchanged, so verification of your existing runs keeps working through this console exactly as before. No new identity.key is needed, because your break-glass key is unchanged. Drills, scheduled restore tests, the canary and in-console restore resume automatically on their next run.

There is one consequence worth stating plainly, because it looks like a failure and is not. A backup taken before you added the operational key still verifies under your unchanged signer, but your engine cannot read that older run back in place with the new operational key, because that run was never wrapped to it. Its break-glass recoverability is exactly what it was. The switch on to in-place read-back applies to runs sealed from the change onward, not retroactively.

First install is not a rotation

The very first key ceremony is a starting point, not a rotation, so it behaves differently from everything above. It generates your keys in the browser, and your break-glass private key is downloaded to you before the single irreversible install step and never travels in it, which is what keeps recovery yours alone. The ceremony forks by posture: it mints an operational key alongside a break-glass key, or a break-glass key only. Everything on this page is what you do to those keys later. To choose the posture your first install sets, see choosing your key posture.

Where this fits

Last updated .