This document defines and describes certificate authority core concepts that are integral to the design
and practical usage of step-ca
.
Readers who are not yet familiar with public key infrastructure (PKI) and certificate management may want to check out...
When referring to Certificate Authorities (CAs), offline generally means
air-gapped or network isolated. However, the term offline has a different
meaning in the context of step-ca
. When step-ca
is online (using the
step-ca
server) it is responding to network requests. But step-ca
can
also operate "offline", without the step-ca
server, by accessing the signing
keys locally. We call this static, non-daemonized operation offline mode. Any
further use of the term offline in these docs will refer to offline mode in
the context of step-ca
(local access only).
Our tools support three modes of generating and operating a Certificate Authority (CA):
step-ca
daemon and step ca
subcommand (docs here).step ca
subcommand with --offline
.step certificate
subcommand
(docs here).It's not always practical or desirable to run an online CA.
Smallstep provides the means to create certificates without step-ca
running.
step-cli
offline mode leverages the CA's configuration, which must be available locally, to issue certificates.
$ step ca init --name "Local CA" --provisioner admin --dns localhost --address ":443"
$ step ca certificate --offline foo.smallstep.com foo.crt foo.key
step-cli
can also generate bootstrap tokens in offline mode and exchange them with a running CA for a certificate.
This workflow is useful when generating tokens on a host without direct access to the running CA.
$ TOKEN=$(step ca token --offline foo.smallstep.com)
$ step ca certificate --token=$TOKEN foo.smallstep.com foo.crt foo.key
The certificate signing API exposed by step-ca
requires mutual
authentication. The CA authenticates to the client using a certificate (which
the client verifies using the root certificate created during CA initialization).
But the client must also authenticate to the CA. Again, this
presents a challenge: the client obviously can't use a certificate for
authentication because it doesn't have one yet.
To verify the legitimacy of certificate signing requests, we need some entity that the CA trusts to measure and attest to the identity of our workloads. In the step certificates architecture this entity is called a provisioner, because it helps to provision certificates.
In general, once a provisioner authenticates a workload's identity it issues the workload a bearer token to submit to the CA, along with a certificate signing request (CSR), to obtain a certificate. The bearer token authenticates the workload and authorizes the certificate request.
The details of how a provisioner interacts with a workload (or device or person) and the CA vary by provisioner type. Smallstep supports a number of provisioner types including:
On the public internet, sometimes HTTPS certificates need to be revoked before they expire. Over the years, there have been several methods for actively revoking HTTPS certificates. Any approach to solving this problem adds complexity to the PKI—usually in the form of additional network requests. For example, a web browser might need to fetch a Certificate Revocation List (CRL) from a URL embedded in an HTTPS certificate so it can make sure the certificate, which would otherwise be valid, has not been actively revoked by a trusted authority.
When designing a private PKI, you can make things a lot simpler and more decentralized. If you make certificate lifetimes short enough, you can passively revoke a certificate by letting it expire and making sure the Certificate Authority knows to reject any attempts to renew it.