forked from TrueCloudLab/certificates
210 lines
7.5 KiB
Markdown
210 lines
7.5 KiB
Markdown
# Revocation
|
|
|
|
**Active Revocation**: A certificate is no longer valid from the moment it has
|
|
been actively revoked. Clients are required to check against centralized
|
|
sources of certificate validity information (e.g. by using CRLs (Certificate
|
|
Revocation Lists) or OCSP (Online Certificate Status Protocol)) to
|
|
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
|
|
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 verify certificates in a simple, decentralized manner without relying on
|
|
centralized 3rd parties. Passive revocation works best with short
|
|
certificate lifetimes.
|
|
|
|
`step certificates` currently only supports passive revocation. Active revocation
|
|
is on our roadmap.
|
|
|
|
Run `step help ca revoke` from the command line for full documentation, list of
|
|
command line flags, and examples.
|
|
|
|
## How It Works
|
|
|
|
Certificates can be created and revoked through the `step cli`. Let's walk
|
|
through an example.
|
|
|
|
### Requirements
|
|
|
|
* `step` (>=v0.10.0) ([install instructions](../README.md#installation-guide))
|
|
|
|
### Let's Get To It
|
|
|
|
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 step 2.
|
|
|
|
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 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>
|
|
<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>
|
|
|
|
5. 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>
|
|
|
|
6. 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>
|
|
|
|
7. Awesome! 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>
|
|
|
|
8. Other ways to revoke a Certificate
|
|
|
|
Use the certificate and key. This method does not require a provisioner
|
|
because it uses the certificate and key to authenticate the request.
|
|
|
|
<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.
|
|
|
|
Run `step help ca revoke` from the command line for full documentation, list of
|
|
command line flags, and examples.
|
|
|
|
## What's next?
|
|
|
|
[Use TLS Everywhere](https://smallstep.com/blog/use-tls.html) and let us know
|
|
what you think of our tools. Get in touch over
|
|
[Twitter](twitter.com/smallsteplabs) or 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)
|