TrueCloudLab/certificates
17
0
Fork 2
Code Issues 1 Pull requests 1 Releases Activity Actions

first pass at README

Browse source
This commit is contained in:
max furman 2018-11-01 00:46:13 -07:00
parent fb3a54e3ff
commit e8baba3e30
3 changed files with 375 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
CHANGELOG.md Normal file
View file

@ -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

247
README.md
View file

@ -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

116
distribution.md Normal file
View file

@ -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!*