SSH key rotation

Rotating Linux and SSH credentials says plainly that an ssh_key credential on a Linux target does not rotate — only the password type does, because writing a new public key into authorized_keys and removing the old one is exactly the kind of change that locks you out of a machine with no fallback if it goes wrong. That gap is closed for one specific case: the linux_ssh_key engine, which rotates an ed25519 key pair the way it needs to be done to be safe.

How it proves itself before it removes anything

The sequence is deliberately ordered so that nothing which already works is ever removed before its replacement has been shown to work:

1. 1

   Generate a fresh ed25519 key pair

   Qorionix generates the key. You never choose it and no route returns the private key to a person.

2. 2

   Append the new public key to authorized_keys, authenticated with the OLD key

   The engine signs in using the key currently in the vault — the one about to be retired — and adds the new public key as an additional line. At this point both keys work.

3. 3

   Open a fresh connection with the NEW key, to prove it actually works

   A separate SSH connection, authenticating with only the new private key. If this fails, the rotation stops here: the old key is left in place, untouched, and nothing about the account has become less accessible than it was before you started.

4. 4

   Only then remove the old key's line from authorized_keys

   The new key has been proven to open the account on its own. Removing the old line is now safe to attempt.

If removing the old key fails, that is a partial success — not a failure

The step most likely to go wrong is the last one: a permission problem, a transient connection drop, or an authorized_keys file that changed underneath the rotation. If that step fails after the new key has already been proven to work, the engine does not report the whole rotation as failed. It returns a *rotation.PartialRotationError: the new secret is live and stored in the vault, the account is reachable, and the old key's line is still sitting in authorized_keys, unretired.

If you see a partial-rotation result: the credential in the vault is the one that works, so there is no urgency about access. Sign in with the new key, remove the old public key's line from authorized_keys by hand, and re-run the rotation (or leave it — the old key is inert once it is gone from that file, whether Qorionix removed it or you did).

What to do next

1. Rotate one non-critical account's SSH key first and read the result, the same way you would with a password rotation.
2. Read Rotating Linux and SSH credentials for what still does not rotate on Linux, and why.
3. See the full adapter catalogue for every platform this release can rotate.