.github | ||
acme | ||
api | ||
authority | ||
autocert | ||
ca | ||
cas | ||
cmd | ||
commands | ||
db | ||
debian | ||
docker | ||
docs | ||
errs | ||
examples | ||
kms | ||
logging | ||
make | ||
monitoring | ||
pki | ||
server | ||
systemd | ||
templates | ||
.dockerignore | ||
.gitattributes | ||
.gitignore | ||
.golangci.yml | ||
.travis.yml | ||
.VERSION | ||
.version.sh | ||
CHANGELOG.md | ||
distribution.md | ||
go.mod | ||
go.sum | ||
icon.png | ||
icon.svg | ||
LICENSE | ||
Makefile | ||
README.md |
Step Certificates
step-ca
is an online certificate authority for secure, automated certificate management. It's the server counterpart to the step
CLI tool.
You can use it to:
- Issue X.509 certificates for your internal infrastructure:
- HTTPS certificates that work in browsers (RFC5280 and CA/Browser Forum compliance)
- TLS certificates for VMs, containers, APIs, mobile clients, database connections, printers, wifi networks, toaster ovens...
- Client certificates to enable mutual TLS (mTLS) in your infra. mTLS is an optional feature in TLS where both client and server authenticate each other. Why add the complexity of a VPN when you can safely use mTLS over the public internet?
- Issue SSH certificates:
- For people, in exchange for single sign-on ID tokens
- For hosts, in exchange for cloud instance identity documents
- Easily automate certificate management:
- It's an ACME v2 server
- It has a JSON API
- It comes with a Go wrapper
- ... and there's a command-line client you can use in scripts!
Whatever your use case, step-ca
is easy to use and hard to misuse, thanks to safe, sane defaults.
Questions? Find us in Discussions.
Website | Documentation | Installation Guide | Quickstart | Getting Started | Contributor's Guide
Features
🦾 A fast, stable, flexible private CA
Setting up a public key infrastructure (PKI) is out of reach for many small teams. step-ca
makes it easier.
- Choose key types (RSA, ECDSA, EdDSA) and lifetimes to suit your needs
- Short-lived certificates with automated enrollment, renewal, and passive revocation
- Capable of high availability (HA) deployment using root federation and/or multiple intermediaries
- Can operate as an online intermediate CA for an existing root CA
- Badger, BoltDB, and MySQL database backends
⚙️ Many ways to automate
There are several ways to authorize a request with the CA and establish a chain of trust that suits your flow.
You can issue certificates in exchange for:
- ACME challenge responses from any ACMEv2 client
- OAuth OIDC single sign-on tokens, eg:
- Cloud instance identity documents, for VMs on AWS, GCP, and Azure
- Single-use, short-lived JWK tokens issued by your CD tool — Puppet, Chef, Ansible, Terraform, etc.
- A trusted X.509 certificate (X5C provisioner)
- Expiring SSH host certificates needing rotation (the SSHPOP provisioner)
- Learn more in our provisioner documentation
🏔 Your own private ACME server
ACME is the protocol used by Let's Encrypt to automate the issuance of HTTPS certificates. It's super easy to issue certificates to any ACMEv2 (RFC8555) client.
-
Supports the most popular ACME challenge types:
- For
http-01
, place a token at a well-known URL to prove that you control the web server - For
dns-01
, add aTXT
record to prove that you control the DNS record set - For
tls-alpn-01
, respond to the challenge at the TLS layer (as Caddy does) to prove that you control the web server
- For
-
Works with any ACME client. We've written examples for:
-
Get certificates programmatically using ACME, using these libraries:
lego
for Golang (example usage)- certbot's
acme
module for Python (example usage) acme-client
for Node.js (example usage)
-
Our own
step
CLI tool is also an ACME client! -
See our ACME tutorial for more
👩🏽💻 An online SSH Certificate Authority
- Delegate SSH authentication to
step-ca
by using SSH certificates instead of public keys andauthorized_keys
files - For user certificates, connect SSH to your single sign-on provider, to improve security with short-lived certificates and MFA (or other security policies) via any OAuth OIDC provider.
- For host certificates, improve security, eliminate TOFU warnings, and set up automated host certificate renewal.
🤓 A general purpose PKI tool, via step
CLI integration
- Generate key pairs where they're needed so private keys are never transmitted across the network
- Authenticate and obtain a certificate using any provisioner supported by
step-ca
- Securely distribute root certificates and bootstrap PKI relying parties
- Renew and revoke certificates issued by
step-ca
- Install root certificates on your machine and browsers, so your CA is trusted
- Inspect and lint certificates
Installation Guide
These instructions will install an OS specific version of the step-ca
binary on
your local machine.
Mac OS
Install step
and step-ca
together, via Homebrew:
$ brew install step
Linux
Note: The
step
CLI tool is the easiest way to initialize, configure, and controlstep-ca
. Whilestep
is not technically required to runstep-ca
, it is very much recommended.
Debian
-
Install
step
.Download the Debian package from the latest
step
release:$ wget https://github.com/smallstep/cli/releases/download/vX.Y.Z/step-cli_X.Y.Z_amd64.deb
Install the Debian package:
$ sudo dpkg -i step-cli_X.Y.Z_amd64.deb
-
Install
step-ca
.Download the Debian package from the latest
step-ca
release:$ wget https://github.com/smallstep/certificates/releases/download/vX.Y.Z/step-certificates_X.Y.Z_amd64.deb
Install the Debian package:
$ sudo dpkg -i step-certificates_X.Y.Z_amd64.deb
Arch Linux
We are using the Arch User Repository to distribute
step
binaries for Arch Linux.
You can use pacman to install the packages.
RHEL/CentOS
-
Install
step
.Download the Linux tarball from the latest
step
release:$ wget -O step-cli.tar.gz https://github.com/smallstep/cli/releases/download/vX.Y.Z/step_linux_X.Y.Z_amd64.tar.gz
Install
step
by unzipping and copying the executable over to/usr/bin
:$ tar -xf step-cli.tar.gz $ sudo cp step_X.Y.Z/bin/step /usr/bin
-
Install
step-ca
.Download the Linux package from the latest
step-ca
release:$ wget -O step-ca.tar.gz https://github.com/smallstep/certificates/releases/download/vX.Y.Z/step-certificates_linux_X.Y.Z_amd64.tar.gz
Install
step-ca
by unzipping and copying the executable over to/usr/bin
:$ tar -xf step-ca.tar.gz $ sudo cp step-certificates_X.Y.Z/bin/step-ca /usr/bin
See the systemctl
setup section for a
guide on configuring step-ca
as a daemon.
Kubernetes
We publish helm charts for easy installation on kubernetes:
helm install step-certificates
If you're using Kubernetes, make sure you check out autocert: a kubernetes add-on that builds on
step certificates
to automatically inject TLS/HTTPS certificates into your containers.
Docker
See our Docker getting started guide
Test
$ step version
Smallstep CLI/0.10.0 (darwin/amd64)
Release Date: 2019-04-30 19:01 UTC
$ step-ca version
Smallstep CA/0.10.0 (darwin/amd64)
Release Date: 2019-04-30 19:02 UTC
Quickstart
In the following guide we'll run a simple hello
server that requires clients
to connect over an authorized and encrypted channel using HTTPS. step-ca
will issue certificates to our server, allowing it to authenticate and encrypt
communication.
Let's get started!
Prerequisites
Let's get started!
1. Run step ca init
to create your CA's keys & certificates and configure step-ca
:
$ 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[,1.1.1.1,etc.]): localhost
✔ What address will your new CA listen at? (e.g. :443): 127.0.0.1:8080
✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): bob@example.com
✔ What do you want your password to be? [leave empty and we'll generate one]: abc123
Generating root certificate...
all done!
Generating intermediate certificate...
all done!
✔ Root certificate: /Users/bob/src/github.com/smallstep/step/.step/certs/root_ca.crt
✔ Root private key: /Users/bob/src/github.com/smallstep/step/.step/secrets/root_ca_key
✔ Root fingerprint: 702a094e239c9eec6f0dcd0a5f65e595bf7ed6614012825c5fe3d1ae1b2fd6ee
✔ Intermediate certificate: /Users/bob/src/github.com/smallstep/step/.step/certs/intermediate_ca.crt
✔ Intermediate private key: /Users/bob/src/github.com/smallstep/step/.step/secrets/intermediate_ca_key
✔ Default configuration: /Users/bob/src/github.com/smallstep/step/.step/config/defaults.json
✔ Certificate Authority configuration: /Users/bob/src/github.com/smallstep/step/.step/config/ca.json
Your PKI is ready to go. To generate certificates for individual services see 'step help ca'.
This command will:
- Generate password protected private keys for your CA to sign certificates
- Generate a root and intermediate signing certificate for your CA
- Create a JSON configuration file for
step-ca
(see configuration docs for details)
You can find these artifacts in $STEPPATH
(or ~/.step
by default).
2. Start step-ca
:
You'll be prompted for your password from the previous step, to decrypt the CA's private signing key:
$ step-ca $(step path)/config/ca.json
Please enter the password to decrypt /Users/bob/src/github.com/smallstep/step/.step/secrets/intermediate_ca_key: abc123
2019/02/18 13:28:58 Serving HTTPS on 127.0.0.1:8080 ...
3. Copy our hello world
golang server.
$ cat > srv.go <<EOF
package main
import (
"net/http"
"log"
)
func HiHandler(w http.ResponseWriter, req *http.Request) {
w.Header().Set("Content-Type", "text/plain")
w.Write([]byte("Hello, world!\n"))
}
func main() {
http.HandleFunc("/hi", HiHandler)
err := http.ListenAndServeTLS(":8443", "srv.crt", "srv.key", nil)
if err != nil {
log.Fatal(err)
}
}
EOF
4. Get an identity for your server from the Step CA.
$ step ca certificate localhost srv.crt srv.key
✔ Key ID: rQxROEr7Kx9TNjSQBTETtsu3GKmuW9zm02dMXZ8GUEk (bob@example.com)
✔ Please enter the password to decrypt the provisioner key: abc123
✔ CA: https://localhost:8080/1.0/sign
✔ Certificate: srv.crt
✔ Private Key: srv.key
$ step certificate inspect --bundle srv.crt
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 140439335711218707689123407681832384336 (0x69a7a1d7f6f22f68059d2d9088307750)
Signature Algorithm: ECDSA-SHA256
Issuer: CN=Example Inc. Intermediate CA
Validity
Not Before: Feb 18 21:32:35 2019 UTC
Not After : Feb 19 21:32:35 2019 UTC
Subject: CN=localhost
...
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 207035091234452090159026162349261226844 (0x9bc18217bd560cf07db23178ed90835c)
Signature Algorithm: ECDSA-SHA256
Issuer: CN=Example Inc. Root CA
Validity
Not Before: Feb 18 21:27:21 2019 UTC
Not After : Feb 15 21:27:21 2029 UTC
Subject: CN=Example Inc. Intermediate CA
...
Note that step
and step-ca
handle details like certificate bundling for you.
5. Run the simple server.
$ go run srv.go &
6. Get the root certificate from the Step CA.
In a new Terminal window:
$ step ca root root.crt
The root certificate has been saved in root.crt.
7. Make an authenticated, encrypted curl request to your server using HTTP over TLS.
$ curl --cacert root.crt https://localhost:8443/hi
Hello, world!
All Done!
Check out the Getting Started guide for more examples and best practices on running Step CA in production.
Documentation
Documentation can be found in a handful of different places:
-
On the web at https://smallstep.com/docs/step-ca.
-
On the command line with
step help ca xxx
wherexxx
is the subcommand you are interested in. Ex:step help ca provisioner list
. -
In your browser, by running
step help --http=:8080 ca
from the command line and visiting http://localhost:8080. -
The docs folder is being deprecated, but it still has some documentation and tutorials.
Feedback?
- Tell us what you like and don't like about managing your PKI - we're eager to help solve problems in this space.
- Tell us about a feature you'd like to see! Add a feature request Issue, ask on Discussions, or hit us up on Twitter.