smallstep-certificates/docs/revocation.md

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)

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.

   
   $ step ca init --name "Local CA" --provisioner admin --dns localhost --address ":443"
   

   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 to see all available database backends and adapters.

3. Run the CA

   
   $ step-ca $(step path)/config/ca.json
   

4. Create a certificate for localhost

   
   $ step ca certificate localhost localhost.crt localhost.key
   ✔ 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
   
   $ step certificate inspect --short localhost.crt
   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
   

5. Renew the certificate (just to prove we can!)

   
   $ step ca renew localhost.crt localhost.key
   ✔ 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"
   $ step certificate inspect --short localhost.crt
   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
   

6. Now let's revoke the certificate

   
   $ step certificate inspect --format=json localhost.crt | jq .serial_number
   "59636004850364466675608080466579278406"
   # the serial number is unique
   
   $ step ca revoke 59636004850364466675608080466579278406
   ✔ 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.
   

7. Awesome! But did it work?

   
   $ step ca renew localhost.crt localhost.key
   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=
   [...]
   

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.

   
   $ step ca revoke --cert localhost.crt --key localhost.key
   Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked.
   

   Or, revoke a certificate in two steps by first creating a revocation token and then exchanging that token in a revocation request.

   
   $ TOKEN=$(step ca token --revoke 59636004850364466675608080466579278406)
   ✔ Key ID: n2kqNhicCCqVxJidspCQrjXWBtGwsa9zk3eBObrViy8 (sebastian@smallstep.com)
   ✔ Please enter the password to decrypt the provisioner key:
   
   $ echo $TOKEN | step crypto jwt inspect --insecure
   {
     "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"
   }
   
   $ step ca revoke --token $TOKEN 59636004850364466675608080466579278406
   Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked.
   

   Or, revoke a certificate in offline mode:

   
   $ step ca revoke --offline 59636004850364466675608080466579278406
   Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked.
   
   $ step ca revoke --offline --cert localhost.crt --key localhost.key
   Certificate with Serial Number 59636004850364466675608080466579278406 has been revoked.
   

   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 and let us know what you think of our tools. Get in touch over Twitter or through our GitHub Discussions to find answers to frequently asked questions. Discord to chat with us in real time.

Further Reading

• Use TLS Everywhere
• Everything you should know about certificates and PKI but are too afraid to ask