Extend the webRequest.onCompleted event details object with TLS/SSL information

extensions/common/api/web_request.json

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 [
   {
     "namespace": "webRequest",
     "description": "Use the <code>chrome.webRequest</code> API to observe and analyze traffic and to intercept, block, or modify requests in-flight.",
     "properties": {
       "MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES": {
@@ skipping 132 matching lines @@
             "optional": true,
             "description": "An ArrayBuffer with a copy of the data."
           },
           "file": {
             "type": "string",
             "optional": true,
             "description": "A string with the file's path and name."
           }
         },
         "description": "Contains data uploaded in a URL request."
+      },
+      {
+        "id": "SSLVersions",
+        "type": "string",
+        "enum": ["UNKNOWN", "SSL 2.0", "SSL 3.0", "TLS 1.0", "TLS 1.1", "TLS 1.2", "QUIC"]

[elawrence, 2016/08/10 14:46:47]

Does it make sense to add "TLS 1.3" now, given that prototype implementations
are underway? Is there any way to make an SSL2 connection in Chrome? Do we need
version numbers for QUIC?

[davidben, 2016/08/10 19:42:14]

Indeed a very early stages TLS 1.3 implementation exists behind an about:flags
toggle already!

[rolandshoemaker, 2016/08/15 03:38:33]

Acknowledged.

+      },
+      {
+        "id": "CipherNames",
+        "type": "string",
+        "enum": ["UNKNOWN", "NULL", "RC4_40", "RC4_128", "RC2_CBC_40", "IDEA_CBC", "DES40_CBC", "DES_CBC", "3DES_EDE_CBC", "AES_128_CBC", "AES_256_CBC", "CAMELLIA_128_CBC", "CAMELLIA_256_CBC", "SEED_CBC", "AES_128_GCM", "AES_256_GCM", "CAMELLIA_128_GCM", "CAMELLIA_256_GCM", "CHACHA20_POLY1305"]

[davidben, 2016/08/10 19:42:14]

(Most of these are things we do not and will never support, FWIW.)

+      },
+      {
+        "id": "KeyExchangeNames",
+        "type": "string",
+        "enum": ["UNKNOWN", "NULL", "RSA", "RSA_EXPORT", "DH_DSS_EXPORT", "DH_DSS", "DH_RSA_EXPORT", "DH_RSA", "DHE_DSS_EXPORT", "DHE_DSS", "DHE_RSA_EXPORT", "DHE_RSA", "DH_anon_EXPORT", "DH_anon", "ECDH_ECDSA", "ECDHE_ECDSA", "ECDH_RSA", "ECDHE_RSA", "ECDH_anon"]

[davidben, 2016/08/10 19:42:14]

How will this work with TLS 1.3 which is expected to (change still in a PR) look
totally different here?

Instead what used to be called NamedCurve in TLS 1.2 (a sub-negotiated part of
ECDHE) is going to be morally the key exchange with values like secp256r1,
x25519, ffdhe2048, etc.

The _RSA and _ECDSA half for signing-based exchanges is no longer negotiated as
part of the cipher at all. Instead it is, like in TLS 1.2 but not 1.1 and below,
part of a signature algorithm negotiation which gives back signature algorithms
like rsa_pkcs1_sha256 or rsa_pss_sha256 or ecdsa_p256_sha256.

DevTools will need a change here too, but especially if we're doing something
where we're committing to an API, this needs some care.

If we're decomposing, it should be patterned after TLS 1.3 which actually
decomposes. If not patterned after TLS 1.3, it should not try to decompose at
all and just give you TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 which will turn into
TLS_AES_128_GCM_SHA256 in TLS 1.3 with additional fields for the things on the
side.

This currently does neither and decomposes yet does not match any true
decomposition in any version of the protocol.

[rolandshoemaker, 2016/08/15 03:38:33]

The 'CipherNames', 'KeyExchangeNames', and 'MACNames' fields are extracted from
the SSLInfo.connection_status bitmap using net::SSLCipherSuiteToStrings.
Currently if the cipher is AEAD the 'MACName' will be, grossly, be set to
'NULL'.

Given that the strings produced by this function seem to be the standard format
here, and as far as I can currently tell the DevTools/Certificate info UI, I'm
not really sure what the best path forward is.

[davidben, 2016/08/15 19:09:34]

They're not really standard format. They're used in one part of the UI which is
going to need changing for TLS 1.3. UI is easy because we can change it.
Extensions APIs are forever, so it is extremely important that we get that
right. I do not think it would be acceptable to ship this API as it stands.

[alex.gaynor, 2016/08/19 15:53:36]

As one of the folks interested in this API, I think exposing simply the "fully
composed" version is sufficient for my needs.

+      },
+      {
+        "id": "MACNames",
+        "type": "string",
+        "enum": ["UNKNOWN", "NULL", "HMAC-MD5", "HMAC-SHA1", "HMAC-SHA256", "HMAC-SHA384"]

[davidben, 2016/08/10 19:42:13]

What is returned for modern ciphers like AEADs? Best practices these days are
*NOT* split up encryption and integrity and use one pre-composed primitive. To
that end, it might be better to report values like:

- AES_256_GCM
- AES_128_GCM
- CHACHA20_POLY1305
- AES_128_CBC_SHA
- RC4_MD5 (no longer supported)

This also aligns with BoringSSL's implementation which pretends everything is
vaguely AEAD-shaped.

+      },
+      {
+        "id": "ValidationErrors",
+        "type": "string",
+        "enum": ["ERR_CERT_REVOKED", "ERR_CERT_INVALID", "ERR_SSL_PINNED_KEY_NOT_IN_CERT_CHAIN", "ERR_CERT_AUTHORITY_INVALID", "ERR_CERT_COMMON_NAME_INVALID", "ERR_CERT_NAME_CONSTRAINT_VIOLATION", "ERR_CERT_WEAK_SIGNATURE_ALGORITHM", "ERR_CERT_WEAK_KEY", "ERR_CERT_DATE_INVALID", "ERR_CERT_VALIDITY_TOO_LONG", "ERR_CERT_UNABLE_TO_CHECK_REVOCATION", "ERR_CERT_NO_REVOCATION_MECHANISM"]
+      },
+      {
+        "id": "DistinguishedName",
+        "type": "object",
+        "properties": {
+          "commonName": {
+            "type": "string",
+            "optional": true,
+            "description": "Subject Common Name."
+          },
+          "localityName": {
+            "type": "string",
+            "optional": true,
+            "description": "Subject Locality Name."
+          },
+          "stateOrProvinceName": {
+            "type": "string",
+            "optional": true,
+            "description": "Subject State or Province Name."
+          },
+          "countryName": {
+            "type": "string",
+            "optional": true,
+            "description": "Subject Country Name."
+          },
+          "streetAddresses": {
+            "type": "array",
+            "items": { "type": "string" },
+            "optional": true,
+            "description": "Subject Street Addresses."
+          },
+          "organizationNames": {
+            "type": "array",
+            "items": { "type": "string" },
+            "optional": true,
+            "description": "Subject Organization Names."
+          },
+          "organizationUnitNames": {
+            "type": "array",
+            "items": { "type": "string" },
+            "optional": true,
+            "description": "Subject Organization Unit."
+          },
+          "domainComponents": {
+            "type": "array",
+            "items": { "type": "string" },
+            "optional": true,
+            "description": "Additional domain components."
+          }
+        }
+      },
+      {
+        "id": "Certificate",
+        "type": "object",
+        "properties": {
+          "raw": {
+            "type": "binary",
+            "optional": true,
+            "description": "ArrayBuffer containing the DER encoded certificate."
+          },
+          "serialNumber": {
+            "type": "string",
+            "description": "The serial number of the certificate."
+          },
+          "subject": {
+            "$ref": "DistinguishedName",
+            "description": "The subject of the certificate"

[elawrence, 2016/08/10 14:46:47]

Other descriptions end with a period.

+          },
+          "issuer": {
+            "$ref": "DistinguishedName",
+            "optional": true,
+            "description": "The issuer subject of the certificate"

[elawrence, 2016/08/10 14:46:47]

Other descriptions end with a period.

+          },
+          "expired": {
+            "type": "boolean",
+            "description": "True if the certificate is expired."
+          },
+          "notBefore": {
+            "type": "number",
+            "description": "notBefore time of the certificate"

[elawrence, 2016/08/10 14:46:47]

Other descriptions end with a period.

+          },
+          "notAfter": {
+            "type": "number",
+            "description": "notAfter time of the certificate"

[elawrence, 2016/08/10 14:46:47]

Other descriptions end with a period.

+          },
+          "DNSNames": {
+            "type": "array",
+            "items": { "type": "string" },
+            "optional": true,
+            "description": "Array of DNS names contained in the certificate."
+          },
+          "IPAddresses": {
+            "type": "array",
+            "items": { "type": "string" },
+            "optional": true,
+            "description": "Array of IP Addresses contained in the certificate."
+          }
+        }
+      },
+      {
+        "id": "ConnectionInfo",
+        "type": "object",
+        "properties": {
+          "cipherName": {
+            "$ref": "CipherNames",
+            "description" :"Name of cipher used"

[elawrence, 2016/08/10 14:46:47]

Other descriptions end with a period.

+          },
+          "keyExchangeName": {
+            "$ref": "KeyExchangeNames",
+            "description" :"Name of key exchange technique used."
+          },
+          "macName": {
+            "$ref": "MACNames",
+            "optional": true,
+            "description" :"Name of MAC used."
+          },
+          "deflateCompression": {

[elawrence, 2016/08/10 14:46:47]

Is there any way to enable (unsafe) deflateCompression any longer?

[davidben, 2016/08/10 19:42:13]

Nope. BoringSSL does not even implement it.

[rolandshoemaker, 2016/08/15 03:38:33]

Acknowledged.

+            "type": "boolean",
+            "optional": true,
+            "description": "True if deflate compression was used."
+          },
+          "sslVersion": {
+            "$ref": "SSLVersions",
+            "description": "The version of TLS used"
+          },
+          "versionFallback": {
+            "type": "boolean",
+            "optional": true,
+            "description": "True if TLS fallback occurred."
+          },
+          "noRenegotiationExtension": {
+            "type": "boolean",
+            "optional": true,
+            "description": "True if the no renegotiation extension was sent."
+          }
+        }
+      },
+      {
+        "id": "SSLInfo",
+        "type": "object",
+        "properties": {
+          "connectionInfo": {
+            "$ref": "ConnectionInfo",
+            "description": "Information about the ciphers and protocols used to establish the underlying connection."
+          },
+          "sentChain": {
+            "type": "array",
+            "optional": true,
+            "description": "Array of Certificates that was sent by the server.",

[elawrence, 2016/08/10 14:46:47]

Is this the list of exactly what the server sent? Or the path we built? Servers
can send certs that aren't in the actual path, can't they?

[rolandshoemaker, 2016/08/15 03:38:33]

This is pulled from SSLInfo.unverified_cert which is documented as being '[t]he
SSL certificate as received by the client' and is differentiated from the chain
built during validation.

+            "items": {
+              "$ref": "Certificate"
+            }
+          },
+          "builtChain": {
+            "type": "object",
+            "optional": true,
+            "description": "An object containing information about the certificate chain that was built from the sent certificates.",
+            "properties": {
+              "valid": {
+                "type": "boolean",
+                "description": "True if built chain is valid."
+              },
+              "issuedByKnownRoot": {
+                "type": "boolean",
+                "description": "True if the leaf certificate issued by known root."

[elawrence, 2016/08/10 14:46:47]

I think this is "True if the leaf certificate has a valid path to a known root."
?

+              },
+              "extendedValidation": {
+                "type": "boolean",
+                "description": "True if the leaf certificate is EV."
+              },
+              "revocationCheckingEnabled": {
+                "type": "boolean",
+                "description": "True if reovcation checking for certificates in the chain is enabled."

[elawrence, 2016/08/10 14:46:47]

Typo: s/reovcation/revocation

+              },
+              "errors": {
+                "type": "array",
+                "description": "List of validation errors for the certificate chain.",
+                "optional": true,
+                "items": {
+                  "$ref": "ValidationErrors"

[davidben, 2016/08/10 19:42:13]

[Anything certificate-related like this should not ship without rsleevi's
approval. He would know better which things we should and should not commit to
indefinitely by way of an extensions API.]

+                }
+              },
+              "nonUniqueName": {
+                "type": "boolean",
+                "optional": true,
+                "description": "True if a certificate in the chain contains non unique names."
+              },
+              "sha1SignaturePresent": {

[davidben, 2016/08/10 19:42:13]

This sort of thing is a temporary (albeit very very long-lived) deprecation
thing. It is probably better not to burn this kind of thing into the extensions
API. That's something the consumer can extract from the certificate chain if it
wants to.

But, again, rsleevi's preferences are definitive here.

+                "type": "boolean",
+                "optional": true,
+                "description": "True if a certificate in the chain uses a SHA1 signature."

[elawrence, 2016/08/10 14:46:47]

Excluding the root, right?

+              },
+              "ctComplianceFailed": {
+                "type": "boolean",
+                "optional": true,
+                "description": "True if a certificate in the chain fails CT compliance checks."
+              },
+              "chain": {
+                "type": "array",
+                "description": "Array of Certificates built from the sent chain.",
+                "items": {
+                  "$ref": "Certificate"
+                }
+              }
+            }
+          }
+        }
       }
     ],
     "functions": [
       {
         "name": "handlerBehaviorChanged",
         "type": "function",
         "description": "Needs to be called when the behavior of the webRequest handlers has changed to prevent incorrect handling due to caching. This function call is expensive. Don't call it often.",
         "parameters": [
           {"type": "function", "name": "callback", "optional": true, "parameters": []}
         ]
@@ skipping 355 matching lines @@
               "method": {"type": "string", "description": "Standard HTTP method."},
               "frameId": {"type": "integer", "description": "The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (<code>type</code> is <code>main_frame</code> or <code>sub_frame</code>), <code>frameId</code> indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab."},
               "parentFrameId": {"type": "integer", "description": "ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists."},
               "tabId": {"type": "integer", "description": "The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab."},
               "type": {"$ref": "ResourceType", "description": "How the requested resource will be used."},
               "timeStamp": {"type": "number", "description": "The time when this signal is triggered, in milliseconds since the epoch."},
               "ip": {"type": "string", "optional": true, "description": "The server IP address that the request was actually sent to. Note that it may be a literal IPv6 address."},
               "fromCache": {"type": "boolean", "description": "Indicates if this response was fetched from disk cache."},
               "statusCode": {"type": "integer", "description": "Standard HTTP status code returned by the server."},
               "responseHeaders": {"$ref": "HttpHeaders", "optional": true, "description": "The HTTP response headers that were received along with this response."},
-              "statusLine": {"type": "string", "description": "HTTP status line of the response or the 'HTTP/0.9 200 OK' string for HTTP/0.9 responses (i.e., responses that lack a status line) or an empty string if there are no headers."}
+              "statusLine": {"type": "string", "description": "HTTP status line of the response or the 'HTTP/0.9 200 OK' string for HTTP/0.9 responses (i.e., responses that lack a status line) or an empty string if there are no headers."},
+              "sslInfo": {"$ref": "SSLInfo", "optional": true, "description": "Optional information about the underlying SSL/TLS transport, if one was used."}

[elawrence, 2016/08/10 14:46:47]

Is sslInfo the best name, given that the protocol will almost never be SSL?

[rolandshoemaker, 2016/08/15 03:38:33]

Good point, I originally thought about just using tlsInfo but ended up using
what is already used internally, do you think that would be better?

             }
           }
         ],
         "extraParameters": [
           {
             "$ref": "RequestFilter",
             "name": "filter",
             "description": "A set of filters that restricts the events that will be sent to this listener."
           },
           {
@@ skipping 34 matching lines @@
           {
             "$ref": "RequestFilter",
             "name": "filter",
             "description": "A set of filters that restricts the events that will be sent to this listener."
           }
         ]
       }
     ]
   }
 ]