🛡️ 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
Carl Tashian 8b0da33e27
Merge pull request #313 from smallstep/readme-update
First stab at a README update 😱
2020-07-13 09:45:21 -05:00
.github Update issue templates 2020-06-18 13:52:16 -07:00
acme wip 2020-06-24 09:58:40 -07:00
api A few last fixes and tests added for rekey/renew ... 2020-07-09 12:11:40 -07:00
authority A few last fixes and tests added for rekey/renew ... 2020-07-09 12:11:40 -07:00
autocert Use REAMDE.md suggested in code review. 2019-06-18 17:11:29 -07:00
ca wip 2020-06-23 11:10:45 -07:00
cmd Move load of kms to main package. 2020-06-12 14:55:35 -07:00
commands Fix formatting. 2020-02-12 12:45:07 -08:00
db ValueLogLoadingMode -> FileLoading Mode badger 2020-04-20 16:09:07 -07:00
debian Added version operability for git archive tarball (non git repo) 2019-02-21 14:51:03 -08:00
docker Let step-ca bind to ports < 1024 2020-02-06 12:35:40 +00:00
docs Add github response to frequenty asked questions doc 2020-07-08 15:18:30 -07:00
errs Simplify statuscoder error generators. 2020-01-28 13:29:40 -08:00
examples Added example for custom claims (#39) 2019-03-22 12:16:56 -07:00
kms Move load of kms to main package. 2020-06-12 14:55:35 -07:00
logging Add x5c provisioner capabilities 2019-10-14 14:51:37 -07:00
make Simplify make bundling and generate ARM tarballs. 2020-04-08 14:20:58 -07:00
monitoring ca-component -> certificates 2018-10-31 21:36:01 -07:00
pki Move default templates to the template package. 2020-06-16 17:24:47 -07:00
server ServetTLS => ServeTLS in function docs 2018-12-20 12:10:32 -05:00
sshutil ssh/api: Use host tags instead of groups 2020-04-03 12:11:19 -07:00
templates Add omitempty to requires property. 2020-06-16 19:03:33 -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 Simplify statuscoder error generators. 2020-01-28 13:29:40 -08:00
.travis.yml Use Go 1.14. 2020-05-20 17:45:57 -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 Use smallstep/cli v0.14.6 2020-07-02 13:55:00 -07:00
go.sum Use smallstep/cli v0.14.6 2020-07-02 13:55:00 -07: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 initialization script for an AWS KMS. 2020-05-19 17:35:58 -07:00
README.md First stab at a README update 😱 2020-07-08 18:42:43 -07:00

Step Certificates

step-ca is an online certificate authority for secure, automated certificate management.

You can use it to:

  • Issue X.509 certificates for all of your internal infrastructure
  • Enable mutual TLS for encryption and authentication to your VMs, containers, devices, databases, APIs, and anything else you can think of, using internal hostnames
  • Issue SSH certificates in exchange for single sign-on tokens and cloud instance identity documents.
  • Easily automate certificate management with any ACME v2 client
  • And do a lot more...

It's easy to use and hard to misuse, thanks to safe, sane defaults.

For automation, step-ca has full ACME v2 support, a JSON API, and a Go wrapper.

For human use, step-ca has a command line counterpart: the step CLI tool.

Questions? Find us on gitter.

Website | Documentation | Installation Guide | Quickstart | Getting Started | Contribution Guide

GitHub release Join the chat at https://gitter.im/smallstep/community CA Image Go Report Card Build Status License CLA assistant

GitHub stars Twitter followers

Animated terminal showing step certificates in practice

Features

A fast, stable, private CA you run yourself

  • Issue certificates for VMs, containers, devices, databases, APIs, and anything else you can think of, using internal hostnames.
  • Issue TLS and SSH certificates for people, using their emails.
  • Certificates work with TLS and HTTPS (they are RFC5280 and CA/Browser Forum compliant).
  • Choose key types (RSA, ECDSA, EdDSA) & lifetimes to suit your needs
  • Kubernetes helm charts, autocert, and cert-manager integration
  • Short-lived certificates with automated enrollment, renewal, and revocation
  • Capable of high availability (HA) deployment using root federation and/or multiple intermediaries
  • Operate as an online intermediate for an existing root CA
  • Pluggable database backends for persistence

Lots of (automatable) ways to get certificates

Configure the CA to issue certificates in exchange for:

Your own private ACME server

ACME is the protocol used by Let's Encrypt. It's super easy to issue certificates to any ACMEv2 (RFC8555) client.

SSH Certificates

  • Use certificate authentication for SSH: connect SSH to SSO, improve security, and eliminate warnings & errors
  • Issue SSH user certificates using OAuth OIDC
  • Issue SSH host certificates to cloud VMs using instance identity documents

Easy certificate management and automation via step CLI integration

Motivation

Managing your own public key infrastructure (PKI) can be tedious and error prone. Good security hygiene is hard. Setting up simple PKI is out of reach for many small teams, and following best practices like proper certificate revocation and rolling is challenging even for experts.

Amongst numerous use cases, proper PKI makes it easy to use mTLS (mutual TLS) to improve security and to make it possible to connect services across the public internet. Unlike VPNs & SDNs, deploying and scaling mTLS is pretty easy. You're (hopefully) already using TLS, and your existing tools and standard libraries will provide most of what you need. If you know how to operate DNS and reverse proxies, you know how to operate mTLS infrastructure.

Connect it all with
mTLS

There's just one problem: you need certificates issued by your own certificate authority (CA). Building and operating a CA, issuing certificates, and making sure they're renewed before they expire is tricky. This project provides the infrastructure, automations, and workflows you'll need.

step certificates is part of smallstep's broader security architecture, which makes it much easier to implement good security practices early, and incrementally improve them as your system matures.

For more information and docs see the smallstep website and the blog post announcing this project.

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: While the step CLI tool is not required to run step-ca, it will make your life easier so you'll probably want to install it too.

Debian

  1. [Optional] 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.

  • [Optional] 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. [Optional] 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/cli/releases/download/vX.Y.Z/step_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.

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:

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. The docs sub-repo has an index of documentation and tutorials.

  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. On the web at https://smallstep.com/docs/certificates.

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

The Future

We plan to build more tools that facilitate the use and management of zero trust networks.

  • 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 what features you'd like to see - open issues or hit us on Twitter.

Further Reading

Check out the Getting Started guide for more examples and best practices on running Step CA in production.