Key Rotation Procedure
Implements: Cryptography Policy Section 4 (Key Management) Owner: Cryptography Specialist Last Updated: 21 May 2026 Next Review: 21 November 2026
Key Inventory
| Key Type | Location | Rotation Schedule | Impact of Rotation |
|---|---|---|---|
| Issuer signing key (RedJubjub) | Cloudflare Workers Secret (provii-issuer) | Annual or on compromise | All existing credentials invalidated, users must re-issue |
| Verifier HMAC keys | Cloudflare Workers Secret (provii-verifier) | 90 days (recommended) | Existing HMAC signatures become invalid; verifiers must update |
| API keys (customer) | Cloudflare KV (provii-management) | Customer-managed; 90-day recommendation | Old key stops working; customer updates integration |
| JWKS public keys | Cloudflare KV (public endpoint) | Updated when signing key rotates | Verifiers fetch new keys from JWKS endpoint |
| Cloudflare API token | Cloudflare Dashboard | Annual | CI/CD must be updated with new token |
| GitHub Actions secrets | GitHub Settings > Secrets | When Cloudflare token rotates | CI workflows use new token |
DOCS_SESSION_HMAC_KEY (docs interactive sandbox session cookie HMAC) | Cloudflare Secrets Store (internal binding; ID maintained internally) | Planned 90 days. The rotation runbook and the kid-header flow are planned work. Current deployment is single-kid per the docs session layer at demo-web-provii-agegate/src/docs/session.ts. | Until the dual-kid flow lands, rotation invalidates all active docs-session bearers in flight. The planned kid prefix on the bearer and dual-key acceptance will let rotation proceed without invalidating in-flight sessions. Rotation runbook entry is tracked at operations/key-rotation-plan.md. |
Issuer Signing Key Rotation
This is the most impactful rotation. All existing user credentials become invalid.
Pre-Rotation
- Communicate: Notify all known issuers and verifiers at least 30 days in advance
- Plan downtime window: Coordinate with customers for minimal impact
Rotation
- Generate new RedJubjub keypair
- Update the provii-issuer secret:
wrangler secret put SIGNING_KEY --env production - Update the JWKS endpoint with the new public key (add new key, keep old key for a transition period)
- Deploy provii-issuer
Post-Rotation
- Monitor for errors (users with old credentials will fail verification)
- After transition period (e.g., 7 days), remove old public key from JWKS
- Document rotation in change log
Customer API Key Rotation
- Customer requests new key via Admin Portal or contacts support
- Generate new API key in provii-management
- Provide new key to customer via secure channel
- Customer updates their integration
- Customer confirms new key works
- Revoke old key
Cloudflare API Token Rotation
- Generate new token in Cloudflare Dashboard with same permissions
- Update GitHub Actions secrets in all repositories that use the token:
gh secret set CLOUDFLARE_API_TOKEN --body "new-token-value" --repo provii/REPO_NAME - Verify CI/CD works by triggering a test deployment
- Revoke old token in Cloudflare Dashboard
Emergency Key Rotation (Compromise)
If a key is suspected compromised:
- Rotate immediately. Do not wait for a maintenance window
- Revoke the old key
- Assess impact: What could an attacker do with the compromised key?
- Notify affected parties per incident response playbook
- Review logs for any unauthorized use of the compromised key
- Document as a P1/P2 incident