smallstep-certificates/README.md

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 and the blog post announcing Step Certificate Authority.

Table of Contents

• Installing
• Documentation
• Terminology
• Getting Started
• I've Got a Running CA! Now What?
• Versioning
• How To Create A New Release
• LICENSE
• CHANGELOG

Installing

These instructions will install an OS specific version of the step binary on your local machine.

Mac OS

Install step-ca via Homebrew:

brew install smallstep/smallstep/step-ca

Linux

Download the latest Debian package from 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

2. Step CA

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 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 for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details