One could write several telephone books about the innards of X.509, asn.1 and the vast topics of infosec, netsec, and public key cryptography that are implicated in the design of a PKI. It's daunting. So let's begin at the beginning, with a CA server and a TLS-enabled "Hello World" application.
Note that one of the prompts is about the default provisioner, but for now an email address works fine as an identifier.
$step ca init✔ What would you like to name your new PKI? (e.g. Smallstep): Example Inc.
✔ What DNS names or IP addresses would you like to add to your new CA? (e.g. ca.smallstep.com[,22.214.171.124,etc.]): localhost
✔ What address will your new CA listen at? (e.g. :443): 127.0.0.1:8443
✔ What would you like to name the first provisioner for your new CA? (e.g. email@example.com): firstname.lastname@example.org
✔ What do you want your password to be? [leave empty and we will generate one]: abc123
Generating root certificate...
Generating intermediate certificate...
✔ Root certificate: /Users/bob/.step/certs/root_ca.crt
✔ Root private key: /Users/bob/.step/secrets/root_ca_key
✔ Root fingerprint: 702a094e239c9eec6f0dcd0a5f65e595bf7ed6614012825c5fe3d1ae1b2fd6ee
✔ Intermediate certificate: /Users/bob/.step/certs/intermediate_ca.crt
✔ Intermediate private key: /Users/bob/.step/secrets/intermediate_ca_key
✔ Default configuration: /Users/bob/.step/config/defaults.json
✔ Certificate Authority configuration: /Users/bob/.step/config/ca.json
Your PKI is ready to go.
Make a note of the root fingerprint! You'll need it to establish trust with your CA from other environments or hosts.
Run your certificate authority
Run your certificate authority and pass it the configuration file you just generated.
$step-ca$(step path)/config/ca.jsonPlease enter the password to decrypt /Users/bob/.step/secrets/intermediate_ca_key: abc123
2019/02/18 13:28:58 Serving HTTPS on 127.0.0.1:8443 ...
Accessing your Certificate Authority
Accessing your CA
You can use step ca and step ssh command groups to interact with the CA. See Basic CA Operations for an overview of common operations.
Because your CA root certificate is a self-signed certificate, it is not automatically trusted by clients.
Any new step client will need to establish a trust relationship with your CA.
You can do this by supplying your CA fingerprint to step ca bootstrap.
Your CA fingerprint is a cryptographic signature identifying your root CA certificate.
To configure step to access your CA from a new machine, run:
$step ca bootstrap --ca-url [CA URL] --fingerprint [CA fingerprint]The root certificate has been saved in /home/alice/.step/certs/root_ca.crt.
Your configuration has been saved in /home/alice/.step/config/defaults.json.
This command will download the root CA certificate and write CA connection details to $HOME/.step/config/defaults.json. The step command will now trust your CA. See Basic CA Operations for an overview of common operations.
Don't know your CA fingerprint?
You can get it by running the following on your CA:
You may also wish to establish system-wide trust of your CA, so your certificates will be trusted by curl and other programs. Use the step certificate install command to install your root CA certificate into your system's trust store:
$step certificate install$(step path)/certs/root_ca.crtCertificate /home/alice/.step/certs/root_ca.crt has been installed.
X.509v3 Root CA Certificate (ECDSA P-256) [Serial: 2282...6360]
Subject: Example Inc. Root CA
Issuer: Example Inc. Root CA
Valid from: 2021-05-11T21:40:19Z
Example: Run A Local Web Server Using TLS
Now that the certificate authority is running, let's create an example server and use our new certificate authority to issue an X.509 certificate and connect to the server using HTTP over TLS.
For this example, you'll need to have go installed.
Get a certificate
First, let's ask the CA for a certificate (srv.crt) and private key (srv.key) for our example server on localhost:
$step ca certificate localhost srv.crt srv.key✔ Key ID: rQxROEr7Kx9TNjSQBTETtsu3GKmuW9zm02dMXZ8GUEk (email@example.com)
✔ Please enter the password to decrypt the provisioner key: abc123
✔ CA: https://localhost:8443/1.0/sign
✔ Certificate: srv.crt
✔ Private Key: srv.key
Run a hello world example server configured for TLS connections
We've got our certificate. Now let's create an example server that will run on localhost and use TLS.
This example server listens to port 9443 and serves Hello, world! to any client that accepts the server certificate as trusted.
First, let's try making a curl request to our example server. In a new terminal, run:
If you already ran step certificate install to install your root CA into your system's trust store, this command will work and you'll see "Hello, World!".
If not, you'll see this error:
curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.haxx.se/docs/sslcerts.html
curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.
In this case, curl does not yet trust your root CA.
Let's download the CA's root certificate and pass it into curl to establish trust.
$step ca root root.crtThe root certificate has been saved in root.crt.
Now you can make a curl request using the root certificate you just downloaded. When you add --cacert root.crt to the curl command, it will verify that the server certificate was signed by the CA, and at that point you will see Hello, world!