> Why a client trusts a certificate: trust stores, intermediates, path validation and cross-signing. Chapters, guides and fixes in one place. Source: https://pkizerotohero.com/topics/chains-and-trust/ Topic # Chains and trust stores A client trusts a server's certificate only if it can build a chain from that certificate, usually through one or more intermediate CAs, to a root that is already in its trust store. A root is trusted because it is in the store, not because it signed itself. Most "unable to get local issuer certificate" and "unknown authority" errors come from a broken chain or a missing root. This hub has the explanations, the fixes for each tool and the guides for trusting a private CA safely. ## Understand it: handbook chapters Plain words first, then the real mechanism, what it looks like at work and why it matters. Chapter 12 ### [Who do we trust? CAs, trust stores and self-signed certificates](https://pkizerotohero.com/handbook/trust-stores/) Every client trusts only the root certificates in its own trust store, so a certificate is accepted only if its chain ends at one of them; being self-signed earns nothing. - Developer - IT ops - Expert Chapter 13 ### [Certificate chains and path validation](https://pkizerotohero.com/handbook/certificate-chains/) Servers must send their leaf and intermediate certificates; clients link them by name and key identifier up to a trusted root and check every signature, date and constraint. - Developer - IT ops - Expert Chapter 14 ### [Two roads to the same root: cross-signing and root expiry](https://pkizerotohero.com/handbook/cross-signing/) Cross-signing gives one CA key two certificates from different issuers, so a chain can reach either an old or a new root; clients must pick a path that is valid. - IT ops - Developer - Expert Chapter 7 ### [Whose key is it? Binding identity to keys](https://pkizerotohero.com/handbook/binding-identity/) Encryption and signatures only help if you use the right person's public key, so something you already trust must vouch that a key belongs to a name. - Beginner - Developer - IT ops Chapter 18 ### [Famous failures and what changed](https://pkizerotohero.com/handbook/famous-failures/) Real PKI failures, from a hacked CA to expired certificates, follow one pattern: a weak point breaks trust, someone notices, and the rules or practices change. - IT ops - Expert - Leader ## Do it: how-to guides Step-by-step, with real commands and a way to check it worked. ### [How to check the certificate chain a server sends](https://pkizerotohero.com/guides/check-remote-certificate-chain/) You will have listed every certificate a server sends, checked their order and links, and verified the chain with a strict client instead of a browser. - Linux - macOS - Windows - Java ### [How to build the full chain file your server needs](https://pkizerotohero.com/guides/build-fullchain/) You will have one PEM file with your certificate followed by its intermediates in the right order, verified offline and proven to work with a strict client. - Linux - nginx - Apache - Kubernetes ### [How to trust a private root CA on Windows](https://pkizerotohero.com/guides/add-root-ca-windows/) Your Windows computer, or a whole fleet, trusts your organisation's private root CA, and you know which apps still need their own setting. - Windows ### [How to trust a private root CA on macOS](https://pkizerotohero.com/guides/add-root-ca-macos/) Your Mac, or every managed Mac, trusts your organisation's private root CA in the System keychain, and you know which apps need their own setting. - macOS ### [How to trust a private root CA on Linux](https://pkizerotohero.com/guides/add-root-ca-linux/) Your Linux server, desktop or container image trusts your organisation's private root CA system-wide, and you know which programs keep their own list. - Linux - Docker ### [How to add a CA to a Java trust store (cacerts)](https://pkizerotohero.com/guides/add-root-ca-java/) Your Java program trusts your private root CA, either through the JDK's cacerts or through its own trust store, and you have proved it with a real connection. - Java - Linux - Windows - macOS ### [How to make Python, Node.js and npm trust a private CA](https://pkizerotohero.com/guides/trust-ca-python-node/) Python, pip, requests, Node.js and npm trust your private root CA, through the operating system's store or a bundle file, with verification still fully on. - Linux - macOS - Windows - Python ### [How to work behind a TLS-inspecting corporate proxy, safely](https://pkizerotohero.com/guides/corporate-proxy-certificates/) You will have confirmed that your traffic is inspected, obtained your company's inspection root through a trusted channel, and made each tool trust it with verification still on. - Windows - macOS - Linux - Java ## Fix it: error pages The exact messages tools and browsers print, with likely causes and safe fixes. - [curlSSL certificate problem: unable to get local issuer certificate](https://pkizerotohero.com/errors/curl-unable-to-get-local-issuer-certificate/) - [curlSSL certificate problem: self-signed certificate in certificate chain](https://pkizerotohero.com/errors/curl-self-signed-certificate-in-certificate-chain/) - [curlcurl: (77) error setting certificate verify locations](https://pkizerotohero.com/errors/curl-77-certificate-verify-locations/) - [OpenSSLverify error:num=20:unable to get local issuer certificate](https://pkizerotohero.com/errors/openssl-verify-error-20/) - [OpenSSLverify error:num=21:unable to verify the first certificate](https://pkizerotohero.com/errors/openssl-verify-error-21/) - [OpenSSLtlsv1 alert unknown ca](https://pkizerotohero.com/errors/openssl-tlsv1-alert-unknown-ca/) - [JavaPKIX path building failed … unable to find valid certification path to requested target](https://pkizerotohero.com/errors/java-pkix-path-building-failed/) - [Python\[SSL: CERTIFICATE\_VERIFY\_FAILED\] certificate verify failed: unable to get local issuer certificate](https://pkizerotohero.com/errors/python-certificate-verify-failed/) - [Node.jsUNABLE\_TO\_VERIFY\_LEAF\_SIGNATURE](https://pkizerotohero.com/errors/node-unable-to-verify-leaf-signature/) - [Node.jsSELF\_SIGNED\_CERT\_IN\_CHAIN](https://pkizerotohero.com/errors/node-self-signed-cert-in-chain/) - [npmUNABLE\_TO\_GET\_ISSUER\_CERT\_LOCALLY](https://pkizerotohero.com/errors/npm-unable-to-get-issuer-cert-locally/) - [Go, Docker, Kubernetesx509: certificate signed by unknown authority](https://pkizerotohero.com/errors/go-x509-unknown-authority/) - [.NET, PowerShellThe remote certificate is invalid according to the validation procedure](https://pkizerotohero.com/errors/dotnet-remote-certificate-invalid/) - [.NET, PowerShellCould not establish trust relationship for the SSL/TLS secure channel](https://pkizerotohero.com/errors/powershell-could-not-establish-trust/) - [git on Windowsschannel: SEC\_E\_UNTRUSTED\_ROOT (0x80090325)](https://pkizerotohero.com/errors/git-schannel-sec-e-untrusted-root/) - [AndroidTrust anchor for certification path not found](https://pkizerotohero.com/errors/android-trust-anchor-not-found/) - [Chrome, EdgeNET::ERR\_CERT\_AUTHORITY\_INVALID](https://pkizerotohero.com/errors/chrome-err-cert-authority-invalid/) - [FirefoxSEC\_ERROR\_UNKNOWN\_ISSUER](https://pkizerotohero.com/errors/firefox-sec-error-unknown-issuer/) - [FirefoxMOZILLA\_PKIX\_ERROR\_SELF\_SIGNED\_CERT](https://pkizerotohero.com/errors/firefox-mozilla-pkix-self-signed-cert/) ## Check yours: browser tools They run in your browser. Nothing you paste is sent anywhere. Tool ### [Chain checker](https://pkizerotohero.com/tools/chain/) Paste a chain and see which link is missing, expired or out of order. Tool ### [Certificate decoder](https://pkizerotohero.com/tools/decoder/) Paste a PEM certificate and read every field in plain words. Tool ### [Paste your error](https://pkizerotohero.com/tools/error-finder/) Paste a certificate error from any tool and get the page that explains it. ## The big picture: crash course Short lessons of about nine minutes each, with check questions. - [Lesson 4: Whose key is it?](https://pkizerotohero.com/course/whose-key-is-it/) - [Lesson 6: Chains and trust stores](https://pkizerotohero.com/course/chains-and-trust-stores/) - [Lesson 8: When trust breaks](https://pkizerotohero.com/course/when-trust-breaks/) ## Look it up: glossary terms Every term in plain words, linked to its full entry. - [Authority Information Access (AIA)](https://pkizerotohero.com/handbook/glossary/#authority-information-access "A certificate extension with links to the issuer's certificate and, sometimes, its OCSP responder.") - [Authority Key Identifier (AKI)](https://pkizerotohero.com/handbook/glossary/#authority-key-identifier "A certificate extension that identifies the public key of the CA that signed the certificate.") - [Certificate authority (CA)](https://pkizerotohero.com/handbook/glossary/#certificate-authority "An organisation or system that checks who controls a name or key and signs certificates that bind them together.") - [Certificate chain](https://pkizerotohero.com/handbook/glossary/#certificate-chain "The sequence of certificates from a server's leaf certificate, through one or more intermediates, up to a trusted root.") - [Certificate pinning](https://pkizerotohero.com/handbook/glossary/#certificate-pinning "Making an app accept only a specific certificate or public key for a server, instead of any certificate its trust store accepts.") - [Cross-signing](https://pkizerotohero.com/handbook/glossary/#cross-signing "When a CA's certificate is also signed by another CA, so clients that trust either root can build a valid chain.") - [Distrust](https://pkizerotohero.com/handbook/glossary/#distrust "When browsers or operating systems stop trusting a CA, so its certificates are rejected even though they have not expired.") - [Intermediate certificate](https://pkizerotohero.com/handbook/glossary/#intermediate-certificate "A CA certificate between the root and the server's certificate. The root signs the intermediate, and the intermediate signs the server certificates.") - [Key substitution](https://pkizerotohero.com/handbook/glossary/#key-substitution "An attack in which someone swaps a public key for their own, so you encrypt to them or trust their signatures by mistake.") - [Leaf certificate](https://pkizerotohero.com/handbook/glossary/#leaf-certificate "The certificate at the bottom of a chain, issued to a server, client or device rather than to a CA.") - [Man-in-the-middle](https://pkizerotohero.com/handbook/glossary/#man-in-the-middle "An attacker who sits between two parties, relays their messages and can read or change them, often by swapping keys.") - [Path validation](https://pkizerotohero.com/handbook/glossary/#path-validation "The checks a client runs on a certificate chain: signatures, validity dates, CA flags, constraints, names and revocation, up to a trusted root.") - [PKI](https://pkizerotohero.com/handbook/glossary/#pki "Short for public key infrastructure: everything needed to issue, trust, check and revoke certificates that bind public keys to identities.") - [Public key infrastructure (PKI)](https://pkizerotohero.com/handbook/glossary/#public-key-infrastructure "The people, policies, systems and standards that create, distribute, check and revoke certificates binding public keys to identities.") - [Relying party](https://pkizerotohero.com/handbook/glossary/#relying-party "Whoever checks a certificate and relies on it to decide whether to trust a connection, signature or device.") - [Root certificate](https://pkizerotohero.com/handbook/glossary/#root-certificate "A CA certificate at the top of a chain, trusted because it is already in a trust store, not because it is self-signed.") - [Root program](https://pkizerotohero.com/handbook/glossary/#root-program "A browser's or operating system's process for deciding which CAs' roots it trusts, with rules those CAs must follow.") - [Self-signed certificate](https://pkizerotohero.com/handbook/glossary/#self-signed-certificate "A certificate signed with its own private key, so issuer and subject match. It is trusted only if deliberately added to a trust store.") - [Subject Key Identifier (SKI)](https://pkizerotohero.com/handbook/glossary/#subject-key-identifier "A certificate extension with an identifier, usually a hash, of the certificate's own public key.") - [TLS inspection](https://pkizerotohero.com/handbook/glossary/#tls-inspection "A proxy or firewall that decrypts TLS traffic by presenting its own certificates, signed by a CA installed on the organisation's devices.") - [Trust anchor](https://pkizerotohero.com/handbook/glossary/#trust-anchor "A public key or certificate that a relying party trusts directly, where path validation ends.") - [Trust store](https://pkizerotohero.com/handbook/glossary/#trust-store "The list of root certificates a system or application trusts, used as the starting point for checking every certificate chain.") ## Other topics - [Certificates](https://pkizerotohero.com/topics/certificates/) - [TLS and HTTPS](https://pkizerotohero.com/topics/tls/) - [Lifecycle and automation](https://pkizerotohero.com/topics/lifecycle-and-automation/) - [Revocation and transparency](https://pkizerotohero.com/topics/revocation-and-transparency/) - [Private PKI](https://pkizerotohero.com/topics/private-pki/) - [Hashes and signatures](https://pkizerotohero.com/topics/signing/) - [Post-quantum cryptography](https://pkizerotohero.com/topics/post-quantum/)