Legacy Client Compatibility Cross-Signed Root Certificates

January 15, 2021 15:22

ZeroSSL's certificates are widely trusted by all modern clients and the default certificate chain that we include in the "ca_bundle.crt" file makes sure of that. However, certain older legacy operating systems and clients might not be able to verify certificates that are delivered with the default chain. In case you are serving such old clients we provide additional cross-signed root CA certificates that you can add to your certificate chain in order to provide compatibility for such clients. Wherever possible we advise upgrading your clients as using end-of-life systems poses various security threats.

Compatibility for the default chain

The default chain is compatible with all modern, supported systems and is incorporated into major root stores (Mozilla, Microsoft, Apple, Google/Chrome). This means that the certificate will work out of the box for all up-to-date systems.

Cross-signed root CA compatibility

For any operating system or client older than the list below you can gain compatibility by installing the cross-signed root CA into your chain. Installing the cross-signed certificate will give you compatibility with the following operating systems/clients:

Apple iOS 9 and earlier
Apple macOS 10.11 (El Capitan) and earlier
Google Android 5.1 and earlier
Mozilla Firefox 52 ESR and earlier
Oracle Java JRE 7 and earlier

Installation of the cross-signed root CA

We provide three ways of fetching the cross-signed root certificate.

Manually, you can accomplish it as follows:

Default: For standard RSA certificates and private keys please download the following cross-signed certificate: https://crt.sh/?id=1199354
ECC: For ECC-based certificates (only available via custom CSRs) please download the following cross-signed certificate: https://crt.sh/?id=2841410

After downloading the appropriate cross-signed root certificate above, you have to add it to your chain manually (by appending it to your ca_bundle.crt in your favorite text editor / copy-pasting it at the end and then installing it)

Using the API, you can download the chain as follows:

For your convenience, ZeroSSL provides an API endpoint where you can fetch the full, cross signed certificate chain.

(Optional) Find the relevant root for your certificate with the following endpoint: https://zerossl.com/documentation/api/list-certificates/. The relevant cross signed root certificate chain can be identified by the following parameter: ca_certificate_id.
Download the chain using the following endpoint: https://zerossl.com/documentation/api/download-ca-certificate/. You can do this by passing the ca_certificate_id

As an example for the process above:

List your certificates: https://api.zerossl.com/certificates?access_key={{ACCESS_KEY}}
Download the chain by passing the ca_certificate_id: https://api.zerossl.com/ca_certificates/6/download/chain?access_key={{ACCESS_KEY}}

You can also copy-paste the ready made cross-signed chain below and install it directly. In any case, the end result should look like this (Default, RSA certificates):

ECC certificates:

After saving the file you can proceed to install your certificate as normal. The downloaded file is used in place of ca_bundle.crt file, while the certificate.crt and your private key remain the same.

Compatibility for the default chain

Cross-signed root CA compatibility

Installation of the cross-signed root CA

Chatbot Disclaimer

Data Usage