Skip to content
Module 03

Issue and inspect certificates with step CLI

Request server and client certificates, read every field, and verify chains.

ToolsBeginner 25 min

Your CA from module 2 is running. Now put it to work. You’ll get a server certificate and a client certificate, read every field, and check the chain the way a browser does.

Keep the CA running in its own terminal. Do this lesson in a second terminal.

Three things happen when you run step ca certificate:

  1. step makes a key pair on your machine. The private key never leaves your computer. The CA never sees it.
  2. step builds a CSR. A certificate signing request holds your new public key and the names you want. step signs it with the new private key, which proves you hold that key.
  3. The CA checks your right to ask. Your provisioner password unlocks a short-lived token. The CA checks the token, signs the certificate and sends it back.

That split is the point. The CA vouches for the public key. Only you hold the private key.

terminal
mkdir -p ~/pki-lab/issue && cd ~/pki-lab/issue

On the CA machine, step is already configured. A laptop or server is not. It needs your root certificate, and it must be sure it got the real one.

step ca bootstrap downloads the root and compares its fingerprint with the one you type. If they don’t match, it stops.

Print your root fingerprint:

terminal
step certificate fingerprint $(step path)/certs/root_ca.crt
Expected output
0681c596b1048ed34c10c4f1e67aff7c79b0a411e092f146edd3e75618f19bd5

Your fingerprint is different. Use yours in the next step.

Pretend to be a new laptop. Point STEPPATH at an empty folder, then bootstrap:

terminal
STEPPATH=~/pki-lab/laptop step ca bootstrap \
--ca-url https://localhost:9000 \
--fingerprint <your-fingerprint>
Expected output
The root certificate has been saved in /home/ubuntu/pki-lab/laptop/certs/root_ca.crt.
The authority configuration has been saved in /home/ubuntu/pki-lab/laptop/config/defaults.json.

STEPPATH tells step where to keep its files. Here it keeps the “laptop” apart from your CA’s own ~/.step folder.

Ask for a certificate for web.example.com. Add localhost and 127.0.0.1 so you can test it on this machine.

terminal
step ca certificate web.example.com web.crt web.key \
--san web.example.com --san localhost --san 127.0.0.1

Enter the provisioner password when asked.

Expected output
✔ Provisioner: admin@example.com (JWK) [kid: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E]
✔ CA: https://localhost:9000
✔ Certificate: web.crt
✔ Private Key: web.key

When you add any --san flag, you must list every name you want. The first argument becomes the Common Name, but only the SAN list counts.

terminal
step certificate inspect web.crt --short
Expected output
X.509v3 TLS Certificate (ECDSA P-256) [Serial: 3354...0265]
Subject: web.example.com
localhost
127.0.0.1
Issuer: Lab CA Intermediate CA
Provisioner: admin@example.com [ID: Cd7t...AS_E]
Valid from: 2026-11-16T03:57:38Z
to: 2026-11-17T03:58:38Z

Two details are worth a look:

  • 24 hours and one minute. step-ca gives 24-hour certificates by default. It also starts them one minute early, so a client with a slow clock still accepts them.
  • The issuer is the intermediate, not the root. The root stays out of daily work.
terminal
step certificate inspect web.crt
Expected output (excerpt)
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 335496621798848314673034230938666930265 (0xfc664c8c5552ce773eca4b6759b61059)
Signature Algorithm: ECDSA-SHA256
Issuer: O=Lab CA,CN=Lab CA Intermediate CA
Validity
Not Before: Nov 16 03:57:38 2026 UTC
Not After : Nov 17 03:58:38 2026 UTC
Subject: CN=web.example.com
Subject Public Key Info:
Public Key Algorithm: ECDSA
Public-Key: (256 bit)
Curve: P-256
...
X509v3 extensions:
X509v3 Key Usage: critical
Digital Signature
X509v3 Extended Key Usage:
Server Authentication, Client Authentication
X509v3 Subject Key Identifier:
1D:0C:70:2A:2D:99:82:95:9D:36:85:4C:2E:F7:B8:1A:41:BF:64:97
X509v3 Authority Key Identifier:
1B:7A:83:36:88:1C:E2:E6:78:50:0A:39:5F:5D:68:AC:A5:7F:9B:F0
X509v3 Subject Alternative Name:
DNS:web.example.com, DNS:localhost
IP Address:127.0.0.1
X509v3 Step Provisioner:
Type: JWK
Name: admin@example.com
CredentialID: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E
Signature Algorithm: ECDSA-SHA256
...

Here is what each part means:

Field What it tells you
Serial Number A unique number from this CA. Revocation lists use it.
Signature Algorithm How the CA signed this certificate. Here, ECDSA with SHA-256.
Issuer The CA that signed it.
Validity The window when clients accept it. Outside it, the certificate is dead.
Subject The Common Name. Kept for humans and old software.
Subject Public Key Info The public key this certificate vouches for.
Key Usage What the key may do. Digital Signature is what TLS needs. critical means software that doesn’t understand it must reject the certificate.
Extended Key Usage The jobs it may do. Server Authentication for TLS servers, Client Authentication for mTLS clients.
Subject / Authority Key Identifier Hashes that link this certificate to its issuer. They help clients find the right intermediate fast.
Subject Alternative Name The names this certificate is valid for. This is the field clients check.
Step Provisioner A step-ca extension that records which provisioner issued it. Other software ignores it.

Count the certificates in web.crt:

terminal
grep -c "BEGIN CERTIFICATE" web.crt
Expected output
2

step-ca returns the leaf and the intermediate. Show both:

terminal
step certificate inspect web.crt --bundle --short
Expected output
X.509v3 TLS Certificate (ECDSA P-256) [Serial: 3354...0265]
Subject: web.example.com
localhost
127.0.0.1
Issuer: Lab CA Intermediate CA
Provisioner: admin@example.com [ID: Cd7t...AS_E]
Valid from: 2026-11-16T03:57:38Z
to: 2026-11-17T03:58:38Z
X.509v3 Intermediate CA Certificate (ECDSA P-256) [Serial: 1455...6432]
Subject: Lab CA Intermediate CA
Issuer: Lab CA Root CA
Valid from: 2026-11-16T03:58:14Z
to: 2036-11-13T03:58:14Z

Read it top to bottom. Each issuer is the subject of the next certificate. That is the chain.

Root CAoffline, self-signedIntermediate CAsigns dailyLeaf certificateapi.example.comsignssigns

You’ll meet OpenSSL everywhere, so learn to read its output too.

terminal
openssl x509 -in web.crt -noout -subject -issuer -dates -ext subjectAltName,extendedKeyUsage
Expected output
subject=CN = web.example.com
issuer=O = Lab CA, CN = Lab CA Intermediate CA
notBefore=Nov 16 03:57:38 2026 GMT
notAfter=Nov 17 03:58:38 2026 GMT
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication
X509v3 Subject Alternative Name:
DNS:web.example.com, DNS:localhost, IP Address:127.0.0.1

A client certificate names a person or device. Use an email address as the name:

terminal
step ca certificate alice@example.com alice.crt alice.key
Expected output
✔ Provisioner: admin@example.com (JWK) [kid: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E]
✔ CA: https://localhost:9000
✔ Certificate: alice.crt
✔ Private Key: alice.key

Check the name type:

terminal
openssl x509 -in alice.crt -noout -ext subjectAltName
Expected output
X509v3 Subject Alternative Name:
email:alice@example.com

step saw the @ and made an email SAN, not a DNS name. The default step-ca template puts both Server and Client Authentication in the EKU. In module 5 you’ll see why a stricter template is better.

9. Check that a key matches its certificate

Section titled “9. Check that a key matches its certificate”

A certificate and key that don’t match cause confusing TLS errors. Compare the public keys:

terminal
step certificate key web.crt
terminal
step crypto key public web.key
Expected output (both commands)
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhOHHmMiJjgHx6dizo1kfWtqfWZcp
+MfAapuz67cF1vCcVbBiJV4+XTCI03UixNs7OGZhX3mmxzwgCZmlkXCzhw==
-----END PUBLIC KEY-----

Same output means they belong together.

step certificate verify does what a TLS client does. It builds the chain to a root you trust, checks each signature and date, and checks the name.

terminal
step certificate verify web.crt \
--roots $(step path)/certs/root_ca.crt \
--host web.example.com

The command prints nothing. Check the exit code:

terminal
echo $?
Expected output
0

Zero means the certificate passed every check.

Each failure below is one you’ll meet in real life. Read the error first, then the fix.

terminal
step certificate verify web.crt \
--roots $(step path)/certs/root_ca.crt \
--host shop.example.com
Expected output
failed to verify certificate: x509: certificate is valid for web.example.com, localhost, not shop.example.com

The chain is fine. The name is not in the SAN list. Fix: issue a new certificate that lists the name.

Make a copy that holds only the leaf:

terminal
awk '/BEGIN/{n++} n==1' web.crt > leaf-only.crt

Verify it:

terminal
step certificate verify leaf-only.crt \
--roots $(step path)/certs/root_ca.crt \
--host web.example.com
Expected output
failed to verify certificate: x509: certificate signed by unknown authority

The client can’t connect the leaf to the root without the intermediate. This is one of the most common server misconfigurations. Fix: always serve the full bundle, leaf first.

Any root that didn’t sign the chain fails the same way. If you made a second CA while you experimented, try its root:

terminal
step certificate verify web.crt \
--roots ~/other-ca/root_ca.crt \
--host web.example.com
Expected output
failed to verify certificate: x509: certificate signed by unknown authority (possibly because of "x509: ECDSA verification failure" while trying to verify candidate authority certificate "Lab CA Root CA")

The names match, but the signature doesn’t. A root with the same name is not the same root. Trust comes from the key, not the label.

Ask for a two-day certificate:

terminal
step ca certificate api.example.com api.crt api.key --not-after 48h
Expected output
✔ Provisioner: admin@example.com (JWK) [kid: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E]
✔ CA: https://localhost:9000
The request was forbidden by the certificate authority: requested duration of 48h1m0s is more than the authorized maximum certificate duration of 24h1m0s.
Re-run with STEPDEBUG=1 for more info.

The CA enforces policy, not the client. Shorter is allowed, so --not-after 2h works. The provisioner’s maxTLSCertDuration setting raises the limit.

  • A laptop-style config that trusts your CA through its fingerprint.
  • A server certificate for web.example.com, localhost and 127.0.0.1.
  • A client certificate for alice@example.com.
  • A habit: read the SAN, the EKU and the issuer before you trust anything.

Check yourself

Tap a card to flip it. Nothing is scored or saved.

Progress is saved in this browser only.