🛡️ A private certificate authority (X.509 & SSH) & ACME server for secure automated certificate management, so you can use TLS everywhere & SSO for SSH.
Find a file
2020-12-18 11:18:42 -05:00
.github Update issue templates 2020-06-18 13:52:16 -07:00
acme Fix broken ValidateChallenge test 2020-12-18 11:18:42 -05:00
api Merge branch 'master' into ssh-cert-templates 2020-08-24 15:08:28 -07:00
authority Recalculate token id instead of validating it. 2020-12-17 14:52:34 -08:00
autocert Use REAMDE.md suggested in code review. 2019-06-18 17:11:29 -07:00
ca Use smallstep/cli-utils instead of smallstep/cli 2020-10-29 13:10:03 -07:00
cas Fix mispell. 2020-11-18 16:57:24 -08:00
cmd Add support for using ssh-agent as a KMS 2020-11-04 09:06:23 +01:00
commands Add initial support for step ca init with cloud cas. 2020-11-18 16:57:24 -08:00
db Fix typos. 2020-10-05 17:20:22 -07:00
debian update year on debian copyright 2020-10-20 22:45:00 -07:00
docker Change HEALTHCHECK to use step ca health. Change shell CMD exec to skip redundant /bin/sh -c 2020-09-08 09:44:35 -07:00
docs [docs] provisioners fix attr dupe and give warning about stale docs 2020-11-18 16:57:24 -08:00
errs Fix error message of bad request 2020-09-10 23:45:44 +09:00
examples Fix example and use ClientCAs. 2020-09-02 15:10:11 -07:00
kms Fix comments, and return an error instead of fatal. 2020-11-18 17:50:21 -08:00
logging Add x5c provisioner capabilities 2019-10-14 14:51:37 -07:00
make Add step-awskms-init to the binary releases. 2020-09-18 11:01:54 -07:00
monitoring ca-component -> certificates 2018-10-31 21:36:01 -07:00
pki Remove unused code. 2020-11-18 16:57:24 -08:00
server ServetTLS => ServeTLS in function docs 2018-12-20 12:10:32 -05:00
templates Use smallstep/cli-utils instead of smallstep/cli 2020-10-29 13:10:03 -07:00
.dockerignore Update Dockerfile.step-ca to match best practices 2020-09-02 11:41:47 -07:00
.gitattributes Added version operability for git archive tarball (non git repo) 2019-02-21 14:51:03 -08:00
.gitignore Add support for TLS-ALPN-01 challenge. 2020-02-07 14:37:13 -05:00
.golangci.yml go mod tidy and golang 1.15.0 cleanup ... 2020-08-17 13:48:37 -07:00
.travis.yml revert to skip_cleanup in travis 2020-08-31 14:28:31 -07:00
.VERSION Added version operability for git archive tarball (non git repo) 2019-02-21 14:51:03 -08:00
.version.sh Added version operability for git archive tarball (non git repo) 2019-02-21 14:51:03 -08:00
CHANGELOG.md first pass at README 2018-11-05 20:37:58 -08:00
distribution.md Fix command in distribution.md. 2020-04-20 17:42:29 -07:00
go.mod Upgrade crypto and fix test. 2020-12-17 14:17:08 -08:00
go.sum Upgrade crypto and fix test. 2020-12-17 14:17:08 -08:00
icon.png Commit icons. 2019-06-12 16:22:39 -07:00
icon.svg Commit icons. 2019-06-12 16:22:39 -07:00
LICENSE Add full version of the license. 2020-05-26 12:21:09 -07:00
Makefile Add step-awskms-init into the builds. 2020-08-19 13:21:14 -07:00
README.md Update READMEs with links to new docs 2020-10-27 16:20:45 -07:00

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:

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

GitHub release CA Image Go Report Card Build Status License CLA assistant

GitHub stars Twitter followers

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.

⚙️ 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:

🏔 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.

👩🏽‍💻 An online SSH Certificate Authority

  • Delegate SSH authentication to step-ca by using SSH certificates instead of public keys and authorized_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

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 control step-ca. While step is not technically required to run step-ca, it is very much recommended.

Debian

  1. 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
    
  2. 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.

  • The step binary tarball can be found here.
  • The step-ca binary tarball can be found here.

You can use pacman to install the packages.

RHEL/CentOS

  1. 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
    
  2. 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.

Animated terminal showing step certificates in practice

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:

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:

  1. On the web at https://smallstep.com/docs/step-ca.

  2. On the command line with step help ca xxx where xxx is the subcommand you are interested in. Ex: step help ca provisioner list.

  3. In your browser, by running step help --http=:8080 ca from the command line and visiting http://localhost:8080.

  4. The docs folder is being deprecated, but it still has some documentation and tutorials.

Feedback?