do-audit-key-rotate retires the audit subsystem's currently-active Ed25519 signing key and generates a fresh one. From the moment the command finishes, every new daily manifest is signed with the new key; every existing manifest still verifies against the (now-retired) key it was originally signed with.
This is the kind of command you run rarely — but when you need it, you need it. Reasons you might rotate:
Where to run it: Open the Cockpit admin interface and click Tools → Terminal, or SSH to the device. Requires
sudo.
do-audit-key-rotate
That's it. The tool takes no arguments and no flags — it's a single action.
$ sudo do-audit-key-rotate
rotated: retired Y8nM3R9k7p2QwA1xL4, active is now A4kP7w2qN3sLcVrXm9 (at 2026-05-16T18:00:00+00:00)
The output prints the retired key's ID, the new active key's ID, and the timestamp the rotation happened — that timestamp is also what gets recorded in the pubring as the retired key's retired_at and the new key's valid_from.
retired_at is set to the current UTC time. The key's public material is not removed from the pubring — it stays there forever so historical manifests can still be verified./opt/data/auditor/keys/manifest.key (mode 0600, root-owned), replacing the previous active private key on disk./opt/data/auditor/keys/manifest.pubring.json with valid_from = now, retired_at = null.do-audit-manifest (scheduled timer) will sign with the new key.After rotation, the pubring grows by one entry. A device that rotates yearly for ten years will have ten entries in its pubring at year ten — all of them needed if you want to be able to verify any manifest from those ten years.
do-audit-verify looks up the key ID embedded in a manifest's signature block, finds the matching pubring entry, and verifies against that specific key. It doesn't care whether the key is currently active or long-retired — only that its public material is in the ring.
Because the ring entries are never deleted, rotation does not invalidate past evidence. A manifest signed three years ago can still be verified three years from now. The only thing rotation changes is which key signs new manifests going forward.
This is the whole point of the pubring design: rotate freely without losing prior verifiability.
chain-of-custody.json will be signed with the new key — make sure the auditor's verification process (or your documented workflow) accounts for that. In practice this is transparent: do-audit-verify handles it without operator effort.| Exit code | Meaning |
|---|---|
0 |
Rotation succeeded. New active key ID printed. |
1 |
No existing private key at /opt/data/auditor/keys/manifest.key. Run do-audit-keygen first to bootstrap a key, then rotate. (Should not happen in normal operation — the audit-deb postinst bootstraps the key automatically.) |
do-audit-manifest on its systemd timer, typically around 00:00 UTC) will use the new key.