webRequest SSL Hooks

Proposal Date


Who is the primary contact for this API?

Ryan Sleevi (rsleevi@chromium.org)

Who will be responsible for this API? (Team please, not an individual)

Networking or Privacy or Security


This proposal seeks to add bindings for extensions that allow them to participate in the SSL/TLS certificate validation process. Information such as certificate chains and connection strength will be provided to extensions, and they will be allowed to reject certificate chains based on extension-specific determinations.

Use cases

In light of recent CA compromises, mis-issued certificates, and man-in-the-middle certificates being issued, increased scrutiny is being placed on the CA infrastructure, and a number of new and novel approaches for solving various deficiencies have been proposed. These include:
  • CRLSets, an alternative form of revocation checking (compared to CRLs or OCSP)
  • TACK, a way of providing a certificate extension that site operators can use to provide information about their 'authorized' CAs.
  • Certificate Pinning, an HTTP header that lets sites indicate public keys that clients should expect to see in certificate chains for the site.
  • Sovereign Keys, a proposal for a notary-style database of certificates issued, so that clients can detect fraudulantly issued keys.
  • Certificate Transparency, an alternative proposal that seeks to accomplish similar goals as TACK and Sovereign Keys.
In addition, several Firefox extensions exist that integrate (sometimes in unofficial/unsanctioned means) with Firefox's SSL certificate validation code to provide users assurances about the sites they talk to:
  • Certificate Patrol, designed to warn users when a site's certificate changes to a new authority.
  • Perspectives, an extension that will bypass SSL warnings if 'many' notaries agree that the server is using that certificate, and which will raise warnings if not enough notaries agree.
  • Convergence, a notary-based system designed to solve some of the deficiencies of Perspectives.
In order to facilitate rapid experimentation for a number of different approaches, the extension API should surface enough details about Chromium's SSL stack to allow such existing extensions and to allow implementing these different verification schemes as extensions.

Do you know anyone else, internal or external, that is also interested in this API?

Interest has been expressed by authors for some of the above extensions, both on the appropriate Chromium tracking bug and on Mozilla's equivalent tracking bug.

Could this API be part of the web platform?

This API is fairly connected to Chromium's network implementation and extension APIs, and therefore may not be suitable for general usage as a standards-track API.

Do you expect this API to be fairly stable?  How might it be extended or changed in the future?

The core API (callbacks during certificate validation) are expected to be highly stable, as it's unlikely that Chrome will ever avoid validating certificates. This API currently only covers validating SSL server certificates, however, in the future this may be extended to other types of certificate validation not directly tied to server certificates (examples: client certificate selection, importation of client and intermediate CA certificates via application/x-x509-(user, ca)-cert, code-signing validation as part of Safe Browsing, etc.).

Additionally, the errors presented in the verificationStatus may be expanded or replaced.

List every UI surface belonging to or potentially affected by your API:

The Page Info Bubble and SSL Certificate Error Interstitial pages may be updated to indicate to the user that an extension denied access to a particular site for some extension-specific reason, along with links for more information.

How could this API be abused?

Many of the same privacy concerns that apply to webRequest in general would apply to this API. Extensions with permissions to this would be able to track which URLs a user is accessing, by way of the server certificate presented, and may be able to deny the user access to legitimate sites.

Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you could commit with your API (if you’ve got good ones, feel free to add more):

1) Implicitly track the user by recording the site names in the certificates they encounter.
2) Deny access to legitimate HTTPS sites as a way of forcing the user to downgrade to HTTP.
3) Possibly cause a downgrade attack from an EV status to a DV status, by introducing soft-fail revocation errors.

Alright Doctor, one last challenge:  
Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?


How would you implement your desired features if this API didn't exist?

In the case of Chromium-supported initiatives (CRLSets, Certificate Pinning), such code has been implemented within Chromium itself as native code. This creates an imbalance in favour of Chromium for experimentation, rather than allowing the web at large to participate.

For non-Chromium-supported initiatives, such as Convergence, this has been implemented by requiring the user to connect to a locally running proxy, which then mediates all SSL connections on behalf of the browser. This reduces the ability to innovate and experiment with new SSL/TLS features, as it breaks the end-to-end guarantees of SSL/TLS.

Draft API spec



chrome.experimental.ssl.onCertificateVerify.addListener( function(object details) { ... }, RequestFilter filter, array of string extraInfoSpec);
Fires after Chrome has verified the SSL/TLS certificate for a connection.

details (object)
hostname (string)
The host name or IP address literal that the certificate is being verified for. This corresponds to the "reference identifier", as described in RFC 6125, Section 1.8.
constructedChain (array of strings)
The certificate chain that was constructed by Chromium during internal certificate verification.
Each certificate in the chain will be a string, base64 encoded, (should this be Uint8Array/ArrayBuffer? Should it be like binaryValue of HttpHeaders?), with the first index corresponding to the server certificate, and each subsequent index corresponding to the issuer of the previous certificate, up to the trust anchor or root certificate.
This chain may be incomplete if Chromium was unable to construct a chain to a known/trusted root, or if errors occurred while processing.
verificationStatus (object)
The details from Chromium's built-in certificate verification logic. Extensions may use this to further inform the decision making process.
errors (array of strings) (TBD: Rather than using a string enumeration, consider providing a more meaningful error object with boolean properties).
status_flags (array of strings)
"builtin_root" (TBD: This is a hard-coded list in Chrome and is intended as a rough heuristic as to whether there is a sanctioned MITM, such as corporate monitoring, or an unsanctioned, hostile MITM. It may not be appropriate to expose)
filter (optional RequestFilter)
Extra information that needs to be passed into the callback function. Each element of extraInfoSpec requires a corresponding string property being added to the details object. Array elements can be:
    • "peerChain"The explicit list of certificates the SSL peer supplied. An array of strings, in the same format as constructedChain. Due to how PKIX path validation is implemented, the peerChain may differ substantially from the actual constructedChain, with the only item in common between the two being the first certificate (the server certificate). Extensions which rely on in-band signalling of extra information by way of an extra certificate, such as TACK, will need to obtain the original chain, as the verified chain will not include the TACK certificate.
    • "blocking" - Indicates that the extension will perform secondary verification, and the connection should not proceed until the callback returns.
If blocking is present, the callback function can return an object to modify the verification result.
result (optional object)
cancel (optional boolean)
Set to true to cancel the request.
custom_errors (optional array of strings)
A set of errors to associate with the certificate chain. These are additive to the existing Chromium errors from verificationStatus. Any unrecognized strings will be treated as if the certificate was invalid. (If extensions have custom error pages, this may not be necessary or helpful. Most extensions under discussion would want to set "revoked", but they want to set a more meaningful extension-specific error message explaining why it's revoked.)


  • Q. Should extensions be allowed to say "This certificate is good" when Chromium says otherwise? A. Not in the initial release of this extension API. While this may be useful for some extensions, particularly those that aim to wholly replace the CA infrastructure, there are inherent security risks and usability concerns associated with this. In the future, it is expected this will be re-evaluated to see where a secure solution can be found. See also http://code.google.com/p/chromium/issues/detail?id=2010 to better understand these concerns.
  • Q. Should extensions be allowed to extend the SSL certificate error interstitial page to display custom, extension specific error information? A. This is something being actively considered, with the API to be determined.
  • Q. Will extensions be permitted to make blocking network requests during validation, such as to a secondary notary service (Perspectives, Convergence)? A. This is not something that should be encouraged, though it may technically be possible. In general, making any form of blocking sub-request during the processing of webRequest callbacks can have significant usability and performance concerns. Such extensions are encouraged to use other methods to distribute revocation/validity information that do not require blocking during subrequest processing.