--- layout: default title: The pwnedkeys Revokinator --- An SSL certificate that uses a compromised key is a major hazard. Anyone with the compromised key could impersonate the websites listed in the certificate, and collect all the information sent to the website (including personal information, passwords, etc), and serve malware to the visitors to the impersonator. For that reason, whenever pwnedkeys finds out about a key that is used by a publicly-trusted SSL certificate, it contacts the issuing CA and lets it know that the certificate's key is compromised. While revocation of WebPKI certificates is far from perfect (in fact, it [isn't particularly useful at all](https://www.imperialviolet.org/2014/04/19/revchecking.html)), it is the best we've got, and it has the side-effect of notifying a CA that they *absolutely* shouldn't be issuing more certificates with that key, so that at least we won't get any *new* certificates with that same, already-compromised, key. This revocation notification, and subsequent monitoring that revocation has actually taken place, is done by the pwnedkeys Revokinator. # How The Revokinator Works In addition to scanning the Internet for exposed private keys, pwnedkeys also downloads all the certificates logged in [Certificate Transparency](https://certificate.transparency.dev) logs. The public keys in all these certificates are matched against known-compromised keys in the pwnedkeys dataset, and an index is kept of the certificates' public keys to match against any newly-discovered compromised keys. When a match is found, the CA who issued the certificate is notified of the compromised key, which means they need to revoke all certificates which use that key. In addition, the Revokinator keeps a regular watch on OCSP responses, to ensure that the certificate(s) involved actually do get revoked, how long that takes to happen, and ensures that they *stay* revoked until the certificate expires. This is an important additional function, as it identifies deficiencies in CAs' revocation processing, which has historically had demonstrated failures across a wide spectrum of the CA ecosystem. # Types of Compromise Notification There are two ways that a key and certificate can match against each other, and due to the way that pwnedkeys maintains the security of compromised keys, they require different methods notifying the CA of compromise. If the certificate is new, and matches against an existing key, that indicates that the CA issued a certificate for a key that was *already publicly known to be compromised*. This sounds bad, and it is, but there's no requirement for a CA to do reasonable due diligence on the keys they issue certificates for, so it happens. We call this an "existing compromise" notification, and handle it by sending the CA an email with a link to the compromise attestation provided by the [pwnedkeys API](/api/). This is the only way we can perform these notifications, as the actual compromised private keys are not stored online, so an interactive revocation request (such as that available via ACME) is not possible. When a new key is found that matches against an existing certificate, however, the key is still available online, and we can do what we call a "live key" notification. ## Live Key Notification When a key is first found, it goes through the pwnedkeys processing pipeline, which generates the compromise attestations served by the [pwnedkeys API](/api/), updates cert-matching bloom filters, and writes an encrypted copy of the private key to the "cold store" of private keys, amongst other things. Part of the processing pipeline is checking the key against the index of keys used in certificates. When a match is found, we want to notify CAs of the compromised key. Because we still have the private key "in hand", as it were, we can use methods which require the use of the private key. The (only) method we support is the `revokeCert` endpoint specified by [the ACME protocol](https://datatracker.ietf.org/doc/html/rfc8555#section-7.6). CA-specific methods are not supported, because they are subject to change at any time, and require custom implementation work by pwnedkeys -- time that would be better spent improving pwnedkeys for everyone. Since not all CAs have an ACME server that is capable of receiving `revokeCert` requests, we fallback to sending an email containing the key compromise attestation to the CA's registered contact address if `revokeCert` is unavailable. To make it clear that the CA could have avoided having to process the email notification by setting up an ACME server capable of processing `revokeCert` notifications, all "live key" email notifications are clearly labeled as such. ### Registering to Receive ACME Live Key Notifications If you are a CA and have received a pwnedkeys "live key" email notification, and would like to instead receive live key revocation requests via ACME, here's what you need to do. 1. Setup a publicly-accessible ACME server capable of processing ACME `revokeCert` requests. You don't even have to run a full ACME implementation -- you can use the freely-available [`acmevoke`](https://github.com/tobermorytech/acmevoke) server to provide *just* the `revokeCert` endpoint. 2. Amend your issuing CA records in the [CCADB](https://ccadb.org/) to list the directory URL of your ACME server. 3. Amend your CPS to acknowledge that your ACME server is a valid contact point for Certificate Problem Reports, and include its URL. 4. Send an email to `revokinator@pwnedkeys.com` listing: * Your issuing CA certificate subject(s); * The ACME directory URL; * A link to the CPS document (*not* your repository) that contains the amendments above. The pwnedkeys team will evaluate your request, and amend our records to suit if everything is in order. Note that, if your ACME server fails to accept a `revokeCert` request, an email will be sent for that notification instead, and repeated failures will result in your ACME server being delisted and all future notifications sent via email.