docs: Add revocation document

2019-04-27 13:24:53 -07:00 · 2019-04-27 13:24:53 -07:00 · e4de7f07e8
commit e4de7f07e8
parent 46c7592f34
1 changed files with 201 additions and 0 deletions
--- a/docs/revocation.md
+++ b/docs/revocation.md
@ -0,0 +1,201 @@
+# Revocation
+
+**Active Revocation**: A certificate is no longer valid from the moment it has
+been actively revoked. Clients are required to check verify certificate validity
+against CRLs (Certificate Revocation Lists) or use OCSP (Online Certificate
+Status Protocol). Active Revocation requires clients to take an active role
+in certificate validation for the benefit of real time revocation.
+
+**Passive Revocation**: A certificate that has been passively revoked can no
+longer be renewed. It will still be valid for the remainder of it's validity period,
+but cannot be prolonged. The benefit of passive revocation is that clients
+can remain simple and decentralized. Passive revocation works best with short
+certificate lifetimes.
+
+`step certificates` currently only supports passive revocation. Active revocation
+is on our roadmap.
+
+## How It Works
+
+Certificates can be created and revoked through the `step cli`. Let's walk
+through some examples.
+
+### Requirements
+
+* `step` v0.10.0 ([install instructions](../README.md#installation-guide))
+
+### How It Works
+
+1. Bootstrap your PKI.
+
+   If you've already done this before and you have a `$STEPPATH` with certs,
+   secrets, and configuration files then you can move on to 1.ii.
+
+   1. Run `step ca init`.
+
+      <pre><code>
+      <b>$ step ca init --name "Local CA" --provisioner admin --dns localhost --address ":443"</b>
+      </code></pre>
+
+      Move on to step 2.
+
+   2. Configure a persistence layer in your `ca.json`.
+
+      > If you did step 1.i with `step` v0.10.0 or greater then your db will
+      > have been configured in the previous step.
+
+      Get your full step path by running `echo $(step path)`. Now edit
+      your `ca.json` by adding the following stanza as a top-level attribute:
+      > Your `ca.json` should be in `$(step path)/config/ca.json`.
+
+      ```
+        ...
+        "db": {
+          "type": "badger",
+          "dataSource": "<full step path>/db"
+        },
+        ...
+      ```
+
+      Check out our [database documentation](./database.md) to see all available
+      database backends and adapters.
+
+2. Run the CA
+
+   <pre><code>
+   <b>$ step-ca $(step path)/config/ca.json)</b>
+   </code></pre>
+
+3. Create a certificate for localhost
+
+   <pre><code>
+   <b>$ step ca certificate localhost localhost.crt localhost.key</b>
+   ✔ Key ID: n2kqNhicCCqVxJidspCQrjXWBtGwsa9zk3eBObrViy8 (sebastian@smallstep.com)
+   ✔ Please enter the password to decrypt the provisioner key:
+   ✔ CA: https://ca.smallstep.com
+   ✔ Certificate: localhost.crt
+   ✔ Private Key: localhost.key
+
+   <b>$ step certificate inspect --short localhost.crt</b>
+   X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2400...2409]
+     Subject:     localhost
+     Issuer:      Smallstep Intermediate CA
+     Provisioner: sebastian@smallstep.com [ID: n2kq...Viy8]
+     Valid from:  2019-04-23T22:55:54Z
+             to:  2019-04-24T22:55:54Z
+   </code></pre>
+
+4. Renew the certificate (just to prove we can!)
+
+   <pre><code>
+   <b>$ step ca renew localhost.crt localhost.key</b>
+   ✔ Would you like to overwrite localhost.crt [y/n]: y
+   Your certificate has been saved in localhost.crt.
+
+   # Make sure the from timestamp is "newer"
+   <b>$ step certificate inspect --short localhost.crt</b>
+   X.509v3 TLS Certificate (ECDSA P-256) [Serial: 5963...8406]
+     Subject:     localhost
+     Issuer:      Smallstep Intermediate CA
+     Provisioner: sebastian@smallstep.com [ID: n2kq...Viy8]
+     Valid from:  2019-04-23T22:57:50Z
+             to:  2019-04-24T22:57:50Z
+   </pre></code>
+
+5. Now let's revoke the certificate
+
+   <pre><code>
+   <b>$ step certificate inspect --format=json localhost.crt | jq .serial_number</b>
+   "59636004850364466675608080466579278406"
+   # the serial number is unique
+
+   <b>$ step ca revoke 59636004850364466675608080466579278406</b>
+   ✔ Key ID: n2kqNhicCCqVxJidspCQrjXWBtGwsa9zk3eBObrViy8 (sebastian@smallstep.com)
+   ✔ Please enter the password to decrypt the provisioner key:
+   ✔ CA: https://ca.smallstep.com
+   Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked.
+   </pre></code>
+
+6. Ok cool! But did it work?
+
+   <pre><code>
+   <b>$ step ca renew localhost.crt localhost.key</b>
+   error renewing certificate: Unauthorized
+
+   # log trace from CA:
+   [...]
+   WARN[0569] duration="82.782µs" duration-ns=82782
+     error="renew: certificate has been revoked"
+     fields.time="2019-04-23T16:03:01-07:00" method=POST
+     name=ca path=/renew protocol=HTTP/1.1 referer=
+     remote-address=127.0.0.1 request-id=bivpj9a3q563rpjheh5g
+     size=40 status=401 user-agent=Go-http-client/1.1 user-id=
+   [...]
+   </pre></code>
+
+7. Other ways to revoke a Certificate
+
+   Use the original certificate and key and authorize the revoke request using
+   mTLS (doesn't require a provisioner).
+
+   <pre><code>
+   <b>$ step ca revoke --cert localhost.crt --key localhost.key</b>
+   Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked.
+   </pre></code>
+
+   Or, revoke a certificate in two steps by first creating a revocation token and
+   then exchanging that token in a revocation request.
+
+   <pre><code>
+   <b>$ TOKEN=$(step ca token --revoke 59636004850364466675608080466579278406)</b>
+   ✔ Key ID: n2kqNhicCCqVxJidspCQrjXWBtGwsa9zk3eBObrViy8 (sebastian@smallstep.com)
+   ✔ Please enter the password to decrypt the provisioner key:
+
+   <b>$ echo $TOKEN | step crypto jwt inspect --insecure</b>
+   {
+     "header": {
+       "alg": "ES256",
+       "kid": "uxEunU9UhUo96lRvKgpEtRevkzbN5Yq88AFFtb1nSGg",
+       "typ": "JWT"
+     },
+     "payload": {
+       "aud": "https://localhost:443/1.0/revoke",
+       "exp": 1556395590,
+       "iat": 1556395290,
+       "iss": "sebastian@smallstep.com",
+       "jti": "1f222fc1a22530b7bcd2a40d7308c566c8e49f90413bc350e07bfabc8002b79b",
+       "nbf": 1556395290,
+       "sha": "fef4c75a050e1f3a31175ca4f4fdb711cbef1efcd374fcae4700596604eb8e5a",
+       "sub": "59636004850364466675608080466579278406"
+     },
+     "signature": "M1wX0ea3VXwS5rIim0TgtcCXHDtvP1GWD15cJSvVkrHNO6XMYl6m3ZmnWdwMi976msv-n2GTG3h6dJ3j2ImdfQ"
+   }
+
+   <b>$ step ca revoke --token $TOKEN 59636004850364466675608080466579278406</b>
+   Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked.
+   </pre></code>
+
+   Or, revoke a certificate in offline mode:
+
+   <pre><code>
+   <b>$ step ca revoke --offline 59636004850364466675608080466579278406</b>
+   Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked.
+
+   <b>$ step ca revoke --offline --cert localhost.crt --key localhost.key</b>
+   Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked.
+   </pre></code>
+
+   > NOTE: you can only revoke a certificate once. Any repeated attempts to revoke
+   > the same serial number will fail.
+
+## Now What?
+
+[Use TLS Everywhere](https://smallstep.com/blog/use-tls.html) and let us know
+what you think of our tools. Hit us on [twitter](twitter.com/smallsteplabs) or
+get in touch through our [Gitter](https://gitter.im/smallstep/community)
+to chat with us in real time.
+
+## Further Reading
+
+* [Use TLS Everywhere](https://smallstep.com/blog/use-tls.html)
+* [Everything you should know about certificates and PKI but are too afraid to ask](https://smallstep.com/blog/everything-pki.html)