Certificate Revocation Lists

Certificate Revocation Lists

Mantis publishes RFC 5280 certificate revocation lists (CRLs) for every certificate authority it holds. A CRL is what makes a certificate withdrawable before it expires, including the certificates that have no agent registration behind them — a Thorax server certificate, Mandible’s dispatch certificate, and anything else signed through the platform’s own signing path.

What is published, and where

Endpoint	Returns	Content type
GET /api/v1/crl/{ca_id}	One authority’s current CRL	application/pkix-crl (DER)
GET /api/v1/crl	Every live authority’s CRL, concatenated	application/x-pem-file (PEM)

Both endpoints are unauthenticated by design. A CRL is signed by the authority that issued it, so a consumer authenticates it from the trust anchor it already holds and the transport carries nothing secret. The party that most needs to read one is a peer whose certificate has just been refused, which by definition cannot authenticate.

GET /api/v1/crl/{ca_id} is also the URL stamped into the CRLDistributionPoints extension of every certificate the platform signs, so a third-party verifier finds it without being told.

The distribution point comes from server.external_url

Certificates carry a distribution point only when server.external_url is set in Mandible’s configuration. With it unset there is no URL the platform can honestly stamp into a certificate, so the extension is omitted rather than pointing at something unreachable.

Publication schedule

Property	Value
nextUpdate	7 days after thisUpdate
Re-issued	when the stored list is more than 5 minutes old and a request arrives
Consumers refresh	every 5 minutes

A revocation is therefore visible to a peer within roughly ten minutes. The list is signed once per interval and stored; the endpoint serves the stored bytes, so an anonymous caller cannot drive the CA key at request rate.

An entry drops off the list once the certificate would have expired anyway, which is what keeps the list from growing without bound.

Configuring Thorax

[tls]
auth_mode = "ca_signed"
ca_cert_path = "/etc/mantis/ca/certs/ca.crt"
crl_url = "https://mantis.example.com/api/v1/crl"
crl_path = "/etc/mantis/ca/crl"   # optional, merged with the published lists

Or MANTIS_TLS_CRL_URL / MANTIS_TLS_CRL_PATH in the environment.

crl_url and crl_path are merged, not exclusive: pinning a list locally does not stop the platform’s own from being applied.

Plain http:// is legitimate here. Each list is signed by the authority that issued it and is verified against the CA already configured, so the transport carries no trust.

Configuring Tarsus

[tls]
ca_cert_path = "/etc/mantis/ca/certs/ca.crt"
crl_url = "https://mantis.example.com/api/v1/crl"

Without this, Thorax’s server certificate is not revocable at all: the CA chain in ca_cert_path says who issued that certificate, not whether it is still good. The revocation check runs on that same CA chain verifier.

What happens when the CRL cannot be had

The two ends make deliberately different choices, because refusing has a different cost at each.

Condition	Thorax (verifying agents)	Tarsus (verifying Thorax)
Fetch fails	Keeps the lists it last fetched	Keeps the lists it last fetched
Never fetched successfully	No revocation check	No revocation check
List past nextUpdate	Refuses every CA-signed client	Still applies the list
Certificate’s issuer absent from the bundle	Refuses the client	Admits the peer

A failed fetch changes no admission decision at either end. Only a sustained outage — one long enough for nextUpdate to pass, which is a week — reaches the fail-closed rows.

Thorax fails closed because it is the resource being protected: an agent whose certificate it cannot vouch for must not execute commands, and a Thorax that cannot reach Mandible cannot dispatch anything anyway.

Tarsus does not, because an agent that refuses to reach its Thorax is a disconnected fleet and disconnection protects nothing. The list the agent still holds catches every certificate revoked up to the moment that list was issued.

A Thorax with crl_url set needs the control plane reachable

If Mandible is unreachable for longer than a week, every CA-signed agent is refused at the TLS layer until a fresh CRL is fetched. Monitor the fetch: Thorax logs Published CRL fetch failed on each failed refresh.

Revoking a certificate

Revocation is the ordinary operator action; nothing separate is needed to reach the CRL.

mantisctl cert revoke "<REGISTRATION_UUID>" --reason "Certificate compromised"

This marks the certificate in the ledger, and the next CRL issued by that authority carries it, with an RFC 5280 reason code and the time the revocation was processed. A certificate superseded by rotation is listed as superseded; one withdrawn with a registration is listed as privilegeWithdrawn.

An offline CA is outside this mechanism

mantisctl cert generate-ca produces a standalone authority whose private key never reaches Mandible. Mantis cannot issue a CRL for it, and the certificates under it cannot be withdrawn through this path. Import the CA (mantisctl cert import-ca) if you want its certificates to be revocable.