checkId: check.timestamp.tsa.root-expiry plugin: stellaops.doctor.timestamping severity: warn tags: [timestamping, tsa, root, certificate, expiry]

TSA Root Certificate Expiry

This Stella Ops Doctor check warns operators when a timestamping authority (TSA) trust anchor — a root certificate — is approaching expiry. Because a root expiry invalidates every timestamp chained to it and renewal must be coordinated across the whole deployment, this check uses deliberately long lead-time thresholds so platform operators can plan the rotation well in advance.

What It Checks

Checks if TSA trust anchor (root) certificates are approaching expiry. The check:

Evaluates each root certificate in the RootCertificates configuration list.
Calculates days remaining until expiry.
Fails (unhealthy) if any root certificate is expired or within the critical threshold (default 180 days).
Warns (degraded) if within the warning threshold (default 365 days).
Uses longer thresholds than leaf certificates because root renewal requires more coordination.

Why It Matters

Root certificates anchor the entire TSA trust chain. When a root expires, all timestamps signed by TSAs chained to that root become unverifiable. Root certificate renewal requires updating trust stores across the entire deployment, which takes significant lead time.

Common Causes

Root certificate approaching end-of-life (typically 10-20 year lifetime)
Using a custom root CA with a shorter validity period
Trust store not updated after provider rotated roots

How to Fix

Docker Compose

Update root certificate trust store:

# Update trust anchors
docker exec <platform-container> stella trust-anchor update --cert /certs/new-root.pem

Bare Metal / systemd

# Update the trust anchor
stella trust-anchor update --cert /path/to/new-root.pem

# Or update the system trust store
sudo cp /path/to/new-root.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates

Kubernetes / Helm

timestamping:
  rootCertificates:
    warnDays: 365
    criticalDays: 180

Verification

stella doctor run --check check.timestamp.tsa.root-expiry

TSA Certificate Expiry (check.timestamp.tsa.cert-expiry) — checks TSA signing certificate expiry
TSA Chain Valid (check.timestamp.tsa.chain-valid) — validates TSA certificate chain integrity