diff --git a/README.md b/README.md
index 0f94a265..144151b6 100644
--- a/README.md
+++ b/README.md
@@ -1,535 +1,320 @@
# Step Certificates
-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.
+
+[Website](https://smallstep.com) |
+[Documentation](https://smallstep.com/docs/certificates) |
+[Installation Guide](#installation-guide) |
+[Getting Started](./docs/GETTING_STARTED.md) |
+[Contribution Guide](./docs/CONTRIBUTING.md)
+
+[](https://github.com/smallstep/certificates/releases)
+[](https://microbadger.com/images/smallstep/step-ca)
+[](https://goreportcard.com/report/github.com/smallstep/certificates)
+[](https://travis-ci.com/smallstep/certificates)
+[](https://opensource.org/licenses/Apache-2.0)
+[](https://cla-assistant.io/smallstep/certificates)
[](https://github.com/smallstep/certificates/stargazers)
[](https://twitter.com/intent/follow?screen_name=smallsteplabs)
-For more information and docs see [the Step website](https://smallstep.com/cli/)
-and the [blog post](https://smallstep.com/blog/step-certificates.html)
-announcing Step Certificate Authority.
-
-
+
-## Why?
+## 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.
+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 infratructure, automations, and workflows you'll need.
+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 infratructure, 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.
-This project 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 Step
+website](https://smallstep.com/certificates) and the [blog
+post](https://smallstep.com/blog/step-certificates.html) announcing Step
+Certificate Authority.
-> ## π Autocert
-> 
+> ## π Autocert
>
-> If you're using Kubernetes, make sure you [check out autocert](autocert/README.md): a kubernetes add-on that builds on `step certificates` to automatically injects TLS/HTTPS certificates into your containers.
-
-### Table of Contents
+> If you're using Kubernetes, make sure you [check out
+> autocert](autocert/README.md): a kubernetes add-on that builds on `step
+> certificates` to automatically inject TLS/HTTPS certificates into your containers.
-- [Installing](#installing)
-- [Documentation](#documentation)
-- [Terminology](#terminology)
-- [Getting Started](#getting-started)
-- [Commonly Asked Questions](docs/common-questions.md)
-- [Recommended Defaults](docs/recommendations.md)
-- [How To Create A New Release](docs/distribution.md)
-- [Versioning](#versioning)
-- [LICENSE](./LICENSE)
-- [CHANGELOG](./CHANGELOG.md)
+## Installation Guide
-
-## Installing
-
-These instructions will install an OS specific version of the `step` binary on
+These instructions will install an OS specific version of the `step-ca` binary on
your local machine.
-### Mac OS
-
-Install `step` via [Homebrew](https://brew.sh/):
-
-```
-brew install smallstep/smallstep/step
-```
-
-### Linux
-
-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
-```
-
-Install the Debian package:
-
-```
-sudo dpkg -i step-certificates_X.Y.Z_amd64.deb
-```
-
-## Documentation
-
-Documentation can be found in three places:
-
-1. On the command line with `step ca help xxx` where `xxx` is the subcommand you are interested in. Ex: `step help ca provisioners list`
-
-2. On the web at https://smallstep.com/docs/certificates
-
-3. In your browser with `step ca help --http :8080` and visiting http://localhost:8080
-
-## Terminology
-
-### PKI - Public Key Infrastructure
-
-A set of roles, policies, and procedures needed to create, manage, distribute,
-use, store, and revoke digital certificates and manage public-key encryption.
-The purpose of a PKI is to facilitate the secure electronic transfer of
-information for a range of network activities.
-
-### Provisioners
-
-Provisioners are people or code that are registered with the CA and authorized
-to issue "provisioning tokens". Provisioning tokens are single use tokens that
-can be used to authenticate with the CA and get a certificate.
-
-## Getting Started
-
-Demonstrates setting up your own PKI and certificate authority using `step ca`
-and getting certificates using the `step` command line tool and SDK.
-
-
-
-### Prerequisites
-
-1. [Step CLI](https://github.com/smallstep/cli/blob/master/README.md#installing)
-
-2. [Step CA](#installing)
-
-### Initializing PKI and configuring the Certificate Authority
-
-To initialize a PKI and configure the Step Certificate Authority run:
-
-```
-step ca init
-```
-
-You'll be asked for a name for your PKI. This name will appear in your CA
-certificates. It doesn't really matter what you choose. The name of your
-organization or your project will suffice.
-
-If you run:
-
-```
-tree $(step path)
-```
-
-You should see:
-
-```
-.
-βββ certs
-βΒ Β βββ intermediate_ca.crt
-βΒ Β βββ root_ca.crt
-βββ config
-βΒ Β βββ ca.json
-βΒ Β βββ defaults.json
-βββ secrets
- βββ intermediate_ca_key
- βββ root_ca_key
-```
-
-The files created include:
-
-* `root_ca.crt` and `root_ca_key`: the root certificate and private key for
- your PKI
-* `intermediate_ca.crt` and `intermediate_ca_key`: the intermediate certificate
- and private key that will be used to sign leaf certificates
-* `ca.json`: the configuration file necessary for running the Step CA.
-* `defaults.json`: file containing default parameters for the `step` CA cli
-interface. You can override these values with the appropriate flags or
-environment variables.
-
-All of the files endinging in `_key` are password protected using the password
-you chose during PKI initialization. We advise you to change these passwords
-(using the `step crypto change-pass` utility) if you plan to run your CA in a
-non-development environment.
-
-### What's Inside `ca.json`?
-
-`ca.json` is responsible for configuring communication, authorization, and
-default new certificate values for the Step CA. Below is a short list of
-definitions and descriptions of available configuration attributes.
-
-* `root`: location of the root certificate on the filesystem. The root certificate
-is used to mutually authenticate all api clients of the CA.
-
-* `crt`: location of the intermediate certificate on the filesystem. The
-intermediate certificate is returned alongside each new certificate,
-allowing the client to complete the certificate chain.
-
-* `key`: location of the intermediate private key on the filesystem. The
-intermediate key signs all new certificates generated by the CA.
-
-* `password`: optionally store the password for decrypting the intermediate private
-key (this should be the same password you chose during PKI initialization). If
-the value is not stored in configuration then you will be prompted for it when
-starting the CA.
-
-* `address`: e.g. `127.0.0.1:8080` - address and port on which the CA will bind
-and respond to requests.
-
-* `dnsNames`: comma separated list of DNS Name(s) for the CA.
-
-* `logger`: the default logging format for the CA is `text`. The other options
-is `json`.
-
-* `tls`: settings for negotiating communication with the CA; includes acceptable
-ciphersuites, min/max TLS version, etc.
-
-* `authority`: controls the request authorization and signature processes.
-
- - `template`: default ASN1DN values for new certificates.
-
- - `claims`: default validation for requested attributes in the certificate request.
- Can be overriden by similar claims objects defined by individual provisioners.
-
- * `minTLSCertDuration`: do not allow certificates with a duration less
- than this value.
-
- * `maxTLSCertDuration`: do not allow certificates with a duration greater
- than this value.
-
- * `defaultTLSCertDuration`: if no certificate validity period is specified,
- use this value.
-
- * `disableIssuedAtCheck`: disable a check verifying that provisioning
- tokens must be issued after the CA has booted. This is one prevention
- against token reuse. The default value is `false`. Do not change this
- unless you know what you are doing.
-
- - `provisioners`: list of provisioners. Each provisioner has a `name`,
- associated public/private keys, and an optional `claims` attribute that will
- override any values set in the global `claims` directly underneath `authority`.
+> 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.
+### Mac OS
-`step ca init` will generate one provisioner. New provisioners can be added by
-running `step ca provisioner add`.
+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`.
-### Running the CA
+
+$ brew install step
-To start the CA run:
+# 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:
```
-export STEPPATH=$(step path)
-step-ca $STEPPATH/config/ca.json
+$ brew untap smallstep/smallstep
+$ brew uninstall step
```
-### Configure Your Environment
-
-**Note**: Configuring your environment is only necessary for remote servers
-(not the server on which the `step ca init` command was originally run).
-
-Many of the cli utilities under `step ca [sub-command]` interface directly with
-a running instance of the Step CA. The CA exposes an HTTP API and clients are
-required to connect using HTTP over TLS (aka HTTPS). As part of bootstraping the
-Step CA, a certificate was generated using the root of trust that was
-created when you initilialized your PKI. In order to properly validate this
-certificate clients need access to the public root of trust, aka the public
-root certificate. If you are using the Step CLI on the same host where you
-initialized your PKI (the `root_ca.crt` is stored on disk locally), then you
-can continue to setting up a `default.json`, otherwise we will show you
-how to easily download your root certificate in the following step.
-
-#### Download the Root Certificate
-
-The next few steps are a guide for downloading the root certificate of your PKI
-from a running instance of the CA. First we'll define two servers:
-
-* **remote server**: This is the server where the Step CA is running. This may
-also be the server where you initialized your PKI, but for security reasons
-you may have done that offline.
+### Linux
-* **local server**: This is the server that wants access to the `step ca [sub-command]`
+1. [Optional] Install `step cli`.
-* **ca-url**: This is the url at which the CA is listening for requests. This
-should be a combination of the DNS name and port entered during PKI initialization.
-In the examples below we will use `https://ca.smallstep.com:8080`.
+ Download the latest Debian package from
+ [`step cli` releases](https://github.com/smallstep/cli/releases):
-1. Get the Fingerprint.
+ ```
+ $ wget https://github.com/smallstep/cli/releases/download/X.Y.Z/step_X.Y.Z_amd64.deb
+ ```
- From the **remote server**:
+ Install the Debian package:
```
- $ FP=$(step certificate fingerprint $(step path)/certs/root_ca.crt)
+ $ sudo dpkg -i step_X.Y.Z_amd64.deb
```
-2. Bootstrap your environment.
+2. Install `step certificates`.
- From the **local server**:
+ Download the latest Debian package from
+ [`step certificates` releases](https://github.com/smallstep/certificates/releases):
```
- $ step ca bootstrap --fingerprint $FP --ca-url "https://ca.smallstep.com:8080"
- $ cat $(step path)/config/defaults.json
+ $ wget https://github.com/smallstep/certificates/releases/download/X.Y.Z/step-certificates_X.Y.Z_amd64.deb
```
-3. Test.
+ Install the Debian package:
```
- * step ca health
+ $ sudo dpkg -i step-certificates_X.Y.Z_amd64.deb
```
-#### Setting up Environment Defaults
-This is optional, but we recommend you populate a `defaults.json` file with a
-few variables that will make your command line experience much more pleasant.
-
-You can do this manually or with the step command `step ca bootstrap`:
-
-```
-$ step ca bootstrap \
- --ca-url https://ca.smallstep.com:8080 \
- --fingerprint 0d7d3834cf187726cf331c40a31aa7ef6b29ba4df601416c9788f6ee01058cf3
-# Let's see what we got...
-$ cat $STEPPATH/config/defaults.json
-{
- "ca-url": "https://ca.smallstep.com:8080",
- "fingerprint": "628cfc85090ca65bb246d224f1217445be155cfc6167db4ed8f1b0e3de1447c5",
- "root": "/Users//src/github.com/smallstep/step/.step/certs/root_ca.crt"
-}
-# Test it out
-$ step ca health
-```
-
-* **ca-url** is the DNS name and port that you used when initializing the CA.
-
-* **root** is the path to the root certificate on the file system.
-
-* **fingerprint** is the root certificate fingerprint (SHA256).
-
-You can always override these values with command-line flags or environment
-variables.
-
-To manage the CA provisioners you can also add the property **ca-config** with
-the path to the CA configuration file, with that property you won't need to add
-it in commands like `step ca provisioners [add|remove]`.
-**Note**: to manage provisioners you must be on the host on which the CA is
-running. You need direct access to the `ca.json` file.
-
-### Hot Reload
-
-It is important that the CA be able to handle configuration changes with no downtime.
-Our CA has a built in `reload` function allowing it to:
-
-1. Finish processing existing connections while blocking new ones.
-2. Parse the configuration file and re-initialize the API.
-3. Begin accepting blocked and new connections.
-
-`reload` is triggered by sending a SIGHUP to the PID (see `man kill`
-for your OS) of the Step CA process. A few important details to note when using `reload`:
-
-* The location of the modified configuration must be in the same location as it
-was in the original invocation of `step-ca`. So, if the original command was
-
-```
-$ step-ca ./.step/config/ca.json
-```
-
-then, upon `reload`, the Step CA will read it's new configuration from the same
-configuration file.
-
-* Step CA requires the password to decrypt the intermediate certificate, again,
-upon `reload`. You can automate this in one of two ways:
-
- * Use the `--password-file` flag in the original invocation.
- * Use the top level `password` attribute in the `ca.json` configuration file.
-
-### Let's issue a certificate!
-
-There are two steps to issuing a certificate at the command line:
-
-1. Generate a provisioning token using your provisioning credentials.
-2. Generate a CSR and exchange it, along with the provisioning token, for a certificate.
-
-If you would like to generate a certificate from the command line, the Step CLI
-provides a single command that will prompt you to select and decrypt an
-authorized provisioner and then request a new certificate.
-
-```
-$ step ca certificate "foo.example.com" foo.crt foo.key
-```
-
-If you would like to generate certificates on demand from an automated
-configuration management solution (no user input) you would split the above flow
-into two commands.
-
-```
-$ TOKEN=$(step ca token foo.example.com \
- --kid 4vn46fbZT68Uxfs9LBwHkTvrjEvxQqx-W8nnE-qDjts \
- --ca-url https://ca.example.com \
- --root /path/to/root_ca.crt --password-file /path/to/provisioner/password)
-
-$ step ca certificate "foo.example.com" foo.crt foo.key --token "$TOKEN"
-```
-
-You can take a closer look at the contents of the certificate using `step certificate inspect`:
+3. Test.
-```
-$ step certificate inspect foo.crt
-```
+
+ $ step version
+ Smallstep CLI/0.8.5 (darwin/amd64)
+ Release Date: 2019-02-13 22:17 UTC
-### List|Add|Remove Provisioners
+ $ step-ca version
+ Smallstep CA/0.8.4 (darwin/amd64)
+ Release Date: 2019-02-18 18:56 UTC
+
-The Step CA configuration is initialized with one provisioner; one entity
-that is authorized by the CA to generate provisioning tokens for new certificates.
-We encourage you to have many provisioners - ideally one for each entity in your
-infrastructure.
+## Quickstart
-**Why should I be using multiple provisioners?**
-
-* Each certificate generated by the Step CA contains the ID of the provisioner
-that issued the *provisioning token* authorizing the creation of the cert. This
-ID is stored in the X.509 ExtraExtensions of the certificate under
-`OID: 1.3.6.1.4.1.37476.9000.64.1` and can be inspected by running `step
-certificate inspect foo.crt`. These IDs can and should be used to debug and
-gather information about the origin of a certificate. If every member of your
-ops team and the configuration management tools all use the same provisioner
-to authorize new certificates you lose valuable visibility into the workings
-of your PKI.
-* Each provisioner should require a **unique** password to decrypt it's private key
--- we can generate unique passwords for you but we can't force you to use them.
-If you only have one provisioner then every entity in the infrastructure will
-need access to that one password. Jim from your dev ops team should not be using
-the same provisioner/password combo to authorize certificates for debugging as
-Chef is for your CICD - no matter how trustworthy Jim says he is.
-
-Let's begin by listing the existing provisioners:
+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!
-```
-$ bin/step ca provisioner list
-```
+### Prerequisites
-Now let's add a provisioner for Jim.
+* [`step`](#installation-guide)
+* [golang](https://golang.org/doc/install)
-```
-$ bin/step ca provisioner add jim@smallstep.com --create
-```
+### Let's get started!
-**NOTE**: This change will not affect the Step CA until a `reload` is forced by
-sending a SIGHUP signal to the process.
+1. Initialize and run the Step CA.
-List the provisioners again and you will see that nothing has changed.
+ `step ca init` initializes the CA and accomplishes two tasks.
-```
-$ bin/step ca provisioner list
-```
+ 1. Generate a Public Key Infrastructure (PKI) with Root and Intermediate
+X.509 Certificates and private keys.
-Now let's `reload` the CA. You will need to re-enter your intermediate
-password unless it's in your `ca.json` or your are using `--password-file`.
+ 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.
-```
-$ ps aux | grep step-ca # to get the PID
-$ kill -1
-```
+ 2. Generate the configuration file required by the Step CA.
-Once the CA is running again, list the provisioners, again.
+ See the [Getting Started](./docs/GETTING_STARTED.md) guide for an in depth
+ explanation of the Step CA configuration file.
-```
-$ bin/step ca provisioner list
-```
+
+ $ 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
-Boom! Magic.
-Now suppose Jim forgets his password ('come on Jim!'), and he'd like to remove
-his old provisioner. Get the `kid` (Key ID) of Jim's provisioner by listing
-the provisioners and finding the appropriate one. Then run:
+ Generating root certificate...
+ all done!
-```
-$ bin/step ca provisioner remove jim@smallstep.com --kid
-```
+ Generating intermediate certificate...
+ all done!
-Then `reload` the CA and verify that Jim's provisioner is no longer returned
-in the provisioner list.
+ β 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
-We can also remove all of Jim's provisioners, supposing Jim forgot all the passwords
-('really Jim?'), by running the following:
+ Your PKI is ready to go. To generate certificates for individual services see 'step help ca'.
-```
-$ bin/step ca provisioner remove jim@smallstep.com --all
-```
+ $ 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 ...
+
-The same entity may have multiple provisioners for authorizing different
-types of certs. Each of these provisioners must have unique keys.
+ Now we've got an 'up and running' online CA!
-## Notes on Securing the Step CA and your PKI.
+2. Copy our `hello world` golang server.
-In this section we recommend a few best practices when it comes to
-running, deploying, and managing your own online CA and PKI. Security is a moving
-target and we expect out recommendations to change and evolve as well.
+ ```
+ $ cat > srv.go <
+ $ 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
+ ...
+
+
+ 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.
+
+
+ $ go run srv.go &
+
+
+5. 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.
+
+
+6. 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](./docs/GETTING_STARTED.md) guide for more examples
+and best practices on running Step CA in production.
-When you initialize your PKI two private keys are generated; one intermediate
-private key and one root private key. It is very important that these private keys
-are kept secret. The root private key should be moved around as little as possible,
-preferably not all - meaning it never leaves the server on which it was created.
+## Documentation
-### Passwords
+Documentation can be found in three places:
-When you intialize your PKI (`step ca init`) the root and intermediate
-private keys will be encrypted with the same password. We recommend that you
-change the password with which the intermediate was encrypted at your earliest
-convenience.
+1. On the command line with `step ca help xxx` where `xxx` is the subcommand you are interested in. Ex: `step help ca provisioners list`
-```
-$ step crypto change-pass $STEPPATH/secrets/intermediate_ca_key
-```
+2. On the web at https://smallstep.com/docs/certificates
-Once you've changed the intermediate private key password you should never have
-to use the root private key password again.
-
-We encourage users to always use a password manager to generate random passwords
-or let Step CLI generate passwords for you.
-
-The next important matter is how your passwords are stored. We recommend using a
-[password manager](https://en.wikipedia.org/wiki/List_of_password_managers).
-There are many to choose from and the choice will depend on the risk & security
-profile of your organization.
-
-In addition to using a password manager to store all passwords (private key,
-provisioner, etc.) we recommend using a threshold cryptography algorithm like
-[Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing)
-to divide the root private key across a handful of trusted parties.
-
-### Provisioners
-
-When you intialize your PKI (`step ca init`) a default provisioner will be created
-and it's private key will be encrypted using the same password used to encrypt
-the root private key. Before deploying the Step CA you should remove this
-provisioner and add new ones that are encrypted with new, secure, random passwords.
-See the section on [managing provisioners](#listaddremove-provisioners).
-
-### Deploying
-
-* Refrain from entering passwords for private keys or provisioners on the command line.
-Use the `--password-file` flag whenever possible.
-* Run the Step CA as a new user and make sure that the config files, private keys,
-and passwords used by the CA are stored in such a way that only this new user
-has permissions to read and write them.
-* Use short lived certificates. Our default validity period for new certificates
-is 24 hours. You can configure this value in the `ca.json` file. Shorter is
-better - less time to form an attack.
-* Short lived certificates are **not** a replacement for CRL and OCSP. CRL and OCSP
-are features that we plan to implement, but are not yet available. In the mean
-time short lived certificates are a decent alternative.
-* Keep your hosts secure by enforcing AuthN and AuthZ for every connection. SSH
-access is a big one.
+3. On your browser by running `step ca help --http :8080` and visiting http://localhost:8080
## The Future
@@ -541,16 +326,7 @@ help solve problems in this space.
* Tell us what features you'd like to see - open issues or hit us on
[Twitter](https://twitter.com/smallsteplabs).
-## Versioning
-
-We use [SemVer](http://semver.org/) for versioning. For the versions available,
-see the [tags on this repository](https://github.com/smallstep/cli).
+## Further Reading
-## License
-
-This project is licensed under the Apache 2.0 License - see the
-[LICENSE](./LICENSE) file for details
-
-### Individual Contributor License
-
-[](https://cla-assistant.io/smallstep/certificates)
+Check out the [Getting Started](./docs/GETTING_STARTED.md) guide for more examples
+and best practices on running Step CA in production.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 00000000..3b70d082
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,99 @@
+# Contributing to `step certificates`
+
+We welcome contributions to `step certificates` of any kind including
+documentation, themes, organization, tutorials, blog posts, bug reports,
+issues, feature requests, feature implementations, pull requests, helping
+to manage issues, etc.
+
+## Table of Contents
+
+* [Asking Support Questions](#asking-support-questions)
+* [Reporting Issues](#reporting-issues)
+* [Submitting Patches](#submitting-patches)
+ * [Code Contribution Guidelines](#code-contribution-guidelines)
+ * [Git Commit Message Guidelines](#git-commit-message-guidelines)
+
+## Asking Support Questions
+
+Users and developers can ask questions over email (info@smallstep.com) or
+[twitter](https://twitter.com/smallsteplabs). Please don't use the GitHub
+issue tracker to ask questions.
+
+## Reporting Issues
+
+If you believe you have found a defect in `step certificates` or its
+documentation, use the GitHub [issue
+tracker](https://github.com/smallstep/certificates/issues) to report the
+problem. When reporting the issue, please provide the version of `step
+certificates` in use (`step-ca version`) and your operating system.
+
+## Code Contribution
+
+'step certificates` aims to become a fully featured online Certificate
+Authority. We encourage all contributions that meet the following criteria:
+
+* fit naturally into a Certificate Authority.
+* strive not to break existing functionality.
+* close or update an open [`step certificates`
+issue](https://github.com/smallstep/certificates/issues)
+
+**Bug fixes are, of course, always welcome.**
+
+## Submitting Patches
+
+`step certificates` welcomes all contributors and contributions. If you are
+interested in helping with the project, please reach out to us or, better yet,
+submit a PR :).
+
+### Code Contribution Guidelines
+
+Because we want to create the best possible product for our users and the best
+contribution experience for our developers, we have a set of guidelines which
+ensure that all contributions are acceptable. The guidelines are not intended
+as a filter or barrier to participation. If you are unfamiliar with the
+contribution process, the Smallstep team will guide you in order to get your
+contribution in accordance with the guidelines.
+
+To make the contribution process as seamless as possible, we ask for the following:
+
+* Go ahead and fork the project and make your changes. We encourage pull
+requests to allow for review and discussion of code changes.
+* When youβre ready to create a pull request, be sure to:
+ * Sign the [CLA](https://cla-assistant.io/smallstep/certificates).
+ * Have test cases for the new code. If you have questions about how to do
+ this, please ask in your pull request.
+ * Run `go fmt`.
+ * Add documentation if you are adding new features or changing
+ functionality.
+ * Squash your commits into a single commit. `git rebase -i`. Itβs okay to
+ force update your pull request with `git push -f`.
+ * Follow the **Git Commit Message Guidelines** below.
+
+### Git Commit Message Guidelines
+
+This [blog article](http://chris.beams.io/posts/git-commit/) is a good resource
+for learning how to write good commit messages, the most important part being
+that each commit message should have a title/subject in imperative mood
+starting with a capital letter and no trailing period: *"Return error on wrong
+use of the Paginator"*, **NOT** *"returning some error."*
+
+Also, if your commit references one or more GitHub issues, always end your
+commit message body with *See #1234* or *Fixes #1234*. Replace *1234* with the
+GitHub issue ID. The last example will close the issue when the commit is
+merged into *master*.
+
+Please use a short and descriptive branch name, e.g. **NOT** "patch-1". It's
+very common but creates a naming conflict each time when a submission is pulled
+for a review.
+
+An example:
+
+```text
+Add step certificate install
+
+Add a command line utility for installing (and uninstalling) certificates to the
+local system truststores. This should help developers with local development
+flows.
+
+Fixes #75
+```
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
new file mode 100644
index 00000000..c64bea4d
--- /dev/null
+++ b/docs/GETTING_STARTED.md
@@ -0,0 +1,445 @@
+# Getting Started
+
+Demonstrates setting up your own PKI and certificate authority using `step ca`
+and getting certificates using the `step` command line tool and SDK.
+
+
+
+## Prerequisites
+
+* [Step CA](#installation-guide)
+
+## Terminology
+
+### PKI - Public Key Infrastructure
+
+A set of roles, policies, and procedures needed to create, manage, distribute,
+use, store, and revoke digital certificates and manage public-key encryption.
+The purpose of a PKI is to facilitate the secure electronic transfer of
+information for a range of network activities.
+
+### Provisioners
+
+Provisioners are people or code that are registered with the CA and authorized
+to issue "provisioning tokens". Provisioning tokens are single use tokens that
+can be used to authenticate with the CA and get a certificate.
+
+## Initializing PKI and configuring the Certificate Authority
+
+To initialize a PKI and configure the Step Certificate Authority run:
+
+```
+step ca init
+```
+
+You'll be asked for a name for your PKI. This name will appear in your CA
+certificates. It doesn't really matter what you choose. The name of your
+organization or your project will suffice.
+
+If you run:
+
+```
+tree $(step path)
+```
+
+You should see:
+
+```
+.
+βββ certs
+βΒ Β βββ intermediate_ca.crt
+βΒ Β βββ root_ca.crt
+βββ config
+βΒ Β βββ ca.json
+βΒ Β βββ defaults.json
+βββ secrets
+ βββ intermediate_ca_key
+ βββ root_ca_key
+```
+
+The files created include:
+
+* `root_ca.crt` and `root_ca_key`: the root certificate and private key for
+ your PKI
+* `intermediate_ca.crt` and `intermediate_ca_key`: the intermediate certificate
+ and private key that will be used to sign leaf certificates
+* `ca.json`: the configuration file necessary for running the Step CA.
+* `defaults.json`: file containing default parameters for the `step` CA cli
+interface. You can override these values with the appropriate flags or
+environment variables.
+
+All of the files endinging in `_key` are password protected using the password
+you chose during PKI initialization. We advise you to change these passwords
+(using the `step crypto change-pass` utility) if you plan to run your CA in a
+non-development environment.
+
+## What's Inside `ca.json`?
+
+`ca.json` is responsible for configuring communication, authorization, and
+default new certificate values for the Step CA. Below is a short list of
+definitions and descriptions of available configuration attributes.
+
+* `root`: location of the root certificate on the filesystem. The root certificate
+is used to mutually authenticate all api clients of the CA.
+
+* `crt`: location of the intermediate certificate on the filesystem. The
+intermediate certificate is returned alongside each new certificate,
+allowing the client to complete the certificate chain.
+
+* `key`: location of the intermediate private key on the filesystem. The
+intermediate key signs all new certificates generated by the CA.
+
+* `password`: optionally store the password for decrypting the intermediate private
+key (this should be the same password you chose during PKI initialization). If
+the value is not stored in configuration then you will be prompted for it when
+starting the CA.
+
+* `address`: e.g. `127.0.0.1:8080` - address and port on which the CA will bind
+and respond to requests.
+
+* `dnsNames`: comma separated list of DNS Name(s) for the CA.
+
+* `logger`: the default logging format for the CA is `text`. The other options
+is `json`.
+
+* `tls`: settings for negotiating communication with the CA; includes acceptable
+ciphersuites, min/max TLS version, etc.
+
+* `authority`: controls the request authorization and signature processes.
+
+ - `template`: default ASN1DN values for new certificates.
+
+ - `claims`: default validation for requested attributes in the certificate request.
+ Can be overriden by similar claims objects defined by individual provisioners.
+
+ * `minTLSCertDuration`: do not allow certificates with a duration less
+ than this value.
+
+ * `maxTLSCertDuration`: do not allow certificates with a duration greater
+ than this value.
+
+ * `defaultTLSCertDuration`: if no certificate validity period is specified,
+ use this value.
+
+ * `disableIssuedAtCheck`: disable a check verifying that provisioning
+ tokens must be issued after the CA has booted. This is one prevention
+ against token reuse. The default value is `false`. Do not change this
+ unless you know what you are doing.
+
+ - `provisioners`: list of provisioners. Each provisioner has a `name`,
+ associated public/private keys, and an optional `claims` attribute that will
+ override any values set in the global `claims` directly underneath `authority`.
+
+
+`step ca init` will generate one provisioner. New provisioners can be added by
+running `step ca provisioner add`.
+
+## Running the CA
+
+To start the CA run:
+
+```
+export STEPPATH=$(step path)
+step-ca $STEPPATH/config/ca.json
+```
+
+## Configure Your Environment
+
+**Note**: Configuring your environment is only necessary for remote servers
+(not the server on which the `step ca init` command was originally run).
+
+Many of the cli utilities under `step ca [sub-command]` interface directly with
+a running instance of the Step CA. The CA exposes an HTTP API and clients are
+required to connect using HTTP over TLS (aka HTTPS). As part of bootstraping
+the Step CA, a certificate was generated using the root of trust that was
+created when you initilialized your PKI. In order to properly validate this
+certificate clients need access to the public root of trust, aka the public root
+certificate. If you are using the `step cli` on the same host where you
+initialized your PKI (the `root_ca.crt` is stored on disk locally), then you can
+continue to [setting up your environment](setting-up-environment-variables),
+otherwise we will show you how to easily download your root certificate in the
+following step.
+
+#### Download the Root Certificate
+
+The next few steps are a guide for downloading the root certificate of your PKI
+from a running instance of the CA. First we'll define two servers:
+
+* **remote server**: This is the server where the Step CA is running. This may
+also be the server where you initialized your PKI, but for security reasons
+you may have done that offline.
+
+* **local server**: This is the server that wants access to the `step ca [sub-command]`
+
+* **ca-url**: This is the url at which the CA is listening for requests. This
+should be a combination of the DNS name and port entered during PKI initialization.
+In the examples below we will use `https://ca.smallstep.com:8080`.
+
+1. Get the Fingerprint.
+
+ From the **remote server**:
+
+ ```
+ $ FP=$(step certificate fingerprint $(step path)/certs/root_ca.crt)
+ ```
+
+2. Bootstrap your environment.
+
+ From the **local server**:
+
+ ```
+ $ step ca bootstrap --fingerprint $FP --ca-url "https://ca.smallstep.com:8080"
+ $ cat $(step path)/config/defaults.json
+ ```
+
+3. Test.
+
+ ```
+ * step ca health
+ ```
+
+#### Setting up Environment Defaults
+
+This is optional, but we recommend you populate a `defaults.json` file with a
+few variables that will make your command line experience much more pleasant.
+
+You can do this manually or with the step command `step ca bootstrap`:
+
+```
+$ step ca bootstrap \
+ --ca-url https://ca.smallstep.com:8080 \
+ --fingerprint 0d7d3834cf187726cf331c40a31aa7ef6b29ba4df601416c9788f6ee01058cf3
+# Let's see what we got...
+$ cat $STEPPATH/config/defaults.json
+{
+ "ca-url": "https://ca.smallstep.com:8080",
+ "fingerprint": "628cfc85090ca65bb246d224f1217445be155cfc6167db4ed8f1b0e3de1447c5",
+ "root": "/Users//src/github.com/smallstep/step/.step/certs/root_ca.crt"
+}
+# Test it out
+$ step ca health
+```
+
+* **ca-url** is the DNS name and port that you used when initializing the CA.
+
+* **root** is the path to the root certificate on the file system.
+
+* **fingerprint** is the root certificate fingerprint (SHA256).
+
+You can always override these values with command-line flags or environment
+variables.
+
+To manage the CA provisioners you can also add the property **ca-config** with
+the path to the CA configuration file, with that property you won't need to add
+it in commands like `step ca provisioners [add|remove]`.
+**Note**: to manage provisioners you must be on the host on which the CA is
+running. You need direct access to the `ca.json` file.
+
+### Hot Reload
+
+It is important that the CA be able to handle configuration changes with no downtime.
+Our CA has a built in `reload` function allowing it to:
+
+1. Finish processing existing connections while blocking new ones.
+2. Parse the configuration file and re-initialize the API.
+3. Begin accepting blocked and new connections.
+
+`reload` is triggered by sending a SIGHUP to the PID (see `man kill`
+for your OS) of the Step CA process. A few important details to note when using `reload`:
+
+* The location of the modified configuration must be in the same location as it
+was in the original invocation of `step-ca`. So, if the original command was
+
+```
+$ step-ca ./.step/config/ca.json
+```
+
+then, upon `reload`, the Step CA will read it's new configuration from the same
+configuration file.
+
+* Step CA requires the password to decrypt the intermediate certificate, again,
+upon `reload`. You can automate this in one of two ways:
+
+ * Use the `--password-file` flag in the original invocation.
+ * Use the top level `password` attribute in the `ca.json` configuration file.
+
+### Let's issue a certificate!
+
+There are two steps to issuing a certificate at the command line:
+
+1. Generate a provisioning token using your provisioning credentials.
+2. Generate a CSR and exchange it, along with the provisioning token, for a certificate.
+
+If you would like to generate a certificate from the command line, the Step CLI
+provides a single command that will prompt you to select and decrypt an
+authorized provisioner and then request a new certificate.
+
+```
+$ step ca certificate "foo.example.com" foo.crt foo.key
+```
+
+If you would like to generate certificates on demand from an automated
+configuration management solution (no user input) you would split the above flow
+into two commands.
+
+```
+$ TOKEN=$(step ca token foo.example.com \
+ --kid 4vn46fbZT68Uxfs9LBwHkTvrjEvxQqx-W8nnE-qDjts \
+ --ca-url https://ca.example.com \
+ --root /path/to/root_ca.crt --password-file /path/to/provisioner/password)
+
+$ step ca certificate "foo.example.com" foo.crt foo.key --token "$TOKEN"
+```
+
+You can take a closer look at the contents of the certificate using `step certificate inspect`:
+
+```
+$ step certificate inspect foo.crt
+```
+
+### List|Add|Remove Provisioners
+
+The Step CA configuration is initialized with one provisioner; one entity
+that is authorized by the CA to generate provisioning tokens for new certificates.
+We encourage you to have many provisioners - ideally one for each entity in your
+infrastructure.
+
+**Why should I be using multiple provisioners?**
+
+* Each certificate generated by the Step CA contains the ID of the provisioner
+that issued the *provisioning token* authorizing the creation of the cert. This
+ID is stored in the X.509 ExtraExtensions of the certificate under
+`OID: 1.3.6.1.4.1.37476.9000.64.1` and can be inspected by running `step
+certificate inspect foo.crt`. These IDs can and should be used to debug and
+gather information about the origin of a certificate. If every member of your
+ops team and the configuration management tools all use the same provisioner
+to authorize new certificates you lose valuable visibility into the workings
+of your PKI.
+* Each provisioner should require a **unique** password to decrypt it's private key
+-- we can generate unique passwords for you but we can't force you to use them.
+If you only have one provisioner then every entity in the infrastructure will
+need access to that one password. Jim from your dev ops team should not be using
+the same provisioner/password combo to authorize certificates for debugging as
+Chef is for your CICD - no matter how trustworthy Jim says he is.
+
+Let's begin by listing the existing provisioners:
+
+```
+$ bin/step ca provisioner list
+```
+
+Now let's add a provisioner for Jim.
+
+```
+$ bin/step ca provisioner add jim@smallstep.com --create
+```
+
+**NOTE**: This change will not affect the Step CA until a `reload` is forced by
+sending a SIGHUP signal to the process.
+
+List the provisioners again and you will see that nothing has changed.
+
+```
+$ bin/step ca provisioner list
+```
+
+Now let's `reload` the CA. You will need to re-enter your intermediate
+password unless it's in your `ca.json` or your are using `--password-file`.
+
+```
+$ ps aux | grep step-ca # to get the PID
+$ kill -1
+```
+
+Once the CA is running again, list the provisioners, again.
+
+```
+$ bin/step ca provisioner list
+```
+
+Boom! Magic.
+Now suppose Jim forgets his password ('come on Jim!'), and he'd like to remove
+his old provisioner. Get the `kid` (Key ID) of Jim's provisioner by listing
+the provisioners and finding the appropriate one. Then run:
+
+```
+$ bin/step ca provisioner remove jim@smallstep.com --kid
+```
+
+Then `reload` the CA and verify that Jim's provisioner is no longer returned
+in the provisioner list.
+
+We can also remove all of Jim's provisioners, supposing Jim forgot all the passwords
+('really Jim?'), by running the following:
+
+```
+$ bin/step ca provisioner remove jim@smallstep.com --all
+```
+
+The same entity may have multiple provisioners for authorizing different
+types of certs. Each of these provisioners must have unique keys.
+
+## Notes on Securing the Step CA and your PKI.
+
+In this section we recommend a few best practices when it comes to
+running, deploying, and managing your own online CA and PKI. Security is a moving
+target and we expect out recommendations to change and evolve as well.
+
+### Initializing your PKI
+
+When you initialize your PKI two private keys are generated; one intermediate
+private key and one root private key. It is very important that these private keys
+are kept secret. The root private key should be moved around as little as possible,
+preferably not all - meaning it never leaves the server on which it was created.
+
+### Passwords
+
+When you intialize your PKI (`step ca init`) the root and intermediate
+private keys will be encrypted with the same password. We recommend that you
+change the password with which the intermediate is encrypted at your earliest
+convenience.
+
+```
+$ step crypto change-pass $STEPPATH/secrets/intermediate_ca_key
+```
+
+Once you've changed the intermediate private key password you should never have
+to use the root private key password again.
+
+We encourage users to always use a password manager to generate random passwords
+or let Step CLI generate passwords for you.
+
+The next important matter is how your passwords are stored. We recommend using a
+[password manager](https://en.wikipedia.org/wiki/List_of_password_managers).
+There are many to choose from and the choice will depend on the risk & security
+profile of your organization.
+
+In addition to using a password manager to store all passwords (private key,
+provisioner, etc.) we recommend using a threshold cryptography algorithm like
+[Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing)
+to divide the root private key password across a handful of trusted parties.
+
+### Provisioners
+
+When you intialize your PKI (`step ca init`) a default provisioner will be created
+and it's private key will be encrypted using the same password used to encrypt
+the root private key. Before deploying the Step CA you should remove this
+provisioner and add new ones that are encrypted with new, secure, random passwords.
+See the section on [managing provisioners](#listaddremove-provisioners).
+
+### Deploying
+
+* Refrain from entering passwords for private keys or provisioners on the command line.
+Use the `--password-file` flag whenever possible.
+* Run the Step CA as a new user and make sure that the config files, private keys,
+and passwords used by the CA are stored in such a way that only this new user
+has permissions to read and write them.
+* Use short lived certificates. Our default validity period for new certificates
+is 24 hours. You can configure this value in the `ca.json` file. Shorter is
+better - less time to form an attack.
+* Short lived certificates are **not** a replacement for CRL and OCSP. CRL and OCSP
+are features that we plan to implement, but are not yet available. In the mean
+time short lived certificates are a decent alternative.
+* Keep your hosts secure by enforcing AuthN and AuthZ for every connection. SSH
+access is a big one.
+
diff --git a/images/step-ca-2-legged.gif b/images/step-ca-2-legged.gif
index f4308d5d..1e53e1d7 100644
Binary files a/images/step-ca-2-legged.gif and b/images/step-ca-2-legged.gif differ
diff --git a/images/step-ca-3-legged.gif b/images/step-ca-3-legged.gif
index d6297a8f..4d3234dc 100644
Binary files a/images/step-ca-3-legged.gif and b/images/step-ca-3-legged.gif differ
diff --git a/images/step-ca.gif b/images/step-ca.gif
deleted file mode 100644
index 4a395d11..00000000
Binary files a/images/step-ca.gif and /dev/null differ