alexvanin/certificates
1
0
Fork 0
forked from TrueCloudLab/certificates
Code Pull requests Activity

Updated README with features & a bunch of cleanup

Browse source
This commit is contained in:
Michael Malone 2019-08-28 11:58:53 -07:00 committed by GitHub
parent 5dac2459c3
commit 7c9ab9814f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 167 additions and 147 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

314
README.md
View file

@ -2,6 +2,10 @@
An online certificate authority and related tools for secure automated certificate management, so you can use TLS everywhere. 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) | [Website](https://smallstep.com) |
[Documentation](#documentation) | [Documentation](#documentation) |
[Installation Guide](#installation-guide) | [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) ![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 ## Motivation
Managing your own *public key infrastructure* (PKI) can be tedious and error 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 makes it much easier to implement good security practices early, and
incrementally improve them as your system matures. 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 website](https://smallstep.com/certificates) and the [blog
post](https://smallstep.com/blog/step-certificates.html) announcing Step post](https://smallstep.com/blog/step-certificates.html) announcing this project.
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.
## Installation Guide ## Installation Guide
These instructions will install an OS specific version of the `step-ca` binary on These instructions will install an OS specific version of the `step-ca` binary on
your local machine. your local machine.
> NOTE: While `step` is not required to run the Step Certificate Authority (CA) 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.
> 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.
### Mac OS ### Mac OS
Install `step` via [Homebrew](https://brew.sh/). The Install `step` and `step-ca` together via [Homebrew](https://brew.sh/):
[Homebrew Formula](https://github.com/Homebrew/homebrew-core/blob/master/Formula/step.rb)
installs both `step cli` and `step certificates`.
<pre><code> <pre><code>
<b>$ brew install step</b> <b>$ brew install step</b>
@ -101,10 +125,10 @@ $ brew uninstall step
#### Debian #### Debian
1. [Optional] Install `step cli`. 1. [Optional] Install `step`.
Download the latest Debian package from 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 $ 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 $ sudo dpkg -i step_X.Y.Z_amd64.deb
``` ```
2. Install `step certificates`. 2. Install `step-ca`.
Download the latest Debian package from Download the latest Debian package from [releases](https://github.com/smallstep/certificates/releases):
[`step certificates` 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 $ 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 We are using the [Arch User Repository](https://aur.archlinux.org) to distribute
`step` binaries for Arch Linux. `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/). * 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. 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 ### Test
<pre><code> <pre><code>
<b>$ step version</b> <b>$ step version</b>
Smallstep CLI/0.8.5 (darwin/amd64) Smallstep CLI/0.10.0 (darwin/amd64)
Release Date: 2019-02-13 22:17 UTC Release Date: 2019-04-30 19:01 UTC
<b>$ step-ca version</b> <b>$ step-ca version</b>
Smallstep CA/0.8.4 (darwin/amd64) Smallstep CA/0.10.0 (darwin/amd64)
Release Date: 2019-02-18 18:56 UTC Release Date: 2019-04-30 19:02 UTC
</code></pre> </code></pre>
## Quickstart ## Quickstart
In the following guide we'll run a simple `hello` server that requires clients 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 to connect over an authorized and encrypted channel using HTTPS. `step-ca`
Certificate Authority (CA) will issue an identity dial tone to our server will issue certificates to our server, allowing it to authenticate and encrypt
enabling it to authenticate and encrypt communication. Let's get started! communication. Let's get started!
### Prerequisites ### Prerequisites
@ -167,152 +204,135 @@ enabling it to authenticate and encrypt communication. Let's get started!
### 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`:
`step ca init` initializes the CA and accomplishes two tasks. <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>
1. Generate a Public Key Infrastructure (PKI) with Root and Intermediate Generating root certificate...
X.509 Certificates and private keys. all done!
The root X.509 Certificate is a fancy public key that will be Generating intermediate certificate...
distributed to clients enabling them to authenticate all certificates all done!
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.
2. Generate the configuration file required by the Step CA. ✔ 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
See the [Getting Started](./docs/GETTING_STARTED.md) guide for an in depth Your PKI is ready to go. To generate certificates for individual services see 'step help ca'.
explanation of the Step CA configuration file. </code></pre>
<pre><code> This command will:
<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... - Generate [password protected](https://github.com/smallstep/certificates/blob/master/docs/GETTING_STARTED.md#passwords) private keys for your CA to sign certificates
all done! - 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)
Generating intermediate certificate... You can find these artifacts in `$STEPPATH` (or `~/.step` by default).
all done!
✔ Root certificate: /Users/bob/src/github.com/smallstep/step/.step/certs/root_ca.crt #### 2. Start `step-ca`:
✔ 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'. You'll be prompted for your password from the previous step, to decrypt the CA's private signing key:
<b>$ step-ca $(step path)/config/ca.json</b> <pre><code>
Please enter the password to decrypt /Users/bob/src/github.com/smallstep/step/.step/secrets/intermediate_ca_key: <b>abc123</b> <b>$ step-ca $(step path)/config/ca.json</b>
2019/02/18 13:28:58 Serving HTTPS on 127.0.0.1:8080 ... Please enter the password to decrypt /Users/bob/src/github.com/smallstep/step/.step/secrets/intermediate_ca_key: <b>abc123</b>
</code></pre> 2019/02/18 13:28:58 Serving HTTPS on 127.0.0.1:8080 ...
</code></pre>
Now we've got an 'up and running' online CA! #### 3. Copy our `hello world` golang server.
2. Copy our `hello world` golang server. ```
$ cat > srv.go <<EOF
package main
``` import (
$ cat > srv.go <<EOF "net/http"
package main "log"
)
import ( func HiHandler(w http.ResponseWriter, req *http.Request) {
"net/http" w.Header().Set("Content-Type", "text/plain")
"log" w.Write([]byte("Hello, world!\n"))
) }
func HiHandler(w http.ResponseWriter, req *http.Request) { func main() {
w.Header().Set("Content-Type", "text/plain") http.HandleFunc("/hi", HiHandler)
w.Write([]byte("Hello, world!\n")) err := http.ListenAndServeTLS(":8443", "srv.crt", "srv.key", nil)
if err != nil {
log.Fatal(err)
} }
}
EOF
```
func main() { #### 4. Get an identity for your server from the Step CA.
http.HandleFunc("/hi", HiHandler)
err := http.ListenAndServeTLS(":8443", "srv.crt", "srv.key", nil)
if err != nil {
log.Fatal(err)
}
}
EOF
```
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
<pre><code> <b>$ step certificate inspect --bundle srv.crt</b>
<b>$ step ca certificate localhost srv.crt srv.key</b> Certificate:
✔ Key ID: rQxROEr7Kx9TNjSQBTETtsu3GKmuW9zm02dMXZ8GUEk (bob@example.com) Data:
✔ Please enter the password to decrypt the provisioner key: abc123 Version: 3 (0x2)
✔ CA: https://localhost:8080/1.0/sign Serial Number: 140439335711218707689123407681832384336 (0x69a7a1d7f6f22f68059d2d9088307750)
✔ Certificate: srv.crt Signature Algorithm: ECDSA-SHA256
✔ Private Key: srv.key 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 certificate inspect --bundle srv.crt</b> Note that `step` and `step-ca` handle details like [certificate bundling](https://smallstep.com/blog/everything-pki.html#intermediates-chains-and-bundling) for you.
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 #### 5. Run the simple server.
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>
<pre><code> #### 6. Get the root certificate from the Step CA.
<b>$ go run srv.go &</b>
</code></pre>
5. Get the root certificate from the Step CA. In a new Terminal window:
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>
<pre><code> #### 7. Make an authenticated, encrypted curl request to your server using HTTP over TLS.
<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>
<pre><code> Hello, world!
<b>$ curl --cacert root.crt https://localhost:8443/hi</b> </code></pre>
Hello, world!
</code></pre>
*All Done!* *All Done!*