Certificate chain
A server sends its certificate together with the intermediate certificates that lead to a root the client trusts. When a CA moves to a new root, clients whose trust store does not hold that root yet fail their TLS handshakes: old Android versions, old Java runtimes, and devices that are never updated.
CAs bridge the move in two ways:
- Alternate chains. Many ACME CAs offer the same certificate with several chains. Let's Encrypt, for example, offers a chain that ends at ISRG Root X1, its most widely trusted root, and shorter ones that end at newer roots.
- Cross-signed roots. The CA has its new root signed by an older root it already owns (DigiCert's G5 root is signed by Global Root G2). A server that also sends that cross-signed copy lets old clients build the chain to the older root they know. Clients that already trust the new root stop there.
CertAutoPilot lets you choose both, per certificate.
The chain is chosen when a version is stored. A change applies from the certificate's next issuance, renewal or re-issue. The version in use keeps the chain it was stored with; re-issue the certificate to apply a change now.
Choosing a chain
Open a certificate and select the Chain tab, or set it in the Options step of the issue wizard.
Chain offered by the CA (ACME)
The tab lists the chains the CA offered for the current version, each named by the root it ends at. Before a certificate's first issuance, the list shows the chains the same ACME account's CA offered on other certificates of the project with the same key algorithm (RSA or ECDSA). A CA issues the two from different intermediates, so their chains end at different roots — Let's Encrypt, for example, offers a chain ending at ISRG Root X2 for ECDSA keys only. Choose one, or keep The CA's default chain.
If the CA does not offer the chosen chain at an issuance, the version serves the CA's default chain. A Certificate chain not as chosen notification is sent. The choice is kept, so the next issuance picks the chosen chain again when the CA offers it.
AD CS and CA connectors deliver one chain, so for them this choice is not shown.
Extend the chain
Add up to four certificates from the chain catalogue. At every issuance CertAutoPilot builds the chain like this:
- A cross-signed copy of a root in the CA's chain replaces that root. It is the same root, signed by an older one.
- A certificate that signed the top of the chain is appended. This repeats while something links, so a cross-sign of a cross-sign extends the chain further.
- Every link is checked by signature. A certificate that does not link to this certificate's chain is left out and the version records why.
Every certificate added is also checked against the new leaf:
| The selected certificate | What is served |
|---|---|
| Valid, and valid at least as long as the new certificate | The selected certificate. |
| Expired, revoked, or expiring before the new certificate | An equivalent catalogue entry (same subject, key and signing root) valid at least as long as the new certificate. The certificate's choice is not changed. |
| As above, and no equivalent entry exists | Nothing: the CA's chain without it, with a warning. |
| Removed from the catalogue | Nothing, with a warning. |
The choice is kept on the certificate and applied again at every renewal, against the chain the CA delivers that time. When the CA rotates its intermediate under the same root, a cross-sign of that root still links and extends the new intermediate — nothing to change. When the CA starts issuing from another root, a cross-sign of the old root no longer links: it is left out, the version records it, and a chain warning notification (and a chain changed one, since the CA's chain now ends at another root) tells you to add a cross-sign for the new root.
So a deployed version never outlives the certificates added to its chain. When one of them expires, add its successor (often the same cross-sign re-issued by the CA) to the catalogue. Renewals use the successor without any change to the certificates themselves.
The Chain tab shows where the served chain ends, where the CA's own chain ends, and every note the current version recorded.
Before you save, the Chain tab checks the choice against the current version with the same rules:
- The catalogue picker groups the entries: Links to this chain, Cannot be served with this certificate (expired, expiring before the certificate or revoked with no equivalent, already in the chain, or the same certificate as another selection) and Does not link to this chain today. The check includes what is already selected, so the next step of a two-step extension appears under "Links" once the first step is selected.
- Picking an entry that does not link shows a warning, and the selected row keeps saying why it would be left out.
- A box shows where the chain would end with this choice and which certificates it would serve.
Nothing is refused: the check uses the chains the CA delivered for the current version and a certificate as long-lived as the current one issued today (a choice applies from the next issuance), and the CA can deliver another chain at the next issuance. A certificate that has never been issued has nothing to check against, so its picker lists the whole catalogue.
The chain catalogue
Settings → Chain certificates holds the public CA certificates that may extend chains. It is shared by every project of the installation. Anyone can read it; organization admins and owners add and remove entries.
- Find in the CCADB. The CCADB is the public database of the browser root programs. It lists every
intermediate and cross-signed certificate of the publicly trusted CAs. Paste the chain a certificate serves
today and CertAutoPilot lists the CCADB certificates that extend it, up to three steps towards older roots,
each checked by signature. Revoked and expired ones are shown but cannot be added.
- From a certificate: an organization admin can open Find chain certificates for this certificate in the CCADB on the certificate's Chain tab. The search starts from the certificate's current chain (no download or paste needed). Picked entries go into the catalogue and into that certificate's chain draft; Save chain keeps them. Entries already in the catalogue can be picked there too.
- The Signed by column names the root a client must already trust for the entry to help it. Signer root shows when that root was created and since which Firefox release it is trusted, from Mozilla's root store in the CCADB. An older root is present on more old devices, but every device's own root store decides; check with the devices you must serve. Not trusted for websites by Mozilla marks a root Mozilla removed for websites (DigiCert Global Root CA and High Assurance EV Root CA today): old devices may still trust it, and a client that knows the newer root stops there anyway.
- The first search downloads the CCADB reports (about 14 MB, plus Mozilla's root-store report) and keeps them for a day.
- On an installation without internet access, switch the lookup off: Settings → General → Look up chain certificates in the CCADB.
- Upload. Paste one certificate's PEM, for example a cross-sign downloaded from the CA's site. Only CA certificates are accepted, and never a self-signed root: a server does not send its root, so add the cross-signed copy instead. Expired certificates are refused.
An entry a certificate's chain names cannot be removed. Take it out of the certificate's chain first. The Used by column, which counts the certificates of every project that use an entry, is shown to organization admins and owners only. Entries used by certificates send a Chain certificate expiring notification 30, 14 and 7 days before they expire, unless the catalogue already holds an equivalent successor. It goes to the projects whose certificates use the entry.
When the CCADB lists a catalogue entry as revoked, the entry is flagged Revoked: it cannot be chosen, and a renewal uses an equivalent successor or leaves it out with a warning. Versions already stored keep serving it until they are renewed — a Chain certificate revoked notification goes to every project whose certificates use it, so you can re-issue them now (clients that check revocation may refuse such a chain). The check runs when the CCADB is searched and once a day on the worker, unless the lookup is switched off.
The CCADB is reached directly or through the HTTP(S) proxy configured for the server.
Per distribution: the CA's default chain
Some targets want the shortest chain, for example to save handshake bytes, or because they build chains themselves. A distribution can deploy The CA's default chain, the chain exactly as the CA delivered it, whatever the certificate chooses:
- When linking a module, set Chain.
- On an existing distribution, use ⋯ → Deploy the CA's default chain.
This also applies from the next deployment of a new version. Modules skip a certificate they already hold. The setting cannot be changed while a large deployment that was split into batches is still running.
Notifications
| Event | When |
|---|---|
cert.chain_warning | A stored version does not serve the chosen chain: the preferred chain was not offered, or a chain certificate expired, would expire before the certificate, is revoked, does not link or was removed. |
cert.chain_changed | The CA delivered the new version with a chain that ends at a different root than it did for the previous version: the CA moved roots at a renewal. A change made by the certificate's own chain choice does not send it. |
chain_certificate.expiring | A chain catalogue certificate that certificates use expires in 30, 14 or 7 days and has no successor. |
chain_certificate.revoked | The CCADB starts listing a chain catalogue certificate that certificates use as revoked. Sent once, to every project whose certificates use it. |
What is not covered
- Certificates issued before this change keep their chain until their next issuance.
- Imported certificates serve the chain they were imported with. Re-import them with the chain you want.
- CertAutoPilot does not judge which clients trust which root. It serves the chain you choose and records where it ends.
Video tutorials
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →