From 8227449746b59d93be6f01c25eb347e2aa650720 Mon Sep 17 00:00:00 2001 From: max furman Date: Fri, 1 May 2020 14:47:29 -0700 Subject: [PATCH] Add docs for ssh cert duration for authority config. Fixes #238. --- docs/GETTING_STARTED.md | 58 +++++++++++++++++++++---- docs/provisioners.md | 95 ++++++++++++++++++++++++++++++++--------- 2 files changed, 123 insertions(+), 30 deletions(-) diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index a442c2b2..6728e2f6 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -34,8 +34,11 @@ provisioners and its options. To initialize a PKI and configure the Step Certificate Authority run: +> **NOTE**: `step ca init` only initialize an x509 CA. If you +> would like to initialize an SSH CA as well, add the `--ssh` flag. + ``` -step ca init +step ca init [--ssh] ``` You'll be asked for a name for your PKI. This name will appear in your CA @@ -54,27 +57,40 @@ You should see: . ├── certs │   ├── intermediate_ca.crt -│   └── root_ca.crt +│   ├── root_ca.crt +│   ├── ssh_host_key.pub (--ssh only) +│   └── ssh_user_key.pub (--ssh only) ├── config │   ├── ca.json │   └── defaults.json └── secrets ├── intermediate_ca_key - └── root_ca_key + ├── root_ca_key + ├── ssh_host_key (--ssh only) + └── ssh_user_key (--ssh only) ``` The files created include: * `root_ca.crt` and `root_ca_key`: the root certificate and private key for - your PKI +your PKI. + * `intermediate_ca.crt` and `intermediate_ca_key`: the intermediate certificate - and private key that will be used to sign leaf certificates +and private key that will be used to sign leaf certificates. + +* `ssh_host_key.pub` and `ssh_host_key` (`--ssh` only): the SSH host pub/priv key +pair that will be used to sign new host SSH certificates. + +* `ssh_user_key.pub` and `ssh_user_key` (`--ssh` only): the SSH user pub/priv key +pair that will be used to sign new user SSH 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 +All of the files ending 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. @@ -146,10 +162,34 @@ ciphersuites, min/max TLS version, etc. 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`. + SSH CA properties + * `minUserSSHDuration`: do not allow certificates with a duration less + than this value. + + * `maxUserSSHDuration`: do not allow certificates with a duration + greater than this value. + + * `defaultUserSSHDuration`: if no certificate validity period is specified, + use this value. + + * `minHostSSHDuration`: do not allow certificates with a duration less + than this value. + + * `maxHostSSHDuration`: do not allow certificates with a duration + greater than this value. + + * `defaultHostSSHDuration`: if no certificate validity period is specified, + use this value. + + * `enableSSHCA`: enable all provisioners to generate SSH Certificates. + The deault value is `false`. You can enable this option per provisioner + by setting it to `true` in the provisioner claims. + + - `provisioners`: list of provisioners. + See the [provisioners documentation](./provisioners.md). Each provisioner + has an optional `claims` attribute that can override any attribute defined + at the level above in the `authority.claims`. `step ca init` will generate one provisioner. New provisioners can be added by running `step ca provisioner add`. diff --git a/docs/provisioners.md b/docs/provisioners.md index 070b819b..5ab7c997 100644 --- a/docs/provisioners.md +++ b/docs/provisioners.md @@ -4,6 +4,70 @@ 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. +Each provisioner can define an optional `claims` attribute. The settings in this +attribute override any settings in the global `claims` attribute in the authority +configuration. + +Example `claims`: + +``` + ... + "claims": { + "minTLSCertDuration": "5m", + "maxTLSCertDuration": "24h", + "defaultTLSCertDuration": "24h", + "disableRenewal": false + "minHostSSHCertDuration": "5m", + "maxHostSSHCertDuration": "1680h", + "minUserSSHCertDuration": "5m", + "maxUserSSHCertDuration": "24h", + "maxTLSCertDuration": "16h", + "enableSSHCA": true, + } + ... +``` + +* `claims` (optional): overwrites the default claims set in the authority. + You can set one or more of the following claims: + + * `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 claim is one prevention against + token reuse. The default value is `false`. Do not change this unless you + know what you are doing. + + SSH CA properties + + * `minUserSSHDuration`: do not allow certificates with a duration less + than this value. + + * `maxUserSSHDuration`: do not allow certificates with a duration + greater than this value. + + * `defaultUserSSHDuration`: if no certificate validity period is specified, + use this value. + + * `minHostSSHDuration`: do not allow certificates with a duration less + than this value. + + * `maxHostSSHDuration`: do not allow certificates with a duration + greater than this value. + + * `defaultHostSSHDuration`: if no certificate validity period is specified, + use this value. + + * `enableSSHCA`: enable all provisioners to generate SSH Certificates. + The deault value is `false`. You can enable this option per provisioner + by setting it to `true` in the provisioner claims. + ## JWK JWK is the default provisioner type. It uses public-key cryptography to sign and @@ -35,6 +99,12 @@ In the ca.json configuration file, a complete JWK provisioner example looks like "maxTLSCertDuration": "24h", "defaultTLSCertDuration": "24h", "disableRenewal": false + "minHostSSHCertDuration": "5m", + "maxHostSSHCertDuration": "1680h", + "minUserSSHCertDuration": "5m", + "maxUserSSHCertDuration": "24h", + "maxTLSCertDuration": "16h", + "enableSSHCA": true, } } ``` @@ -75,23 +145,6 @@ In the ca.json configuration file, a complete JWK provisioner example looks like provided using the `--key` flag of the `step ca token` to be able to sign the token. -* `claims` (optional): overwrites the default claims set in the authority. - You can set one or more of the following claims: - - * `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 claim is one prevention against - token reuse. The default value is `false`. Do not change this unless you - know what you are doing. - ## OIDC An OIDC provisioner allows a user to get a certificate after authenticating @@ -149,7 +202,7 @@ is G-Suite. port to be specified at the time of the request for loopback IP redirect URIs. * `claims` (optional): overwrites the default claims set in the authority, see - the [JWK](#jwk) section for all the options. + the [top](#provisioners) section for all the options. ## Provisioners for Cloud Identities @@ -213,7 +266,7 @@ In the ca.json, an AWS provisioner looks like: certificate. The instance age is a string using the duration format. * `claims` (optional): overwrites the default claims set in the authority, see - the [JWK](#jwk) section for all the options. + the [top](#provisioners) section for all the options. ### GCP @@ -265,7 +318,7 @@ In the ca.json, a GCP provisioner looks like: certificate. The instance age is a string using the duration format. * `claims` (optional): overwrites the default claims set in the authority, see - the [JWK](#jwk) section for all the options. + the [top](#provisioners) section for all the options. ### Azure @@ -315,4 +368,4 @@ In the ca.json, an Azure provisioner looks like: and different tokens can be used to get different certificates. * `claims` (optional): overwrites the default claims set in the authority, see - the [JWK](#jwk) section for all the options. + the [top](#provisioners) section for all the options.