How to trust a private root CA on Linux

Before you start

• The root certificate of your private CA in PEM format (text starting with -----BEGIN CERTIFICATE-----). Never a private key.
• Its SHA-256 fingerprint, from a channel you trust.
• Root access (sudo).
• Your distribution family: cat /etc/os-release tells you.

Why it matters: every root in the system trust store can vouch for any name, for curl, git, Go programs, package managers and most other tools on the machine. Add only roots your organisation controls.

Steps

1. Check the file

openssl x509 -in corp-root.crt -noout -subject -issuer -enddate -fingerprint -sha256 -ext basicConstraints

subject=C=BE, O=Example Corp, CN=Example Corp Root CA
issuer=C=BE, O=Example Corp, CN=Example Corp Root CA
notAfter=Oct 17 01:43:50 2036 GMT
sha256 Fingerprint=BC:02:A4:F5:DC:68:B3:FD:CD:C4:78:03:0E:30:8C:B5:9D:6D:A0:84:5A:A0:B4:33:36:60:78:8E:96:C2:2E:01
X509v3 Basic Constraints: critical
    CA:TRUE

The fingerprint must match the published value, subject and issuer must be equal, and CA:TRUE must be set. If the file is DER (binary), convert it first: openssl x509 -inform DER -in corp-root.cer -out corp-root.crt (DER and PEM).

2. Debian, Ubuntu and Alpine

The file must be PEM, hold one certificate, and end in .crt, or update-ca-certificates ignores it:

sudo cp corp-root.crt /usr/local/share/ca-certificates/example-corp-root.crt
sudo update-ca-certificates

On Ubuntu 24.04 with Java installed, the output was:

Updating certificates in /etc/ssl/certs...
rehash: warning: skipping ca-certificates.crt,it does not contain exactly one certificate or CRL
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
Processing triggers for ca-certificates-java (20240118) ...
Adding debian:example-corp-root.pem
done.
done.

1 added is what you want. The rehash warning is harmless. The Adding debian:… line is a hook that also put the root into the distribution’s Java cacerts. The result is the bundle /etc/ssl/certs/ca-certificates.crt plus a hashed directory, /etc/ssl/certs. Alpine uses the same folder and command once the ca-certificates package is installed.

3. RHEL, Fedora, CentOS Stream, Rocky, AlmaLinux and Amazon Linux

Here the folder accepts PEM or DER, and the anchors are trusted “for all purposes” (update-ca-trust):

sudo cp corp-root.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

This rebuilds /etc/pki/ca-trust/extracted/, including the PEM bundle behind /etc/pki/tls/certs/ca-bundle.crt and the Java keystore behind /etc/pki/java/cacerts. The p11-kit tool does the same in one step: sudo trust anchor corp-root.crt (Red Hat).

4. SUSE and openSUSE

Local roots go in /etc/pki/trust/anchors/ (openSUSE ca-certificates):

sudo cp corp-root.crt /etc/pki/trust/anchors/
sudo update-ca-certificates

5. Container images

A container does not inherit the host’s trust store. Bake the root into the image at build time:

FROM debian:trixie-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
    && rm -rf /var/lib/apt/lists/*
COPY corp-root.crt /usr/local/share/ca-certificates/example-corp-root.crt
RUN update-ca-certificates

For Alpine, install ca-certificates with apk add --no-cache ca-certificates and use the same two lines. For Red Hat UBI images, copy to /etc/pki/ca-trust/source/anchors/ and run update-ca-trust. In Kubernetes you can also mount the bundle from a ConfigMap, but the image approach works everywhere.

6. Point the programs that keep their own list

For Chrome on Linux, the Chromium documentation uses NSS certutil (package libnss3-tools on Debian and Ubuntu, nss-tools on Fedora). Recent versions use ~/.local/share/pki/nssdb, or ~/.pki/nssdb if that already exists:

DB="$HOME/.pki/nssdb"; [ -d "$DB" ] || DB="$HOME/.local/share/pki/nssdb"
certutil -d "sql:$DB" -A -t "C,," -n "Example Corp Root CA" -i corp-root.crt
certutil -d "sql:$DB" -L

-t "C,," trusts the CA for TLS server certificates only. On a test database the listing showed Example Corp Root CA C,,.

Check it worked

Before the change, curl on our Ubuntu test machine refused a server whose chain ends at the private root:

curl -sS https://intranet.example.com:18443/ -o /dev/null

curl: (60) SSL certificate problem: unable to get local issuer certificate

After update-ca-certificates, the same command printed the status code 200, and OpenSSL verified the whole chain:

openssl s_client -connect intranet.example.com:18443 -servername intranet.example.com -verify_hostname intranet.example.com </dev/null

depth=2 C = BE, O = Example Corp, CN = Example Corp Root CA
verify return:1
depth=1 C = BE, O = Example Corp, CN = Example Corp Issuing CA 1
verify return:1
depth=0 CN = intranet.example.com
verify return:1
...
Verification: OK
Verify return code: 0 (ok)

On the RHEL family, trust list --filter=ca-anchors | grep -A3 "Example Corp" shows the new anchor.

If something goes wrong

• 0 added on Debian or Ubuntu. The file does not end in .crt, is DER instead of PEM, or is in the wrong folder.
• The root is added, but unable to get local issuer certificate or verify error 20 remains. The chain probably ends at a different root, or the server leaves out its intermediate. Paste the server’s chain into the chain checker below, and build the full chain file on the server.
• curl, git and Go work, but Node.js or a pip-installed tool fails with SELF_SIGNED_CERT_IN_CHAIN or similar. That program reads its own bundle: see step 6.
• It works on the host but not in the container, often as x509: certificate signed by unknown authority. Add the root to the image (step 5).
• curl: (77) error setting certificate verify locations. SSL_CERT_FILE, CURL_CA_BUNDLE or --cacert points to a file that does not exist; unset it, or point it at the system bundle.

Try it: Chain checkerOpen the full tool

Runs in your browser. Nothing you paste is sent anywhere.

Paste the chain

Try a sampleChoose a sample…A complete chain: leaf, intermediate and rootA server that forgets its intermediateA chain in the wrong orderA self-signed root CA

-----BEGIN CERTIFICATE----- MIIC1zCCAnygAwIBAgIQWTTOzqWiPshGdQhNb6kmNjAKBggqhkjOPQQDAjB+MQsw CQYDVQQGEwJCRTEZMBcGA1UEChMQUEtJIFplcm8gdG8gSGVybzEnMCUGA1UECxMe U2FtcGxlcyAtIG5vdCBwdWJsaWNseSB0cnVzdGVkMSswKQYDVQQDEyJQS0kgWmVy byB0byBIZXJvIFNhbXBsZSBJc3N1aW5nIENBMB4XDTI2MTAwMTAwMDAwMFoXDTM2 MTAwMTAwMDAwMFowGjEYMBYGA1UEAxMPd3d3LmV4YW1wbGUuY29tMFkwEwYHKoZI zj0CAQYIKoZIzj0DAQcDQgAEw4og6Y/SOr+WrqSv+ng7tOBEsc5N3A3yZRk+9hsR XzPQvB9672aHZHTYFNlSY93RWVcTRieE+8XnIbWIYfwxIqOCAT4wggE6MAwGA1Ud EwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMBMCcG A1UdEQQgMB6CD3d3dy5leGFtcGxlLmNvbYILZXhhbXBsZS5jb20wHQYDVR0OBBYE FALMipe4vcXJTpwO926S15Y/bobzMB8GA1UdIwQYMBaAFN+ph37v40SN23r6Fg/z OvSNjJqeMEgGCCsGAQUFBwEBBDwwOjA4BggrBgEFBQcwAoYsaHR0cDovL3BraS5l eGFtcGxlLmNvbS9zYW1wbGUtaXNzdWluZy1jYS5jcnQwPQYDVR0fBDYwNDAyoDCg LoYsaHR0cDovL3BraS5leGFtcGxlLmNvbS9zYW1wbGUtaXNzdWluZy1jYS5jcmww EwYDVR0gBAwwCjAIBgZngQwBAgEwCgYIKoZIzj0EAwIDSQAwRgIhAM5dJUPhL+qV artvWtQinfnykhVflJTjMXe8M6PnqQfaAiEAhOLGj1hSEkNxQoMrYNXRaIe69nq6 2unibVFSVw1AC80= -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIIE2TCCAsGgAwIBAgIQPh9PeiGf4STnEQriHxExjDANBgkqhkiG9w0BAQsFADB7 MQswCQYDVQQGEwJCRTEZMBcGA1UEChMQUEtJIFplcm8gdG8gSGVybzEnMCUGA1UE CxMeU2FtcGxlcyAtIG5vdCBwdWJsaWNseSB0cnVzdGVkMSgwJgYDVQQDEx9QS0kg WmVybyB0byBIZXJvIFNhbXBsZSBSb290IENBMB4XDTI1MDEwMTAwMDAwMFoXDTQw MDEwMTAwMDAwMFowfjELMAkGA1UEBhMCQkUxGTAXBgNVBAoTEFBLSSBaZXJvIHRv IEhlcm8xJzAlBgNVBAsTHlNhbXBsZXMgLSBub3QgcHVibGljbHkgdHJ1c3RlZDEr MCkGA1UEAxMiUEtJIFplcm8gdG8gSGVybyBTYW1wbGUgSXNzdWluZyBDQTBZMBMG ByqGSM49AgEGCCqGSM49AwEHA0IABBFqObJ/j93aHrAuebO5+KWnj0xRFzUS8/Jh Idj6jR/p4zqaNT8+gOqxZ+zhpNO/weIpz/nzXjQ7RJS+EebYRNijggEfMIIBGzAS BgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggr BgEFBQcDAQYIKwYBBQUHAwIwHQYDVR0OBBYEFN+ph37v40SN23r6Fg/zOvSNjJqe MB8GA1UdIwQYMBaAFIVx1Hy1TuED0pMkxEcdM+DWWPGiMEUGCCsGAQUFBwEBBDkw NzA1BggrBgEFBQcwAoYpaHR0cDovL3BraS5leGFtcGxlLmNvbS9zYW1wbGUtcm9v dC1jYS5jcnQwOgYDVR0fBDMwMTAvoC2gK4YpaHR0cDovL3BraS5leGFtcGxlLmNv bS9zYW1wbGUtcm9vdC1jYS5jcmwwEwYDVR0gBAwwCjAIBgZngQwBAgEwDQYJKoZI hvcNAQELBQADggIBAFa8c1kEzTTPW2aPDRPb3+OQc8GTgwpZV0pWNR3e6X8mJi7A D/RGrz4t354IwGzTts+tX23sY3fORKST3/BkqeHZwAZHvGNWi0+Co342eo2BySxo bcyy31AJBSSHOC2b7KJ11coMX++bvaHgtwOloy6DnHRDYIFwWRHg91wo1MKJGNVb OQH0vmqn6YPDLZ4BYL8VHOVtlRddBwd6bKyyp3Lw0MEMgfmg87Yd/U0yRZFaLKNb b5vgDg7n+J1ozFwvumQlN6WVEyPsQdvI73K5bgMHkUeeUQ6j9KOeDMZMjbqQSC8x 1khcyT/qhqZLDJIHvmWS11FcYaLQUuvQiAzQieTNIuOM8WJw95LlxYSNIkZeOuLf f+JboiuT1cmqmvdbngAXtBIWRJ+Byeqdq2Z0d8Xfln6gWhHmm93+DO5uTaTxBwTr DayFTdTFxBZydXs48S+I/rVQvQtwkRh3rOcZpwTMsGzfoiCsOhEaiBOFk0C5FEKi um55SDXCMR6yXDhWqFPBIdle4izj5g2YmuZ3YD4G3PlcX5okW7aKTNU3RGWEOMk3 Ob9bkPnCsY7Ei4OqDqTBt/8HH/2kA4om4RzKGLw5Zc/Y+KhpbFhT52gtL7WDEEVZ NqFHgi6fdHgsczFNpCKhC8vM+mAM/gBiVR8hYIpt5lPFyXpFJO5Wn5BcEkv3 -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- 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 -----END CERTIFICATE-----

Every certificate the server sends, leaf first. The output of openssl s_client -showcerts -connect example.com:443 works as it is: we ignore the text around the certificates.

Check the chainClearChoose a file

Why this works

OpenSSL-based programs check a server’s certificate chain against a CA bundle file or a hashed directory, and accept it only if it ends at a certificate in there. update-ca-certificates and update-ca-trust rebuild those files from the distribution’s roots plus your local ones, so every program that reads them trusts the new root at the next connection. A root is trusted because it is in the store, not because it is self-signed (Who do we trust?). The checks themselves are in Certificate chains and path validation, and designing a private CA that is safe to trust is in A CA of your own.

Go deeper

• update-ca-certificates(8): the Debian tool and its rules for local certificates.
• Red Hat: using shared system certificates: update-ca-trust and trust anchor.
• update-ca-trust(8): the source folders and every extracted file.
• Chromium: certificate management on Linux: the NSS database Chrome uses.
• curl: SSL certificate verification: how curl finds its CA bundle.