alexvanin/certificates
1
0
Fork 0
forked from TrueCloudLab/certificates
Code Pull requests Activity

docs: update revocation doc

Browse source
This commit is contained in:
max furman 2019-04-29 11:21:40 -07:00
parent e4de7f07e8
commit a27c2dea7d
1 changed files with 55 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

107
docs/revocation.md
View file

@ -1,15 +1,18 @@
# Revocation # Revocation
**Active Revocation**: A certificate is no longer valid from the moment it has **Active Revocation**: A certificate is no longer valid from the moment it has
been actively revoked. Clients are required to check verify certificate validity been actively revoked. Clients are required to check against centralized
against CRLs (Certificate Revocation Lists) or use OCSP (Online Certificate sources of certificate validity information (e.g. by using CRLs (Certificate
Status Protocol). Active Revocation requires clients to take an active role Revocation Lists) or OCSP (Online Certificate Status Protocol)) to
in certificate validation for the benefit of real time revocation. verify that certificates have not been revoked. 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 **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, 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 but cannot be prolonged. The benefit of passive revocation is that clients
can remain simple and decentralized. Passive revocation works best with short can verify certificates in a simple, decentralized manner without relying on
centralized 3rd parties. Passive revocation works best with short
certificate lifetimes. certificate lifetimes.
`step certificates` currently only supports passive revocation. Active revocation `step certificates` currently only supports passive revocation. Active revocation
@ -18,55 +21,55 @@ is on our roadmap.
## How It Works ## How It Works
Certificates can be created and revoked through the `step cli`. Let's walk Certificates can be created and revoked through the `step cli`. Let's walk
through some examples. through an example.
### Requirements ### Requirements
* `step` v0.10.0 ([install instructions](../README.md#installation-guide)) * `step` (>=v0.10.0) ([install instructions](../README.md#installation-guide))
### How It Works ### Let's Get To It
1. Bootstrap your PKI. 1. Bootstrap your PKI.
If you've already done this before and you have a `$STEPPATH` with certs, > 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. > secrets, and configuration files then you can move on to step 2.
1. Run `step ca init`. 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> <pre><code>
<b>$ step-ca $(step path)/config/ca.json)</b> <b>$ step ca init --name "Local CA" --provisioner admin --dns localhost --address ":443"</b>
</code></pre> </code></pre>
3. Create a certificate for localhost Move on to step 3.
2. Configure a persistence layer in your `ca.json`.
> If you did step 1 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.
3. Run the CA
<pre><code>
<b>$ step-ca $(step path)/config/ca.json</b>
</code></pre>
4. Create a certificate for localhost
<pre><code> <pre><code>
<b>$ step ca certificate localhost localhost.crt localhost.key</b> <b>$ step ca certificate localhost localhost.crt localhost.key</b>
@ -85,7 +88,7 @@ through some examples.
to: 2019-04-24T22:55:54Z to: 2019-04-24T22:55:54Z
</code></pre> </code></pre>
4. Renew the certificate (just to prove we can!) 5. Renew the certificate (just to prove we can!)
<pre><code> <pre><code>
<b>$ step ca renew localhost.crt localhost.key</b> <b>$ step ca renew localhost.crt localhost.key</b>
@ -102,7 +105,7 @@ through some examples.
to: 2019-04-24T22:57:50Z to: 2019-04-24T22:57:50Z
</pre></code> </pre></code>
5. Now let's revoke the certificate 6. Now let's revoke the certificate
<pre><code> <pre><code>
<b>$ step certificate inspect --format=json localhost.crt | jq .serial_number</b> <b>$ step certificate inspect --format=json localhost.crt | jq .serial_number</b>
@ -116,7 +119,7 @@ through some examples.
Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked. Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked.
</pre></code> </pre></code>
6. Ok cool! But did it work? 7. Awesome! But did it work?
<pre><code> <pre><code>
<b>$ step ca renew localhost.crt localhost.key</b> <b>$ step ca renew localhost.crt localhost.key</b>
@ -133,10 +136,10 @@ through some examples.
[...] [...]
</pre></code> </pre></code>
7. Other ways to revoke a Certificate 8. Other ways to revoke a Certificate
Use the original certificate and key and authorize the revoke request using Use the certificate and key. This method does not require a provisioner
mTLS (doesn't require a provisioner). because it uses the certificate and key to authenticate the request.
<pre><code> <pre><code>
<b>$ step ca revoke --cert localhost.crt --key localhost.key</b> <b>$ step ca revoke --cert localhost.crt --key localhost.key</b>
@ -188,12 +191,12 @@ through some examples.
> NOTE: you can only revoke a certificate once. Any repeated attempts to revoke > NOTE: you can only revoke a certificate once. Any repeated attempts to revoke
> the same serial number will fail. > the same serial number will fail.
## Now What? ## What's next?
[Use TLS Everywhere](https://smallstep.com/blog/use-tls.html) and let us know [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 what you think of our tools. Get in touch over
get in touch through our [Gitter](https://gitter.im/smallstep/community) [twitter](twitter.com/smallsteplabs) or through our
to chat with us in real time. [Gitter](https://gitter.im/smallstep/community) to chat with us in real time.
## Further Reading ## Further Reading