Proposal: `WebRequest.securityInfo` API for receiving TLS certificate from web requests.

[vkrot-cell]

Summary

An API proposal to extend the webRequest API to provide TLS/QUIC certificate information for a given request.

Objective

This API enables extensions to inspect the server certificate of a web request after a secure connection has been established. This fulfills a long-standing developer need for TLS introspection, allowing for the creation of advanced security and debugging tools.
Currently, Firefox has a similar getSecurityInfo extensions API, so this proposal mostly targets other browsers.

Related Issues:

• Mozilla Bug 1322748
• Similar Chromium Proposal

Use Cases

The lack of TLS introspection prevents the development of a number of security-focused browser extensions. This API would enable extensions to:

• Replicate the functionality of security scoring tools.
• Provide more granular or prominent certificate chain introspection than the browser's built-in UI.
• Attempt to detect Man-in-the-Middle (MITM) attacks.
• Assist in debugging TLS deployment and configuration issues.

Schema

This API adds a new optional field, securityInfo, to the details object of the onHeadersReceived.

export enum OnHeadersReceivedOptions {
   // .. old fields,

   // If used, then securityInfo will be provided.
   "securityInfo",
   // The option is used to provide securityInfo with raw bytes of a server certificate.
   "securityInfoRawDer"
}

export interface Fingerprint {
    /**
     * SHA-256 hash of the certificate.
     */ 
    sha256: string;
}

export interface CertificateInfo {
    fingerprint: Fingerprint;
    rawDER: Uint8Array;
}

/**
 * Represents the state of the network connection.
 */
export enum ConnectionState {
    /**
     * The TLS handshake failed (for example, the certificate has expired).
     */
    Broken = "broken",

    /**
     * The connection is not a TLS connection.
     */
    Insecure = "insecure",

    /**
     * The connection is a secure TLS connection.
     */
    Secure = "secure"
}

export interface SecurityInfo {
    /**
     * The array contains a single CertificateInfo object, for the server certificate, or empty in case 
     * the connection state is "insecure" (http).
     */
    certificates: CertificateInfo[];
    /**
     * State of the connection.
     */
    state: ConnectionState;
}

export interface OnHeadersReceivedDetails {
    // ... existing fields
    /**
     * Information about the security of the connection. This is only
     * present if "securityInfo" is passed in the extraInfoSpec parameter
     * and the request used a secure connection.
     */
    securityInfo?: SecurityInfo;
}

Behavior

• New onHeadersReceivedOptions are necessary for performance reasons. They specify whether ssl data must be kept for as long as the web request is alive. Without them, unnecessary data can be kept for longer. Which is very undesirable especially in post quantum cryptography, since certificates can take a significant amount of memory space.
  Note that Firefox has no such an option, because it only supports blocking web requests call while there’s still ssl data.

• A new securityInfo object can be obtained in the onHeadersReceived event listener.

• To receive this information, an extension must include "securityInfo" or "securityInfoRawDer" in the extraInfoSpec array when calling addListener. This opt-in design prevents performance overhead for the majority of extensions that don't need this data.

• The securityInfo object will only be populated for requests made over a secure protocol (e.g., HTTPS, WSS) where the TLS/QUIC handshake has successfully completed or also in case of certificate errors.
  Browsers interrupt connections when there's a certificate error, unless user has explicitely allowed it in the browser UI, only in this case it is possible to have SecurityInfo with state = "broken".

• certificates - will contain only the leaf server certificate. This is done for future extensibility and Firefox API compatibility, because there they also provide a leaf if certificateChain is not included in getSecurityInfo options.

• state - State of the connection. One of:

  • "broken": the TLS handshake failed (for example, the certificate has expired)
  • "insecure": the connection is not a TLS connection
  • "secure": the connection is a secure TLS connection
  • Note that Firefox extension API has a “weak” state of connection, which does not exist in Chrome.

• The CertificateInfo.rawDER field contains the raw certificate bytes in DER format, which can be parsed by the extension using a third-party library. This field is only provided if extraInfoSpec array includes "securityInfoRawDer". The reason for it is a performance optimization to not pass raw bytes when
  it is not necessary, and compatibility with Firefox extensions API.

Example

Here is an example of an extension listening for web requests to log the server's certificate fingerprint.

chrome.webRequest.onHeadersReceived.addListener(
  (details) => {
    if (details.securityInfo && details.securityInfo.state == "secure") {
      console.log(`Received certificate for ${details.url}. The fingerprint is ${details.securityInfo.certificates[0].fingerprint.sha256}`);
    }
  },
  // Filter for requests.
  { urls: ["<all_urls>"] },
  // Opt-in to receive the security info.
  ["securityInfo"]
);

Implementation Notes

This API is designed with Firefox's webRequest.getSecurityInfo() in mind to promote cross-browser compatibility for extension developers where possible. However, there are key design differences:

• Asynchronous & Non-Blocking: Unlike Firefox's API, which is tied to blocking web requests, this proposal is fully compatible with Chrome's asynchronous, non-blocking model in Manifest V3.
  A separate getSecurityInfo() function is not be possible in Asynchronous context, because internal request data would be cleaned up after it is completed.
  For that reason there is opt-in "securityInfo", "securityInfoRawDer flags which avoid unnecessary work when the data isn't needed.

Future Work

• The SecurityInfo can be updated with more fields if necessary, such as isDomainMismatch or full list of server certificates.

[david-va]

That would be awesome.
It may also help organizations monitor, promote, and adopt PQC (PostQuantum Cryptography) usage.

[vkrot-cell]

After reading the discussion notes,
I have added Schema for the proposed API, and clarified why onHeadersReceived is unfeasible place for Chromium browser to include the event, in short words - it is not feasible technically, because of how web request is made in code. The amount of internal technical changes would be too big.

[oliverdunk]

I wasn't aware during the last meeting but this proposal was authored by @vkrot-cell who is a Googler. There has been some internal discussion of this already and we are generally supportive, hence adding the supportive: chrome label. Based on some planned refactoring in this part of the code we could quite easily implement this in the near future once we align on an API schema.

[Rob--W]

A key difference between the proposed API and Firefox's webRequest.getSecurityInfo API is that the implementation here intends to unconditionally expose the certificate information to every event, motivated by the belief that it is architecturally challenging to support Firefox's version in a non-blocking webRequest API.

In the last meeting, I suggested that it is conceptually feasible to support a method to do so: if extraInfoSpec contains a (new) "securityInfo" value, then the browser can keep track of the certificate information until the extension process has acknowledged the "handling" of the event, measured by the listener running to completion (and if it runs a Promise, the resolution/rejection of the Promise).

On event timing, you mentioned that

Information is provided on onCompleted or onErrorOccurred. This is because in Chromium's architecture, the necessary security information is not guaranteed to be available earlier in the request lifecycle (e.g., onHeadersReceived), meaning that in theory it could be possible to use onHeadersReceived, but it is unfeasible and would require a big change to network stack.

Internal implementation details aside, I would expect the certificate information to be available when point of triggering onHeadersReceived is reached, because a browser should only accept a response (and expose response headers from the server) when it verified the certificate. I can imagine architectural constrains that result in the absence of the desired information when you're about to trigger the request. The definition of an (async)webRequest.getSecurityInfo method can actually help here - the method is not bound to the same constrains as the event dispatch. E.g. if you need to hop to a different thread, that is very well possible.

Another advantage with a method is that it allows options to be specified, e.g. in Firefox's API there is the certificateChain and rawDER properties that allows extensions to opt into more information.

If some more discussion is needed before getting to the final API shape, let's do so here, but if you are also aligned on a webRequest.getSecurityInfo() method, please paste the proposal in the proposal template md document, so that it is easier to review and have per line discussions.