# Key rotation

Purpose
- Rotate signing keys without invalidating historical DSSE proofs.

Principles
- Do not mutate old DSSE envelopes.
- Keep key history; revoke instead of delete.
- Publish key material to trust anchors and mirrors.
- Audit all key lifecycle events.

Key profiles (examples)
- default: SHA256-ED25519
- fips: SHA256-ECDSA-P256
- gost: GOST-R-34.10-2012
- sm2: SM2-P256
- pqc: ML-DSA-65

Rotation workflow
1. Generate a new key in the configured keystore.
2. Add the key to the trust anchor without removing old keys.
3. Run a transition period where both keys verify.
4. Revoke the old key with an effective date.
5. Publish updated key material to attestation feeds or mirrors.

Trust anchors
- Scoped by PURL pattern and allowed predicate types.
- Store allowedKeyIds, revokedKeys, and keyHistory with timestamps.

Verification with key history
- Verify signatures using the key valid at the time of signing.
- Revoked keys remain valid for pre-revocation attestations.

Emergency revocation
- Revoke compromised keys immediately and publish updated anchors.
- Re-issue trust bundles and notify downstream verifiers.

Metrics and alerts
- signer_key_age_days
- signer_keys_active_total
- signer_keys_revoked_total
- signer_rotation_events_total
- signer_verification_key_lookups_total
- Alerts when keys near or exceed maximum age.

Related references
- security/crypto-and-trust.md
- provenance/attestation-workflow.md
- docs/operations/key-rotation-runbook.md