mirror of https://github.com/smallstep/certificates.git synced 2024-11-17 15:29:21 +00:00

Miclain K Keffeler 195cdd664a

2020-06-03 08:57:35 -05:00

20 KiB

Raw Blame History

Step Certificates

An online certificate authority and related tools for secure automated certificate management, so you can use TLS everywhere.

This repository is for step-ca, a certificate authority that exposes an API for automated certificate management. It also contains a golang SDK for interacting with step-ca programatically. However, you'll probably want to use the step command-line tool to operate step-ca and get certificates, instead of using this low-level SDK directly.

Questions? Find us on gitter.

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

Features

It's super easy to get started and to operate step-ca thanks to streamlined initialization and safe, sane defaults. Get started in 15 minutes.

A private certificate authority you run yourself

Issue client and server certificates to VMs, containers, devices, and people using internal hostnames and emails
RFC5280 and CA/Browser Forum compliant certificates that work for TLS and HTTPS
Choose key types (RSA, ECDSA, EdDSA) & lifetimes to suit your needs
Short-lived certificates with fully automated enrollment, renewal, and revocation
Fast, stable, and capable of high availability deployment using root federation and/or multiple intermediaries
Operate as an online intermediate for an existing root CA
Pluggable database backends for persistence
Helm charts, autocert, and cert-manager integration for kubernetes

Lots of (automatable) ways to get certificates

Single sign-on using Okta, GSuite, Active Directory, or any other OAuth OIDC identity provider
Instance identity documents for VMs on AWS, GCP, and Azure
Single-use short-lived tokens issued by your CD tool — Puppet, Chef, Ansible, Terraform, etc.
Use an existing certificate from another CA (e.g., using a device certificate like Twilio's Trust OnBoard) coming soon

Your own private ACME Server

Issue certificates using ACMEv2 (RFC8555), the protocol used by Let's Encrypt
Great for using ACME in development & pre-production
Supports the http-01, tls-alpn-01, and dns-01 ACME challenge types
Works with any compliant ACME client including certbot, acme.sh, Caddy, and traefik
Get certificates programmatically (e.g., in Go, Python, Node.js)

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

Generate key pairs where they're needed so private keys are never transmitted across the network
Authenticate and obtain a certificate using any enrollment mechanism supported by step-ca
Securely distribute root certificates and bootstrap PKI relying parties
Renew and revoke certificates issued by step-ca
Install root certificates so your CA is trusted by default (issue development certificates that work in browsers)
Inspect and lint certificates

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.

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.

While step is not required to run step-ca, it will make your life easier so you'll probably want to install it too.

Mac OS

Install step and step-ca together via Homebrew:

$ brew install step

# Test installation ...
$ step certificate inspect https://smallstep.com
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 326381749415081530968054238478851085504954 (0x3bf265673332db2d0c70e48a163fb7d11ba)
    Signature Algorithm: SHA256-RSA
        Issuer: C=US,O=Let's Encrypt,CN=Let's Encrypt Authority X3
...

Note: If you have installed step previously through the smallstep/smallstep tap you will need to run the following commands before installing:
$ brew untap smallstep/smallstep
$ brew uninstall step

Linux

Debian

[Optional] Install step.

Download the latest Debian package from step releases:

$ 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 latest Debian package from releases:

$ 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

There are a few subtle yet important things to getting this setup, at the time of this writing the package cannot be installed via yum (its a feature request). So this is how we setup this on RHEL following some best practices.

[Required] Install step.

Download the latest Linux package from step releases:

$ wget -O step-cert.tar.gz https://github.com/smallstep/cli/releases/download/vX.Y.Z/step_linux_X.Y.Z_amd64.tar.gz

Install the Package by unzipping in bin:

$ tar -xf step.tar.gz
$ cd step-_X.Y.Z/bin/
$ mv step /usr/bin

Install step-ca.

Download the latest Linux package from releases:

$ 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 the Package by unzipping in bin:

$ tar -xf step-ca.tar.gz
$ cd step-certificates_X.Y.Z/bin/
$ mv step-ca /usr/bin

Now your users can call the step and step-ca commands, create a 'smallstep' user that doesn't have login permitted and will only be used as a service user for systemctl to manage this service.
```
$ useradd smallstep
$ passwd -l smallstep
```
This creates a home directory for smallstep, as root sudo to the smallstep user, and perform the getting-started steps to setup the CA on this box as that user, we chose to put the password in a file in this example but you can mess with other solutions, we then made this systemctl service file
```
[Unit]
Description=Smallstep
After=syslog.target network.target

[Service]

User=smallstep
Group=smallstep
ExecStart=/bin/sh -c '/bin/step-ca /home/smallstep/.step/config/ca.json --password-file=/home/smallstep/.step/pwd >>   /var/log/smallstep/output.log 2>&1'
Type=simple
Restart=on-failure
RestartSec=10


[Install]
WantedBy=multi-user.target
```
This also assumes you want logs going to a log file (we don't have a log rotation strategy at this time, perhaps the community can contribute :)

To setup this, perform the following
```
$ mkdir /var/log/smallstep
$ chown -R smallstep:smallstep /var/log/smallstep
```
Then do the following to startup the service.
```
$ systemctl status smallstep
$ systemctl enable smallstep (startup on reboot automatically)
$ systemctl start smallstep
```

If you have issues, you can debug by grabbing the execStart command from systemctl, sudo to smallstep, and start seeing what it is complaining about.

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:

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 getting started 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:

The docs sub-repo has an index of documentation and tutorials.
On the command line with step help ca xxx where xxx is the subcommand you are interested in. Ex: step help ca provisioner list.
On the web at https://smallstep.com/docs/certificates.
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.

20 KiB Raw Blame History