> Running a CA of your own: two-tier design, HSMs and key ceremonies, mutual TLS and device identity. Chapters, guides and fixes in one place. Source: https://pkizerotohero.com/topics/private-pki/ Topic # Private PKI Many organisations run their own CA for internal servers, users, devices and services. Its certificates are trusted only by machines you configure to trust its root. This hub covers a two-tier design with an offline root, guarding CA keys with HSMs and key ceremonies, distributing your root safely, mutual TLS and identities for machines. ## Understand it: handbook chapters Plain words first, then the real mechanism, what it looks like at work and why it matters. Chapter 22 ### [A CA of your own: private two-tier PKI](https://pkizerotohero.com/handbook/private-ca/) A private CA lets you issue certificates for internal systems under your own rules, built safely as an offline root plus an online issuing CA with clear policies and templates. - Expert - IT ops - Developer Chapter 21 ### [Guarding the keys: HSMs and key ceremonies](https://pkizerotohero.com/handbook/hsm-and-key-ceremonies/) A CA is only as trustworthy as its private keys, so they live in certified hardware, are created in witnessed ceremonies and are used only under multi-person control. - Expert - IT ops - Leader 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 23 ### [Both sides show ID: mutual TLS](https://pkizerotohero.com/handbook/mutual-tls/) In mutual TLS the client also proves who it is, with a certificate and a signature from its private key, so both ends are authenticated before any data flows. - IT ops - Developer - Expert Chapter 25 ### [Machines with passports: device identity](https://pkizerotohero.com/handbook/device-identity/) A device certificate, installed at the factory with its private key locked in secure hardware, lets a machine prove what it is and who made it, for its whole life. - IT ops - Developer - Expert ## Do it: how-to guides Step-by-step, with real commands and a way to check it worked. ### [How to run a small private CA with step-ca (lab)](https://pkizerotohero.com/guides/private-ca-step-ca/) You will have a lab CA running smallstep's step-ca that issues and renews 24-hour certificates, speaks ACME, and refuses names outside your lab domain. - Linux - macOS ### [How to build a test CA with OpenSSL (lab only)](https://pkizerotohero.com/guides/openssl-test-ca/) You will have a two-tier test CA built with openssl ca: a root, a name-constrained issuing CA, server and client certificates, a revocation and working CRLs. - Linux - macOS - Windows ### [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 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 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 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 set up mutual TLS (nginx and curl)](https://pkizerotohero.com/guides/mutual-tls-setup/) You will have an nginx endpoint that accepts only clients holding a certificate from your own client CA, lets in only the clients you name, and is tested with curl. - nginx - Linux - Windows ### [How to use SSH certificates instead of known\_hosts](https://pkizerotohero.com/guides/ssh-certificates/) You will have OpenSSH host and user certificates signed by your own CAs, so clients trust servers without first-use prompts and servers trust short-lived user certificates. - Linux - macOS - Windows ## Fix it: error pages The exact messages tools and browsers print, with likely causes and safe fixes. - [OpenSSLtlsv1 alert unknown ca](https://pkizerotohero.com/errors/openssl-tlsv1-alert-unknown-ca/) - [curlSSL certificate problem: self-signed certificate in certificate chain](https://pkizerotohero.com/errors/curl-self-signed-certificate-in-certificate-chain/) - [Go, Docker, Kubernetesx509: certificate signed by unknown authority](https://pkizerotohero.com/errors/go-x509-unknown-authority/) - [AndroidTrust anchor for certification path not found](https://pkizerotohero.com/errors/android-trust-anchor-not-found/) ## 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 ### [CSR decoder](https://pkizerotohero.com/tools/csr/) Check a certificate signing request before you send it to a CA. Tool ### [Certificate decoder](https://pkizerotohero.com/tools/decoder/) Paste a PEM certificate and read every field in plain words. ## The big picture: crash course Short lessons of about nine minutes each, with check questions. - [Lesson 6: Chains and trust stores](https://pkizerotohero.com/course/chains-and-trust-stores/) - [Lesson 9: Running PKI](https://pkizerotohero.com/course/running-pki/) - [Lesson 10: Beyond the browser, and what comes next](https://pkizerotohero.com/course/beyond-the-browser/) ## Look it up: glossary terms Every term in plain words, linked to its full entry. - [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 policy (CP)](https://pkizerotohero.com/handbook/glossary/#certificate-policy "A document that sets the rules a CA's certificates follow and what relying parties can expect from them.") - [Certification practice statement (CPS)](https://pkizerotohero.com/handbook/glossary/#cps "A CA's document that describes in detail how it issues, manages and revokes certificates.") - [Client certificate](https://pkizerotohero.com/handbook/glossary/#client-certificate "A certificate that a client, such as a service, device or user, presents to prove its identity to a server in mutual TLS.") - [Cryptoperiod](https://pkizerotohero.com/handbook/glossary/#cryptoperiod "The length of time a key may be used before it must be replaced.") - [Device attestation](https://pkizerotohero.com/handbook/glossary/#device-attestation "A device proving it is genuine hardware from a known manufacturer by signing a fresh challenge with a factory-installed key.") - [Device certificate](https://pkizerotohero.com/handbook/glossary/#device-certificate "A certificate that identifies one physical device, usually installed at the factory with its private key locked in a secure chip.") - [Hardware security module (HSM)](https://pkizerotohero.com/handbook/glossary/#hardware-security-module "A tamper-resistant device that generates and stores private keys and uses them inside, so the keys cannot be copied out.") - [HSM](https://pkizerotohero.com/handbook/glossary/#hsm "Short for hardware security module: a tamper-resistant device that keeps private keys inside and uses them without ever exporting them.") - [IDevID](https://pkizerotohero.com/handbook/glossary/#idevid "Initial Device Identifier: the manufacturer-installed, globally unique identity certificate of a device, defined in IEEE 802.1AR.") - [Key ceremony](https://pkizerotohero.com/handbook/glossary/#key-ceremony "A scripted, witnessed and recorded procedure for creating or using a CA's most important keys, such as a root key.") - [Key escrow](https://pkizerotohero.com/handbook/glossary/#key-escrow "Keeping a protected copy of a key with a trusted party so that it can be recovered, for example to read old encrypted data.") - [LDevID](https://pkizerotohero.com/handbook/glossary/#ldevid "Locally significant Device Identifier: a device certificate issued by the owner's own CA, defined in IEEE 802.1AR.") - [Mutual TLS (mTLS)](https://pkizerotohero.com/handbook/glossary/#mutual-tls "TLS in which the client also presents a certificate and proves its private key, so both sides are authenticated.") - [Name Constraints](https://pkizerotohero.com/handbook/glossary/#name-constraints "A CA certificate extension that limits which names its certificates may contain, such as only names under example.com.") - [Offline root CA](https://pkizerotohero.com/handbook/glossary/#offline-root-ca "A root CA whose private key is kept on a device that is never connected to a network and is used only in key ceremonies.") - [Private CA](https://pkizerotohero.com/handbook/glossary/#private-ca "A certificate authority run by an organisation for its own systems, trusted only where it has been added to trust stores.") - [Registration authority (RA)](https://pkizerotohero.com/handbook/glossary/#registration-authority "The part of a PKI that checks who is asking for a certificate before the CA issues it.") - [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.") - [Secure element](https://pkizerotohero.com/handbook/glossary/#secure-element "A tamper-resistant chip that generates and stores keys and performs cryptography inside, so the keys cannot be read out.") - [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.") - [Separation of duties](https://pkizerotohero.com/handbook/glossary/#separation-of-duties "Splitting sensitive tasks so that no single person can complete them alone, such as using or restoring a CA key.") - [Service mesh](https://pkizerotohero.com/handbook/glossary/#service-mesh "An infrastructure layer that handles traffic between services, typically giving each service a certificate and using mutual TLS for every call.") - [SPIFFE](https://pkizerotohero.com/handbook/glossary/#spiffe "Secure Production Identity Framework for Everyone: a standard for giving software workloads identities, usually as short-lived X.509 certificates.") - [SSH certificate](https://pkizerotohero.com/handbook/glossary/#ssh-certificate "An OpenSSH key signed by an SSH certificate authority, with a key ID, allowed user or host names and a validity period.") - [SVID](https://pkizerotohero.com/handbook/glossary/#svid "SPIFFE Verifiable Identity Document: the certificate or token that proves a workload's SPIFFE ID.") - [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.") - [TPM](https://pkizerotohero.com/handbook/glossary/#tpm "Trusted Platform Module: a security chip in most PCs and many servers that stores keys and can prove the machine's identity and state.") - [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 on first use (TOFU)](https://pkizerotohero.com/handbook/glossary/#trust-on-first-use "Accepting a key the first time you see it and then warning if it ever changes, as SSH does by default.") - [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.") - [Two-tier PKI](https://pkizerotohero.com/handbook/glossary/#two-tier-pki "A CA hierarchy with an offline root CA that signs one or more online issuing CAs, which issue the end-entity certificates.") - [Workload identity](https://pkizerotohero.com/handbook/glossary/#workload-identity "An identity given to a piece of running software, such as a service or job, rather than to a person or a machine.") ## Other topics - [Certificates](https://pkizerotohero.com/topics/certificates/) - [Chains and trust stores](https://pkizerotohero.com/topics/chains-and-trust/) - [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/) - [Hashes and signatures](https://pkizerotohero.com/topics/signing/) - [Post-quantum cryptography](https://pkizerotohero.com/topics/post-quantum/)