From e8baba3e30550264c67cb71917fbfca546746d5e Mon Sep 17 00:00:00 2001 From: max furman Date: Thu, 1 Nov 2018 00:46:13 -0700 Subject: [PATCH] first pass at README --- CHANGELOG.md | 13 +++ README.md | 247 +++++++++++++++++++++++++++++++++++++++++++++++- distribution.md | 116 +++++++++++++++++++++++ 3 files changed, 375 insertions(+), 1 deletion(-) create mode 100644 CHANGELOG.md create mode 100644 distribution.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..2a2b3e25 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,13 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) +and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). + +## [Unreleased - 0.0.1] - DATE +### Added +### Changed +### Deprecated +### Removed +### Fixed +### Security diff --git a/README.md b/README.md index 183f3bc6..7b503d9b 100644 --- a/README.md +++ b/README.md @@ -1 +1,246 @@ -## SHHHH, THIS PROJECT HASN'T OFFICIALLY LAUNCHED YET AND THIS REPO IS SUPER SECRET!!! +# SHHHH, THIS PROJECT HASN'T OFFICIALLY LAUNCHED YET AND THIS REPO IS SUPER SECRET!!! + +# Step Certificates + +An online certificate authority and related tools for secure automated +certificate management, so you can use TLS everywhere. + +For more information and docs see [the Step website](https://smallstep.com/cli/) +and the [blog post](https://smallstep.com/blog/zero-trust-swiss-army-knife.html) +announcing Step Certificate Authority. + +### Table of Contents + +- [Installing](#installing) +- [Documentation](#documentation) +- [Terminology](#terminology) +- [Getting Started](#getting-started) +- [I've Got a Running CA! Now What?](#now-what) +- [Versioning](#versioning) +- [How To Create A New Release](./distribution.md) +- [LICENSE](./LICENSE) +- [CHANGELOG](./CHANGELOG.md) + +## Installing + +These instructions will install an OS specific version of the `step` binary on +your local machine. + +### Mac OS + +Install `step-ca` via [Homebrew](https://brew.sh/): + +``` +brew install smallstep/smallstep/step-ca +``` + +### 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_X.Y.Z_amd64.deb +``` + +Install the Debian package: + +``` +sudo dpkg -i step-ca_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/step-ca + +3. In your browser with `step ca help --http :8080` and visiting http://localhost:8080 + +## Terminology + +### PKI - Public Key Infrastructure + +Blah blah + +### 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/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 . +``` + +You should see: + +``` +... +├── config +│   └── ca.json +└── secrets + ├── intermediate_ca.crt + ├── intermediate_ca_key + ├── root_ca.crt + ├── 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. + +All of the files endinging in `_key` are password protected using the password +you chose during PKI initialization. + +### 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 not certificat 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: + +``` +step-ca $STEPPATH/config/ca.step +``` + +## [I've got a running CA! Now What?](#now-what) + +Now that you have an online CA that authenticates requests before issuing +certificates you can begin automating the distribution and maintenance of your +PKI. + +### Issuing x.509 certificates for TLS (HTTPS) + +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 new-certificate "foo.example.com" foo.crt foo.key --ca-url ca.smallstep.com \ + --root /path/to/root_ca.crt +``` + +If you would like to generate certificates on demand from an automated configuration +configuration management solution (no user input) you would split the above flow +into two commands. + +``` +$ TOKEN=$(step ca new-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 new-certificate "foo.example.com" foo.crt foo.key --token "$TOKEN" \ + --ca-url https://ca.example.com --root /path/to/root_ca.crt +``` + +You can take a closer look at the contents of the certificate using `step certificate inspect`: + +``` +step certificate inspect foo.crt +``` + +## Versioning + +We use [SemVer](http://semver.org/) for versioning. For the versions available, +see the [tags on this repository](https://github.com/smallstep/cli). + + +## License + +This project is licensed under the MIT License - see the +[LICENSE](./LICENSE) file for details diff --git a/distribution.md b/distribution.md new file mode 100644 index 00000000..940d38d3 --- /dev/null +++ b/distribution.md @@ -0,0 +1,116 @@ +# Distribution + +This section describes how to build and deploy publicly available releases of +the Step CLI. + +## Creating A New Release + +New releases are (almost) entirely built and deployed by Travis-CI. Creating a new +release is as simple as pushing a new github tag. + +**Definitions**: + +* *Standard Release*: ready for public use. no `-rc*` suffix on the version. +e.g. `v1.0.2` +* *Release Candidate*: not ready for public use, still testing. must have a +`-rc*` suffix. e.g. `v1.0.2-rc` or `v1.0.2-rc.4` + + +1. Figure out the most recent existing tag. + + ``` + git fetch --tags + git tag + ``` + + The new tag needs to be the logical successor of the most recent existing tag. + See [versioning](./README.md#versioning) section for more information on version numbers. + +2. Select the next tag (but don't actually tag anything yet!!). + + Is the new release a *release candidate* or a *standard release*? + + 1. Release Candidate + + If the most recent tag is a standard release, say `v1.0.2`, then the version + of the next release candidate should be `v1.0.3-rc.1`. If the most recent tag + is a release candidate, say `v1.0.2-rc.3`, then the version of the next + release candidate should be `v1.0.2-rc.4`. + + 2. Standard Release + + If the most recent tag is a standard release, say `v1.0.2`, then the version + of the next standard release should be `v1.0.3`. If the most recent tag + is a release candidate, say `v1.0.2-rc.3`, then the version of the next + standard release should be `v1.0.3`. + +3. Update the [debian/changelog](./debian/changelog). + + 1. Update the version to match the tag selected in the previous step. Leave + off the `v` prefix. + + ``` + step-cli (1.0.2) UNRELEASED; urgency=medium + ... + ``` + + becomes... + + ``` + step-cli (1.0.3) UNRELEASED; urgency=medium + ... + ``` + + 2. Update the change log. + + *sigh* Honestly, this entire step should be handled programmatically. + + 3. Commit the changes. + +3. Update the remote origin with your commits. + + Make sure that the local checkout is up to date with + with the remote origin and that all local changes have been pushed. + + ``` + git pull --rebase origin master + git push + ``` + +4. Create a local tag. + + ``` + git tag v1.0.3 # standard release + ...or + git tag v1.0.3-rc.1 # release candidate + ``` + +5. Push the new tag to the remote origin. + + ``` + git push origin tag v1.0.3 # standard release + ...or + git push origin tag v1.0.3-rc.1 # release candidate + ``` + +6. Check the build status at +[Travis-CI](https://travis-ci.com/smallstep/certificates/builds/). + + Travis will begin by verifying that there are no compilation or linting errors + and then run the unit tests. Assuming all the checks have passed, Travis will + build Darwin and Linux artifacts (for easily installing `step`) and upload them + as part of the [Github Release](https://github.com/smallstep/certificates/releases). + + Travis will build and upload the following artifacts: + + * *step-ca_1.0.3_amd64.deb*: debian package for installation on linux. + * *step-ca_1.0.3_linux_amd64.tar.gz*: tarball containing a statically compiled linux binary. + * *step-ca_1.0.3_darwin_amd64.tar.gz*: tarball containing a statically compiled darwin binary. + +7. Update the Homebrew formula. + + **NOTE**: this only needs to be done for standard releases. + + Follow the steps [here](https://github.com/smallstep/homebrew-smallstep#how-to-update-the-formula). + +*All Done!*