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

## 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:

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

### Bare Metal / systemd
```bash
# 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
```yaml
timestamping:
  rootCertificates:
    warnDays: 365
    criticalDays: 180
```

## Verification
```
stella doctor run --check check.timestamp.tsa.root-expiry
```

## Related Checks
- `check.timestamp.tsa.cert-expiry` — checks TSA signing certificate expiry
- `check.timestamp.tsa.chain-valid` — validates TSA certificate chain integrity