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

Add docs for ssh cert duration for authority config.

Browse source 
Fixes #238.
This commit is contained in:
max furman 2020-05-01 14:47:29 -07:00
parent c1a84c1405
commit 8227449746
2 changed files with 123 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
docs/GETTING_STARTED.md
View file

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

95
docs/provisioners.md
View file

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