Certificate rotation¶

There are two rotations to consider:

1. Agent client certificates — the leaves issued to each agent.
2. CA signing keys — the keys that sign those leaves.

Both can be done without agent downtime if you follow the procedure below.

Agent client certificates¶

Automatic renewal¶

When an agent's leaf cert is within RenewalThresholdDays of expiry (default 30) the server signals ConnectionSettings containing a fresh cert + key on the next agent connect. The agent rotates in place — no rebootstrap.

Required:

• Agent has signalled AcceptsConnectionSettings.
• The active CA signing key is healthy and able to issue.

Most operators never have to think about this.

Manual revocation + reissue¶

Use this when a cert is compromised or when an agent host is replaced:

1. Settings → Identities → find the agent → Revoke.
2. The revocation lands in the CRL within nextUpdate (≤ 15 minutes) and in the OCSP responder immediately.
3. Issue a new bootstrap token for that agent.
4. Drop the new token into the agent's config.
5. Agent reconnects, redeems the token, gets a fresh cert.

Old cert validation fails as soon as the next OCSP/CRL check runs.

CA signing-key rotation¶

The persisted CA's signing key has the lifecycle:

Draft → Active → Trusted → Retired

Active is what new certs are signed by. Trusted is what previously issued certs still validate against. Retired drops out of the trust bundle.

Standard rotation procedure¶

1. Settings → PKI → Signing keys → Create new key.
2. Pick the algorithm and size (RSA 3072 or ECDSA P-256).

3. The new key lands in Draft.

4. Activate the new key.

5. The previous active becomes Trusted with TrustedUntilUtc = now + DefaultTrustedWindow (default 30 days).

6. All new agent certs are now signed by the new key.

7. Wait for one trust window.

8. Agents whose leaves were signed by the previous-active key still validate during this window.

9. Agents that auto-renew during this window get a leaf signed by the new key.

10. Retire the previous-active key after the window.

11. It drops out of the trust bundle.
12. Any agent whose leaf is still signed by the retired key will fail to validate next reconnect — re-bootstrap them.

The Trusted window default of 30 days handles the long tail of agents that connect rarely (edge devices, scale-down at off hours).

Emergency rotation¶

If the active key is compromised:

1. Create a new key, activate it (steps 1-2 above).
2. Immediately retire the previous-active. Its leaves stop validating now.
3. Re-bootstrap every agent. Use a token pool to make this manageable.

This is a fleet outage. Plan for re-bootstrap automation before you need it.

Importing an existing key¶

If you operate a corporate PKI and want Ampora's CA to be a sub-CA:

1. Generate a CSR via the API:

   curl -fsS -X POST "https://AMPORA_HOST/pki/signing-keys" \
     -H "Authorization: Bearer ..." \
     -H "Content-Type: application/json" \
     -d '{"algorithm":"Rsa3072","subjectCn":"Ampora Sub-CA"}'
   

2. Sign it with your corporate CA, returning a cert chain.
3. Settings → PKI → Signing keys → {new draft} → Import certificate and paste the chain.
4. Activate.

Issued agent certs now chain up to your corporate CA. Distribute the new trust bundle to agents via the standard mechanism.

Trust bundle distribution¶

Agents pull GET /pki/trust-bundle.pem during bootstrap and cache it. After a CA rotation, agents that connect at any point during the Trusted window automatically pick up the new bundle.

For agents that connect rarely:

• ship the current bundle alongside their config-management package (Ansible, Salt, Puppet) so they have it before connecting,
• or schedule a rebootstrap within the Trusted window so they pick it up on the next connect.

Verifying¶

After any rotation:

1. Settings → PKI → Signing keys shows the active key with the expected NotBefore / NotAfter.
2. GET /pki/trust-bundle.pem returns the new chain.
3. Connect a fresh test agent — its issued cert chain matches the new active key.
4. Reconnect an existing agent — its cert still validates against the trust bundle (now active + trusted).
5. Audit log shows the rotation events with the actor, timestamp, and key IDs involved.

Troubleshooting¶