> Source: https://vitna.ai/docs/operations/key-rotation
> Raw Markdown: https://vitna.ai/docs/operations/key-rotation.md
> Corpus index: https://vitna.ai/llms.txt

# Rotating a signing key

Replacing the key that signs customers' policies without refusing a single
running runtime, and what a compromise needs instead.

There is no scheduled rotation. Every rotation of the policy key costs every
operator a restart, so it happens on a compromise, on the personnel change that
implies one, or when the trust set is being edited anyway. `RUNTIME.md` records
that decision, and this page does not reopen it.

## The two keys

| Purpose | Signs | Private half lives in | Read by | Pinned by |
|---|---|---|---|---|
| `record` | Each day's Merkle root | `/etc/vitna/env.attest` | `vitna-attest` | Nobody |
| `policy` | Configs and policies for customers | `/etc/vitna/env.policy` | `vitna-sign` | Every runtime, in `VITNA_PUBLIC_KEY` |

The difference in the last column is the whole of why the policy key is the
hard one. A record key can change on any day: every attestation row stores the
key that signed it, so the record remembers. A runtime only knows what its
operator told it.

What is registered at any moment, with what each key signed, is at
[`GET /api/v1/keys`](../api/v1/verification/keys.md) and on `/witness`.

## A planned rotation, in order

The order is not a preference. Signing with the new key before operators pin it
refuses every deployed runtime until each one catches up.

**1. Make the pair and register the public half.**

```bash
npm run witness:attest -- --new-key
npm run witness:key:register -- --purpose policy --key <public half> --note "incoming, 2026-10-01"
```

`--new-key` prints both halves once and stores neither. Registering publishes
the key and signs nothing with it. A key that has signed the record's roots is
refused here, because the signer would then sign customer policies with the
record's own key. Check it appeared:

```bash
npm run witness:key:register -- --list
curl -s https://vitna.ai/api/v1/keys/policy-key.pub
```

The `.pub` file now carries two keys, comma separated, oldest first.

**2. Operators add the new key beside the old one, and restart.**

```bash
VITNA_PUBLIC_KEY="<old key>,<new key>"
```

`vitna-runtime` 0.1.2 and later accept the set. Both keys verify, so the policy
already on disk keeps loading and nothing is urgent. Tell operators, with the
fingerprint from `/api/v1/keys` so they can check what they pasted, and give
them time. This is the step that costs other people a restart, and nothing here
can tell whether they have done it: a runtime never calls vitna.ai.

**3. Sign with the new key.**

Put the private half in `/etc/vitna/env.policy` as `VITNA_POLICY_SIGNING_KEY`.
`vitna-sign` is a oneshot on a five-minute timer, so its next run reads it. It
checks its own key against the register before signing anything and refuses a
key that is not registered to sign policies, which is what makes step 1
enforceable rather than remembered.

From here every new artifact carries the new key, and `/console/deployment`
prints that key beside each one. Policies already downloaded still verify
against the old key, which is still pinned.

**4. Retire the old key, with a dated reason.**

```bash
npm run witness:key:retire -- --key <old key> --reason "rotated 2026-10-01, replaced by the key registered that day"
```

The reason is public. `/api/v1/keys` serves it to anybody and `/witness` prints
it beside the key, and no command here edits it afterwards, so write what a
stranger may read.

Retiring is a date and a reason, never a delete. Everything the old key signed
stays checkable against it, and `/api/v1/keys` keeps listing it as retired. It
drops out of `policyKey` and out of `policy-key.pub` at once.

Operators drop the old key from `VITNA_PUBLIC_KEY` when they have a policy
signed by the new one, and restart. Not before: a runtime restarted with only
the new key refuses a policy file signed by the old one.

## A compromise

Everything above assumes the old key is still trustworthy while operators catch
up. After a compromise it is not, and the overlap in step 2 is the window an
attacker uses. What changes, and what nothing here does for you.

**Stop signing with it, now.** Remove `VITNA_POLICY_SIGNING_KEY` from
`/etc/vitna/env.policy`. The next `vitna-sign` run refuses to start and signs
nothing, which is the right state until the replacement is ready.

**Retire the old key next, before anything is registered.**

```bash
npm run witness:key:retire -- --key <old key> --reason "compromised 2026-10-01"
```

The order is the point. `policy-key.pub` serves every policy key that is not
retired, so a replacement registered first would sit beside the compromised key
in that file, and `/api/v1/keys` would call the pair a rotation in progress and
say to pin both. Anybody who read the file in that gap would pin the key this
section exists to get rid of. Retiring first has no dependency on the
replacement: the signer already refuses a retired key.

Until the replacement is registered, `policy-key.pub` answers `404`
`no_policy_key` and `/api/v1/keys` says no key is registered to sign policies.
That is the true state, and it is the safe one to be read. Both answers are
cached for a minute and never served stale past it, so a minute after the
retire nobody is handed the old set.

The reason is public, served by `/api/v1/keys` and printed on `/witness`, and
it cannot be edited afterwards. Say that the key was compromised and when, and
keep how it happened, which host, and what is known in the incident record.

**Register and install the replacement without waiting for operators.** Steps 1
and 3 above, back to back. There is no overlap to protect, because an operator
still trusting the old key is exactly the exposure.

Be exact about what retirement does and does not do. It publishes that the key
is out of service. It does not stop a runtime trusting it: that runtime cannot
be told, by design, and a key stops being trusted there only when its operator
removes it from `VITNA_PUBLIC_KEY`. So every operator has to be contacted
directly, with the new key's fingerprint, and told to remove the old key rather
than add the new one beside it.

**Re-signing is not automated.** A signed artifact is an append-only row and is
never rewritten, so replacing an organisation's policy means a new ask answered
by the new key. Today that ask is made per organisation: an owner presses
**Ask for a signed policy** at `/console/deployment`, or an operator writes one
ask per organisation into `aperture.artifact_request` as the owning role. There
is no command that asks for every organisation at once, and one that writes
queue rows in bulk should arrive as its own reviewed change rather than as a
statement typed during an incident. Each operator then downloads the new file,
sets `VITNA_PUBLIC_KEY` to the new key alone, and restarts, in that order.

**What cannot be undone.** A policy the attacker signed with the old key
verifies against the old key forever. The register can say the key was retired
and when; it cannot say which signatures made before that moment were Vitna's.
`aperture.artifact` is the list of what Vitna actually signed, digest by digest,
and a file whose digest is not in that organisation's listing did not come from
the signer.

## If the record key is the one compromised

Nothing pins it, so there is no operator step. Generate a pair, put the private
half in `/etc/vitna/env.attest`, and the next nightly run signs with it; the new
key enters the register the moment it signs a root. Register the old key and
retire it with the reason, since a key known only from attestation rows has no
row to retire until it is registered.

Roots signed with the old key before the compromise stay checkable, because
each was published on its day and a later forgery has to contradict what was
already out. Roots dated inside the compromise window are the ones to treat as
unproven.
