Directory caching headers

What this check verifies

This check reads the Cache-Control header on the directory response. If the header is present, the check passes and reports its value. If it is absent, the check warns. This is advisory: a missing Cache-Control never fails the directory and never makes it invalid.

A passing response carries a header such as:

Cache-Control: max-age=3600

Why it matters

Every verifier that checks one of your signatures fetches the directory to resolve the signing key. Without a caching hint, each verifier may refetch on every request, which adds load to your origin and latency to verification. A Cache-Control with a sensible max-age lets verifiers reuse the directory for a while instead of refetching it constantly.

The trade-off is freshness against load. Too long a max-age means a rotated or revoked key lingers in verifier caches after you have changed the directory; too short defeats the point of caching. The check is advisory because the spec does not mandate a specific value, and the right number depends on how often you rotate keys. The checker flags the absence so you make a deliberate choice rather than leaving it unset by accident.

How to fix it

1. Set a Cache-Control header on the well-known directory response.
2. Choose a max-age that balances load against how quickly a key change must propagate. An hour (max-age=3600) is a reasonable starting point for a directory that does not rotate keys frequently; shorten it if you rotate often.
3. Avoid extremes: a multi-day max-age delays key changes reaching verifiers, while no-store removes the caching benefit entirely.

The usual cause is serving the directory through a handler that sets no cache headers. Add the header on that route.

References

• The web-bot-auth directory draft (draft-meunier-http-message-signatures-directory) discusses caching of the directory.
• How grading works explains how an advisory warning moves the grade without capping it.