Add docs for ssh cert duration for authority config.

Fixes #238.

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`,
+        SSH CA properties
-    associated public/private keys, and an optional `claims` attribute that will
-    override any values set in the global `claims` directly underneath `authority`.
 
+        * `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`.

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.