Archives
/
smallstep-certificates
mirror of https://github.com/smallstep/certificates
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated README with features & a bunch of cleanup

Browse Source
pull/97/head
Michael Malone 5 years ago committed by GitHub
parent 5dac2459c3
commit 7c9ab9814f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 177 additions and 157 deletions
Show Stats Download Patch File Download Diff File

334
README.md
Unescape Escape View File

@ -2,6 +2,10 @@
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](https://github.com/smallstep/certificates/tree/master/examples#basic-client-usage) for interacting with `step-ca` programatically. However, you'll probably want to use the [`step` command-line tool](https://github.com/smallstep/cli) to operate `step-ca` and get certificates, instead of using this low-level SDK directly.
**Questions? Find us [on gitter](https://gitter.im/smallstep/community).**
[Website](https://smallstep.com) |
[Documentation](#documentation) |
[Installation Guide](#installation-guide) |
@ -21,6 +25,38 @@ An online certificate authority and related tools for secure automated certifica
![Animated terminal showing step certificates in practice](https://github.com/smallstep/certificates/raw/master/docs/images/step-ca-2-legged.gif)
## Features
It's super easy to get started and to operate `step-ca` thanks to [streamlined initialization](https://github.com/smallstep/certificates#lets-get-started) and [safe, sane defaults](https://github.com/smallstep/certificates/blob/master/docs/defaults.md). **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](https://tools.ietf.org/html/rfc5280) and [CA/Browser Forum](https://cabforum.org/baseline-requirements-documents/) compliant certificates that work **for TLS and HTTPS** (SSH coming soon!)
- Choose key types (RSA, ECDSA, EdDSA) & lifetimes to suit your needs
- [Short-lived certificates](https://smallstep.com/blog/passive-revocation.html) with **fully automated** enrollment, renewal, and revocation
- Fast, stable, and capable of high availability deployment using [root federation](https://smallstep.com/blog/step-v0.8.3-federation-root-rotation.html) and/or multiple intermediaries
- Operate as an online intermediate for an existing root CA
- [Pluggable database backends](https://github.com/smallstep/certificates/blob/master/docs/database.md) for persistence
- [Helm charts](https://hub.helm.sh/charts/smallstep/step-certificates), [autocert](https://github.com/smallstep/autocert), and [cert-manager integration](https://github.com/smallstep/step-issuer) for kubernetes
### Lots of (automatable) ways to get certificates
- [Single sign-on](https://smallstep.com/blog/easily-curl-services-secured-by-https-tls.html) 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](https://smallstep.com/docs/design-doc.html#jwk-provisioner) 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](https://www.twilio.com/wireless/trust-onboard)) *coming soon*
- ACMEv2 (RFC8555) support so you can **run your own private ACME server** *[coming soon](https://github.com/smallstep/certificates/tree/acme)*
### Easy certificate management and automation via [`step` CLI](https://github.com/smallstep/cli) [integration](https://smallstep.com/docs/cli/ca/)
- Generate key pairs where they're needed so private keys are never transmitted across the network
- [Authenticate and obtain a certificate](https://smallstep.com/docs/cli/ca/certificate/) using any enrollment mechanism supported by `step-ca`
- Securely [distribute root certificates](https://smallstep.com/docs/cli/ca/root/) and [bootstrap](https://smallstep.com/docs/cli/ca/bootstrap/) PKI relying parties
- [Renew](https://smallstep.com/docs/cli/ca/renew/) and [revoke](https://smallstep.com/docs/cli/ca/revoke/) certificates issued by `step-ca`
- [Install root certificates](https://smallstep.com/docs/cli/certificate/install/) so your CA is trusted by default (issue development certificates **that [work in browsers](https://smallstep.com/blog/step-v0-8-6-valid-HTTPS-certificates-for-dev-pre-prod.html)**)
- [Inspect](https://smallstep.com/docs/cli/certificate/inspect/) and [lint](https://smallstep.com/docs/cli/certificate/lint/) certificates
## Motivation
Managing your own *public key infrastructure* (PKI) can be tedious and error
@ -49,32 +85,20 @@ need.
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 Step
For more information and [docs](https://smallstep.com/docs) see [the smallstep
website](https://smallstep.com/certificates) and the [blog
post](https://smallstep.com/blog/step-certificates.html) announcing Step
Certificate Authority.
> ## 🆕 Autocert <a href="https://github.com/smallstep/autocert"><img width="50%" src="https://raw.githubusercontent.com/smallstep/autocert/master/autocert-logo.png"></a>
>
> If you're using Kubernetes, make sure you [check out
> autocert](https://github.com/smallstep/autocert): a kubernetes add-on that builds on `step
> certificates` to automatically inject TLS/HTTPS certificates into your containers.
post](https://smallstep.com/blog/step-certificates.html) announcing this project.
## Installation Guide
These instructions will install an OS specific version of the `step-ca` binary on
your local machine.
> NOTE: While `step` is not required to run the Step Certificate Authority (CA)
> we strongly recommend installing both `step cli` and `step certificates`
> because the Step CA is much easier to initialize, manage, and debug using
> the `step cli` toolkit.
While `step` is not required to run `step-ca`, it will make your life easier so you'll probably want to [install it](https://github.com/smallstep/cli#installation-guide) too.
### Mac OS
Install `step` via [Homebrew](https://brew.sh/). The
[Homebrew Formula](https://github.com/Homebrew/homebrew-core/blob/master/Formula/step.rb)
installs both `step cli` and `step certificates`.
Install `step` and `step-ca` together via [Homebrew](https://brew.sh/):
<pre><code>
<b>$ brew install step</b>
@ -101,10 +125,10 @@ $ brew uninstall step
#### Debian
1. [Optional] Install `step cli`.
1. [Optional] Install `step`.
Download the latest Debian package from
[`step cli` releases](https://github.com/smallstep/cli/releases):
[`step` releases](https://github.com/smallstep/cli/releases):
```
$ wget https://github.com/smallstep/cli/releases/download/X.Y.Z/step_X.Y.Z_amd64.deb
@ -116,10 +140,9 @@ $ brew uninstall step
$ sudo dpkg -i step_X.Y.Z_amd64.deb
```
2. Install `step certificates`.
2. Install `step-ca`.
Download the latest Debian package from
[`step certificates` releases](https://github.com/smallstep/certificates/releases):
Download the latest Debian package from [releases](https://github.com/smallstep/certificates/releases):
```
$ wget https://github.com/smallstep/certificates/releases/download/X.Y.Z/step-certificates_X.Y.Z_amd64.deb
@ -136,29 +159,43 @@ $ brew uninstall step
We are using the [Arch User Repository](https://aur.archlinux.org) to distribute
`step` binaries for Arch Linux.
* [Optional] The `step-cli` binary tarball can be found [here](https://aur.archlinux.org/packages/step-cli-bin/).
* [Optional] The `step` binary tarball can be found [here](https://aur.archlinux.org/packages/step-cli-bin/).
* The `step-ca` binary tarball can be found [here](https://aur.archlinux.org/packages/step-ca-bin/).
You can use [pacman](https://www.archlinux.org/pacman/) to install the packages.
### Kubernetes
We publish [helm charts](https://hub.helm.sh/charts/smallstep/step-certificates) for easy installation on kubernetes:
```
helm install step-certificates
```
> <a href="https://github.com/smallstep/autocert"><img width="25%" src="https://raw.githubusercontent.com/smallstep/autocert/master/autocert-logo.png"></a>
>
> If you're using Kubernetes, make sure you [check out
> autocert](https://github.com/smallstep/autocert): a kubernetes add-on that builds on `step
> certificates` to automatically inject TLS/HTTPS certificates into your containers.
### Test
<pre><code>
<b>$ step version</b>
Smallstep CLI/0.8.5 (darwin/amd64)
Release Date: 2019-02-13 22:17 UTC
Smallstep CLI/0.10.0 (darwin/amd64)
Release Date: 2019-04-30 19:01 UTC
<b>$ step-ca version</b>
Smallstep CA/0.8.4 (darwin/amd64)
Release Date: 2019-02-18 18:56 UTC
Smallstep CA/0.10.0 (darwin/amd64)
Release Date: 2019-04-30 19:02 UTC
</code></pre>
## Quickstart
In the following guide we'll run a simple `hello` server that requires clients
to connect over an authorized and encrypted channel (HTTP over TLS). The Step
Certificate Authority (CA) will issue an identity dial tone to our server
enabling it to authenticate and encrypt communication. Let's get started!
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
@ -167,152 +204,135 @@ enabling it to authenticate and encrypt communication. Let's get started!
### Let's get started!
1. Initialize and run the Step CA.
#### 1. Run `step ca init` to create your CA's keys & certificates and configure `step-ca`:
<pre><code>
<b>$ step ca init</b>
✔ What would you like to name your new PKI? (e.g. Smallstep): <b>Example Inc.</b>
✔ 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.]): <b>localhost</b>
✔ What address will your new CA listen at? (e.g. :443): <b>127.0.0.1:8080</b>
✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): <b>bob@example.com</b>
✔ What do you want your password to be? [leave empty and we'll generate one]: <b>abc123</b>
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'.
</code></pre>
`step ca init` initializes the CA and accomplishes two tasks.
This command will:
1. Generate a Public Key Infrastructure (PKI) with Root and Intermediate
X.509 Certificates and private keys.
- Generate [password protected](https://github.com/smallstep/certificates/blob/master/docs/GETTING_STARTED.md#passwords) private keys for your CA to sign certificates
- Generate a root and [intermediate signing certificate](https://security.stackexchange.com/questions/128779/why-is-it-more-secure-to-use-intermediate-ca-certificates) for your CA
- Create a JSON configuration file for `step-ca` (see [getting started](./docs/GETTING_STARTED.md) for details)
The root X.509 Certificate is a fancy public key that will be
distributed to clients enabling them to authenticate all certificates
generated by your PKI. The root private key should be kept in a very
private place - but as this is just a demo we won't worry about that
right now ([more info on storing sensitive
data](./docs/GETTING_STARTED.md#passwords)). The intermediate
private key will be used to sign new certificates ([Why is it more
secure to use intermediate CA
certificates?](https://security.stackexchange.com/questions/128779/why-is-it-more-secure-to-use-intermediate-ca-certificates))
and the intermediate certificate will be distributed along with newly
minted leaf certificates. In our demo, the server will present the
intermediate certificate along with it's *server* (leaf) certificate
allowing our client to validate the full chain using the root.
You can find these artifacts in `$STEPPATH` (or `~/.step` by default).
2. Generate the configuration file required by the Step CA.
#### 2. Start `step-ca`:
See the [Getting Started](./docs/GETTING_STARTED.md) guide for an in depth
explanation of the Step CA configuration file.
You'll be prompted for your password from the previous step, to decrypt the CA's private signing key:
<pre><code>
<b>$ step ca init</b>
✔ What would you like to name your new PKI? (e.g. Smallstep): <b>Example Inc.</b>
✔ 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.]): <b>localhost</b>
✔ What address will your new CA listen at? (e.g. :443): <b>127.0.0.1:8080</b>
✔ What would you like to name the first provisioner for your new CA? (e.g. you@smallstep.com): <b>bob@example.com</b>
✔ What do you want your password to be? [leave empty and we'll generate one]: <b>abc123</b>
<pre><code>
<b>$ step-ca $(step path)/config/ca.json</b>
Please enter the password to decrypt /Users/bob/src/github.com/smallstep/step/.step/secrets/intermediate_ca_key: <b>abc123</b>
2019/02/18 13:28:58 Serving HTTPS on 127.0.0.1:8080 ...
</code></pre>
Generating root certificate...
all done!
#### 3. Copy our `hello world` golang server.
Generating intermediate certificate...
all done!
```
$ 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
```
✔ 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
#### 4. Get an identity for your server from the Step CA.
Your PKI is ready to go. To generate certificates for individual services see 'step help ca'.
<pre><code>
<b>$ step ca certificate localhost srv.crt srv.key</b>
✔ 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
<b>$ step certificate inspect --bundle srv.crt</b>
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
...
</code></pre>
<b>$ step-ca $(step path)/config/ca.json</b>
Please enter the password to decrypt /Users/bob/src/github.com/smallstep/step/.step/secrets/intermediate_ca_key: <b>abc123</b>
2019/02/18 13:28:58 Serving HTTPS on 127.0.0.1:8080 ...
</code></pre>
Note that `step` and `step-ca` handle details like [certificate bundling](https://smallstep.com/blog/everything-pki.html#intermediates-chains-and-bundling) for you.
Now we've got an 'up and running' online CA!
#### 5. Run the simple server.
2. Copy our `hello world` golang server.
<pre><code>
<b>$ go run srv.go &</b>
</code></pre>
```
$ cat > srv.go <<EOF
package main
#### 6. Get the root certificate from the Step CA.
import (
"net/http"
"log"
)
In a new Terminal window:
func HiHandler(w http.ResponseWriter, req *http.Request) {
w.Header().Set("Content-Type", "text/plain")
w.Write([]byte("Hello, world!\n"))
}
<pre><code>
<b>$ step ca root root.crt</b>
The root certificate has been saved in root.crt.
</code></pre>
func main() {
http.HandleFunc("/hi", HiHandler)
err := http.ListenAndServeTLS(":8443", "srv.crt", "srv.key", nil)
if err != nil {
log.Fatal(err)
}
}
EOF
```
#### 7. Make an authenticated, encrypted curl request to your server using HTTP over TLS.
3. Get an identity for your server from the Step CA.
<pre><code>
<b>$ step ca certificate localhost srv.crt srv.key</b>
✔ 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
<b>$ step certificate inspect --bundle srv.crt</b>
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
...
</code></pre>
Notice that when you inspect `srv.crt` there are actually two certificates
present. The first is your **server** (leaf) certificate and the second is
the intermediate certificate. When an intermediate CA is used to sign
**leaf** certificates it is not enough for the server to only show it's
**leaf** certificate because the client (which only has access to the root
certificate) will not be able to validate the full chain.
4. Run the simple server.
<pre><code>
<b>$ go run srv.go &</b>
</code></pre>
5. Get the root certificate from the Step CA.
In a new Terminal window:
<pre><code>
<b>$ step ca root root.crt</b>
The root certificate has been saved in root.crt.
</code></pre>
6. Make an authenticated, encrypted curl request to your server using HTTP over TLS.
<pre><code>
<b>$ curl --cacert root.crt https://localhost:8443/hi</b>
Hello, world!
</code></pre>
<pre><code>
<b>$ curl --cacert root.crt https://localhost:8443/hi</b>
Hello, world!
</code></pre>
*All Done!*

Write Preview
Loading…
Cancel
Save