From 7b1f4a43cf0c47904360eb8ae015269902b014be Mon Sep 17 00:00:00 2001
From: Sebastian Tiedtke <sebastiantiedtke@gmail.com>
Date: Fri, 22 Mar 2019 12:16:56 -0700
Subject: [PATCH] Added example for custom claims (#39)
Add docs and examples for custom claims
---
docs/GETTING_STARTED.md | 74 ++++++++++++++++++
examples/README.md | 63 ++++++++++++++++
examples/pki/config/ca.json | 145 ++++++++++++++++++++++--------------
3 files changed, 228 insertions(+), 54 deletions(-)
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
index c64bea4d..f08c1a06 100644
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@@ -379,6 +379,80 @@ $ bin/step ca provisioner remove jim@smallstep.com --all
The same entity may have multiple provisioners for authorizing different
types of certs. Each of these provisioners must have unique keys.
+## Use Custom Claims for Provisioners to Control Certificate Validity etc
+
+It's possible to configure provisioners on the CA to issue certs using propoerties specific to their target environments. Most commonly different validity periods and disabling renewals for certs. Here's how:
+
+```bash
+$ step ca init
+# complete the init steps
+$ step ca provisioner add --create dev@smallstep.com
+# lets create a provisioner for dev certs
+Please enter a password to encrypt the provisioner private key? password
+# add claims inside a provisioner element in ~/.step/config/ca.json
+~/.step/config/ca.json
+[...]
+"authority": {
+ "provisioners": [
+ {
+ "name": "you@smallstep.com",
+ "type": "jwk",
+ "key": {
+ "use": "sig",
+ "kty": "EC",
+ "kid": "Kg43gSukHnl8f5NztLPDxqpz_9TNUILnMrIMIa70jOU",
+ "crv": "P-256",
+ "alg": "ES256",
+ "x": "So0JVWFFXo-6GmDwq6WWZZk-AFZt5GKTx5PzdLhdsrQ",
+ "y": "kVz8pCl2Qx9fZmJZhXGrHpufwNDTp7oHwi8Zaj7rhiQ"
+ },
+ "encryptedKey": "...",
++ "claims": {
++ "minTLSCertDuration": "5s",
++ "maxTLSCertDuration": "12h",
++ "defaultTLSCertDuration": "2h",
++ "disableRenewal": true
++ }
+ }
+ ]
+},
+[...]
+
+# launch CA...
+$ step-ca $(step path)/config/ca.json
+Please enter the password to decrypt ~/.step/secrets/intermediate_ca_key: password
+2019/02/21 12:09:51 Serving HTTPS on :9443 ...
+```
+
+Please [`step ca provisioner`](https://smallstep.com/docs/cli/ca/provisioner/)'s docs for details on all available claims properties. The durations are strings which are a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+
+Now certs issued by the `dev@smallstep.com` provisioner will be valid for two hours and deny renewals. Command line flags allow validity extension up to 12h, please see [`step ca certificate`](https://smallstep.com/docs/cli/ca/certificate/)'s docs for details.
+
+```bash
+# grab a cert, will also work with 'step ca token' flow
+$ step ca certificate localhost site.crt site.key
+Use the arrow keys to navigate: ↓ ↑ → ←
+What provisioner key do you want to use?
+ IY7gYg_cDKmXtcs1sbhdBDDb9K9YvLO5aHzArjaayso (sebastian@smallstep.com)
+ ▸ uBYWYDCpeJu_IYzMGPZ1LJJTdlaiJQfdpkOVewbjy-8 (dev@smallstep.com)
+
+✔ Please enter the password to decrypt the provisioner key: password
+✔ CA: https://ca.smallstep.com:9443/1.0/sign
+✔ Certificate: site.crt
+✔ Private Key: site.key
+
+$ step certificate inspect site.crt --format json | jq .validity
+{
+ "start": "2019-02-21T20:19:06Z",
+ "end": "2019-02-21T22:19:06Z",
+ "length": 7200
+}
+
+# renewals will be denied for certs issued by this provisioner
+$ step ca renew site.crt site.key
+error renewing certificate: Unauthorized
+```
+
## Notes on Securing the Step CA and your PKI.
In this section we recommend a few best practices when it comes to
diff --git a/examples/README.md b/examples/README.md
index f6527db3..a2323302 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -555,6 +555,69 @@ Hello kube_client (cert issued by 'Smallstep Kubernetes Root CA') at 2019-01-28
Since the demo server is enrolled with the federated `Cloud CA` that trusts certs issued by the `Kubernetes CA` through federation the connection is successfully established.
+## Custom certificate validity periods using Custom Claims
+
+Bring up the certificate authority with the example:
+
+```sh
+certificates $ step-ca examples/pki/config/ca.json
+2019/03/11 13:37:03 Serving HTTPS on :9000 ...
+```
+
+The example comes with multiple provisioner options, two of which have custom claims to expand the validity of certificates:
+
+```sh
+$ step ca provisioner list | jq '.[] | "\(.name): \(.claims.defaultTLSCertDuration)"'
+# null means step default of 24h for cert validity
+"mariano@smallstep.com: null"
+"mike@smallstep.com: 2m0s"
+"decade: 87600h0m0s"
+"90days: 2160h0m0s"
+```
+
+A closer look at a duration-bound provisioner, `90days` for instance, reveals the custom configuration for certificate validity.
+
+```sh
+$ step ca provisioner list | jq '.[3].claims'
+{
+ "maxTLSCertDuration": "2160h0m0s",
+ "defaultTLSCertDuration": "2160h0m0s"
+}
+```
+
+Certificates with different validity periods can be generated using the respective provisioners.
+The durations are strings which are a sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+
+Please see [Getting Started](https://github.com/smallstep/certificates/blob/master/docs/GETTING_STARTED.md) in the docs directory to learn what custom claims configuration options are available and how to use them.
+
+```sh
+$ step ca certificate decade decade.crt decade.key
+✔ Key ID: iu7VZxKUcquv1BCWuvEUOyRy4zYyCmgt61OpRW5VbRE (decade)
+✔ Please enter the password to decrypt the provisioner key: password
+✔ CA: https://localhost:9000/1.0/sign
+✔ Certificate: decade.crt
+✔ Private Key: decade.key
+$ step certificate inspect --format json decade.crt | jq .validity
+{
+ "start": "2019-03-11T22:34:30Z",
+ "end": "2029-03-08T22:34:30Z",
+ "length": 315360000
+}
+
+$ step ca certificate 90days 90days.crt 90days.key
+✔ Key ID: 2LgjIvfirblnFMC6FjUr8jYkO8nOqz4rKoarCc8kiGU (90days)
+✔ Please enter the password to decrypt the provisioner key: password
+✔ CA: https://localhost:9000/1.0/sign
+✔ Certificate: 90days.crt
+✔ Private Key: 90days.key
+$ step certificate inspect --format json 90days.crt | jq .validity
+{
+ "start": "2019-03-11T22:35:39Z",
+ "end": "2019-06-09T22:35:39Z",
+ "length": 7776000
+}
+```
+
## Configuration Management Tools
Configuration management tools such as Puppet, Chef, Ansible, Salt, etc. make
diff --git a/examples/pki/config/ca.json b/examples/pki/config/ca.json
index 193e140c..2249b5fb 100644
--- a/examples/pki/config/ca.json
+++ b/examples/pki/config/ca.json
@@ -1,58 +1,95 @@
{
- "root": "examples/pki/secrets/root_ca.crt",
- "crt": "examples/pki/secrets/intermediate_ca.crt",
- "key": "examples/pki/secrets/intermediate_ca_key",
- "password": "password",
- "address": ":9000",
- "dnsNames": [
- "localhost"
- ],
- "logger": {
- "format": "text"
- },
- "authority": {
- "provisioners": [
- {
- "name": "mariano@smallstep.com",
- "type": "jwk",
- "key": {
- "use": "sig",
- "kty": "EC",
- "kid": "DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk",
- "crv": "P-256",
- "alg": "ES256",
- "x": "jXoO1j4CXxoTC32pNzkVC8l6k2LfP0k5ndhJZmcdVbk",
- "y": "c3JDL4GTFxJWHa8EaHdMh4QgwMh64P2_AGWrD0ADXcI"
+ "root": "examples/pki/secrets/root_ca.crt",
+ "federatedRoots": null,
+ "crt": "examples/pki/secrets/intermediate_ca.crt",
+ "key": "examples/pki/secrets/intermediate_ca_key",
+ "address": ":9000",
+ "dnsNames": [
+ "localhost"
+ ],
+ "logger": {
+ "format": "text"
+ },
+ "authority": {
+ "provisioners": [
+ {
+ "type": "jwk",
+ "name": "mariano@smallstep.com",
+ "key": {
+ "use": "sig",
+ "kty": "EC",
+ "kid": "DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk",
+ "crv": "P-256",
+ "alg": "ES256",
+ "x": "jXoO1j4CXxoTC32pNzkVC8l6k2LfP0k5ndhJZmcdVbk",
+ "y": "c3JDL4GTFxJWHa8EaHdMh4QgwMh64P2_AGWrD0ADXcI"
+ },
+ "encryptedKey": "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJjdHkiOiJqd2sranNvbiIsImVuYyI6IkEyNTZHQ00iLCJwMmMiOjEwMDAwMCwicDJzIjoiOTFVWjdzRGw3RlNXcldfX1I1NUh3USJ9.FcWtrBDNgrkA33G9Ll9sXh1cPF-3jVXeYe1FLmSDc_Q2PmfLOPvJOA.0ZoN32ayaRWnufJb.WrkffMmDLWiq1-2kn-w7-kVBGW12gjNCBHNHB1hyEdED0rWH1YWpKd8FjoOACdJyLhSn4kAS3Lw5AH7fvO27A48zzvoxZU5EgSm5HG9IjkIH-LBJ-v79ShkpmPylchgjkFhxa5epD11OIK4rFmI7s-0BCjmJokLR_DZBhDMw2khGnsr_MEOfAz9UnqXaQ4MIy8eT52xUpx68gpWFlz2YP3EqiYyNEv0PpjMtyP5lO2i8-p8BqvuJdus9H3fO5Dg-1KVto1wuqh4BQ2JKTauv60QAnM_4sdxRHku3F_nV64SCrZfDvnN2ve21raFROtyXaqHZhN6lyoPxDncy8v4.biaOblEe0N-gMpJyFZ-3-A"
+ },
+ {
+ "type": "jwk",
+ "name": "mike@smallstep.com",
+ "key": {
+ "use": "sig",
+ "kty": "EC",
+ "kid": "YYNxZ0rq0WsT2MlqLCWvgme3jszkmt99KjoGEJJwAKs",
+ "crv": "P-256",
+ "alg": "ES256",
+ "x": "LsI8nHBflc-mrCbRqhl8d3hSl5sYuSM1AbXBmRfznyg",
+ "y": "F99LoOvi7z-ZkumsgoHIhodP8q9brXe4bhF3szK-c_w"
+ },
+ "encryptedKey": "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJjdHkiOiJqd2sranNvbiIsImVuYyI6IkEyNTZHQ00iLCJwMmMiOjEwMDAwMCwicDJzIjoiVERQS2dzcEItTUR4ZDJxTGo0VlpwdyJ9.2_j0cZgTm2eFkZ-hrtr1hBIvLxN0w3TZhbX0Jrrq7vBMaywhgFcGTA.mCasZCbZJ-JT7vjA.bW052WDKSf_ueEXq1dyxLq0n3qXWRO-LXr7OzBLdUKWKSBGQrzqS5KJWqdUCPoMIHTqpwYvm-iD6uFlcxKBYxnsAG_hoq_V3icvvwNQQSd_q7Thxr2_KtPIDJWNuX1t5qXp11hkgb-8d5HO93CmN7xNDG89pzSUepT6RYXOZ483mP5fre9qzkfnrjx3oPROCnf3SnIVUvqk7fwfXuniNsg3NrNqncHYUQNReiq3e9I1R60w0ZQTvIReY7-zfiq7iPgVqmu5I7XGgFK4iBv0L7UOEora65b4hRWeLxg5t7OCfUqrS9yxAk8FdjFb9sEfjopWViPRepB0dYPH8dVI.fb6-7XWqp0j6CR9Li0NI-Q",
+ "claims": {
+ "minTLSCertDuration": "1m0s",
+ "defaultTLSCertDuration": "2m0s"
+ }
+ },
+ {
+ "type": "jwk",
+ "name": "decade",
+ "key": {
+ "use": "sig",
+ "kty": "EC",
+ "kid": "iu7VZxKUcquv1BCWuvEUOyRy4zYyCmgt61OpRW5VbRE",
+ "crv": "P-256",
+ "alg": "ES256",
+ "x": "PExnlmHxnnfpvp4bznMKbA6L_9Bk9ZhtsmvbOwh9Kys",
+ "y": "rrMPGvxscRzDdOYtZ1wsxeQjuuFl0nSzkwTHV_P-K-Y"
},
- "encryptedKey": "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJjdHkiOiJqd2sranNvbiIsImVuYyI6IkEyNTZHQ00iLCJwMmMiOjEwMDAwMCwicDJzIjoiOTFVWjdzRGw3RlNXcldfX1I1NUh3USJ9.FcWtrBDNgrkA33G9Ll9sXh1cPF-3jVXeYe1FLmSDc_Q2PmfLOPvJOA.0ZoN32ayaRWnufJb.WrkffMmDLWiq1-2kn-w7-kVBGW12gjNCBHNHB1hyEdED0rWH1YWpKd8FjoOACdJyLhSn4kAS3Lw5AH7fvO27A48zzvoxZU5EgSm5HG9IjkIH-LBJ-v79ShkpmPylchgjkFhxa5epD11OIK4rFmI7s-0BCjmJokLR_DZBhDMw2khGnsr_MEOfAz9UnqXaQ4MIy8eT52xUpx68gpWFlz2YP3EqiYyNEv0PpjMtyP5lO2i8-p8BqvuJdus9H3fO5Dg-1KVto1wuqh4BQ2JKTauv60QAnM_4sdxRHku3F_nV64SCrZfDvnN2ve21raFROtyXaqHZhN6lyoPxDncy8v4.biaOblEe0N-gMpJyFZ-3-A"
- },
- {
- "name": "mike@smallstep.com",
- "type": "jwk",
- "key": {
- "use": "sig",
- "kty": "EC",
- "kid": "YYNxZ0rq0WsT2MlqLCWvgme3jszkmt99KjoGEJJwAKs",
- "crv": "P-256",
- "alg": "ES256",
- "x": "LsI8nHBflc-mrCbRqhl8d3hSl5sYuSM1AbXBmRfznyg",
- "y": "F99LoOvi7z-ZkumsgoHIhodP8q9brXe4bhF3szK-c_w"
+ "claims": {
+ "maxTLSCertDuration": "87600h",
+ "defaultTLSCertDuration": "87600h"
},
- "encryptedKey": "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJjdHkiOiJqd2sranNvbiIsImVuYyI6IkEyNTZHQ00iLCJwMmMiOjEwMDAwMCwicDJzIjoiVERQS2dzcEItTUR4ZDJxTGo0VlpwdyJ9.2_j0cZgTm2eFkZ-hrtr1hBIvLxN0w3TZhbX0Jrrq7vBMaywhgFcGTA.mCasZCbZJ-JT7vjA.bW052WDKSf_ueEXq1dyxLq0n3qXWRO-LXr7OzBLdUKWKSBGQrzqS5KJWqdUCPoMIHTqpwYvm-iD6uFlcxKBYxnsAG_hoq_V3icvvwNQQSd_q7Thxr2_KtPIDJWNuX1t5qXp11hkgb-8d5HO93CmN7xNDG89pzSUepT6RYXOZ483mP5fre9qzkfnrjx3oPROCnf3SnIVUvqk7fwfXuniNsg3NrNqncHYUQNReiq3e9I1R60w0ZQTvIReY7-zfiq7iPgVqmu5I7XGgFK4iBv0L7UOEora65b4hRWeLxg5t7OCfUqrS9yxAk8FdjFb9sEfjopWViPRepB0dYPH8dVI.fb6-7XWqp0j6CR9Li0NI-Q",
+ "encryptedKey": "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJjdHkiOiJqd2sranNvbiIsImVuYyI6IkEyNTZHQ00iLCJwMmMiOjEwMDAwMCwicDJzIjoiZS1OVzRaZlBUNjFCUmR1bjJyNk9OZyJ9.zjToJ_Od6RIzVmo0cnmLZ69am410ftfBW594qNt60KmKX6JEWUufhA.kSrC74fKK3CkqiNS.G-oUqQhYMFIKuSj8thg9B5TeiaIMsQ-o_PTxIZE-Qb8TDU15ehPAsuIQmnbM6dSpkSGCmZgHTscp3xgLyv6QEBBjUHBpLwciWyipj1KBZDKSgLKeV6G2NiVBMETOaD1DsX3DxrHM-K3T1chXJFMJfkDSx1OEtaVfzqVYLyvNb5y_26oeRNSNYuTLzOrk6Ebr6KJE6lSWpvu1dtOrDAhTErouC56EQu2fTeDCa9eN50iRs4OjmF6FtBlR63h6FkvbmjJWC3zbIOe2RXRQx0Po6_dnKXSIqs7JMZSBerlgw6jzHme8YvqBqc2Ccy4Y4gJ23nwLkcsOVuFNdk6Nb7s.SB296DDrS-Wi4a9x_TGv4A"
+ },
+ {
+ "type": "jwk",
+ "name": "90days",
+ "key": {
+ "use": "sig",
+ "kty": "EC",
+ "kid": "2LgjIvfirblnFMC6FjUr8jYkO8nOqz4rKoarCc8kiGU",
+ "crv": "P-256",
+ "alg": "ES256",
+ "x": "iHFHMN91iFUDLh2LweFj6o0gDJ-pdmBY4IFIBNfUqd4",
+ "y": "Yfym7KtzZQaQc1gQoT81ggNBPvAdV_0CW0A5mQgOsOc"
+ },
"claims": {
- "minTLSCertDuration": "60s",
- "defaultTLSCertDuration": "120s"
- }
- }
- ]
- },
- "tls": {
- "cipherSuites": [
- "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
- "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
- ],
- "minVersion": 1.2,
- "maxVersion": 1.2,
- "renegotiation": false
- }
-}
\ No newline at end of file
+ "maxTLSCertDuration": "2160h",
+ "defaultTLSCertDuration": "2160h"
+ },
+ "encryptedKey": "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJjdHkiOiJqd2sranNvbiIsImVuYyI6IkEyNTZHQ00iLCJwMmMiOjEwMDAwMCwicDJzIjoiYk9XV0ZUN29uZldtZTdvbzdCMFZOdyJ9.p3gs2xd-Bdtwz1WGzQUZrcZeA8mpaMn_R_wTInpzZ9G1vIeRk-9T4g.RQNXmZP8uAzF1n8b.WpLqmNV_I0RIetdID2ag-igZryM8ekSimaHrXKoEpRAlBdBDZC-9qkbrJPNcTPRUi-29iZiBxKQ-0GX7ytiyulrQl7UfxUSrtT5vjhJEthSOGYXAOerUAnodGjpLCtIueTwVl6KJA2bXUapUd9xFn3DXfVgFagwqo1MrXKuIR0R5A4sjmEx8d2Kn_KQr0ZNnSOaAod2os4tmh3A87u9Jb51FMxhP-8Qbn7ff-RXwT_015C64Ux1zzS-ok89XbTgyfGxkah0-fVFAgS0zosHLI3C_pvumcglmFXZz7otH596BAU_QkqME6X-PGte6j6eldFobP_96tBxOhIRgVKw.Ky4xLbQZEGaBPjGJnKurng"
+ }
+ ]
+ },
+ "tls": {
+ "cipherSuites": [
+ "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
+ "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
+ ],
+ "minVersion": 1.2,
+ "maxVersion": 1.2,
+ "renegotiation": false
+ },
+ "password": "password"
+}
--
GitLab