webRequest.SecurityInfo
=======================

An object describing the security properties of a particular web request. An object of this type is returned from the `webRequest.getSecurityInfo()` API.

If the request is not secured using TLS, then this object will contain only the property `state`, whose value will be `"insecure"`.

Type
----

Values of this type are objects. They contain the following properties:

`certificates`

`Array` of `CertificateInfo`. If `webRequest.getSecurityInfo()` was called with the `certificateChain` option present and set to `true`, this will contain a `CertificateInfo` object for every certificate in the chain, from the server certificate up to and including the trust root.

Otherwise it will contain a single `CertificateInfo` object, for the server certificate.

`certificateTransparencyStatus` Optional

`String`. Indicates the Certificate Transparency status for the connection. This may take any one of the following values:

* "not\_applicable"
* "policy\_compliant"
* "policy\_not\_enough\_scts"
* "policy\_not\_diverse\_scts"

`cipherSuite` Optional

`String`. Cipher suite used for the connection, formatted as per the TLS specification: for example, "TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256".

`errorMessage` Optional

`String`. If there was a problem with the TLS handshake (for example, the certificate had expired, or a trusted root could not be found, or a certificate was revoked) then `status` will be "broken" and the `errorMessage` property will contain a string describing the error, taken from Firefox's internal list of error codes.

Note though that at present you can only call `getSecurityInfo()` in the `onHeaderReceived` listener, and the `onHeaderReceived` event is not fired when the handshake fails. So in practice this will never be set.

`hsts` Optional

`Boolean`. `true` if the host uses Strict Transport Security, `false` otherwise.

`isDomainMismatch` Optional

`Boolean`. `true` if the server's domain name does not match the domain name in its certificate, `false` otherwise.

`isExtendedValidation` Optional

`Boolean`. `true` if the server has an Extended Validation Certificate, `false` otherwise.

`isNotValidAtThisTime` Optional

`Boolean`. `true` if the current time falls outside the server certificate's validity period (i.e. the certificate has expired or is not yet valid), `false` otherwise.

`isUntrusted` Optional

`Boolean`. `true` if a chain back to a trusted root certificate could not be constructed, `false` otherwise.

`keaGroupName` Optional

`String`. If `state` is "secure" this describes the key exchange algorithm used in this request.

`protocolVersion` Optional

`String`. Version of the TLS protocol used. One of:

* "TLSv1"
* "TLSv1.1"
* "TLSv1.2"
* "TLSv1.3"
* "unknown" (if the version is not valid)

`secretKeyLength` Optional

`Number`. The length of the secret key in bits.

`signatureSchemeName` Optional

`String`. If `state` is "secure" this describes the signature scheme used in this request.

`state`

`String`. State of the connection. One of:

* "broken": the TLS handshake failed (for example, the certificate had expired)
* "insecure": the connection is not a TLS connection
* "secure": the connection is a secure TLS connection
* "weak": the connection is a TLS connection but is considered weak. You can examine `weaknessReasons` to find out the problem.

Note though that at present you can only call `getSecurityInfo()` in the `onHeaderReceived` listener, and the `onHeaderReceived` event is not fired when the handshake fails. So in practice this will never be set to "broke".

`usedDelegatedCredentials` Optional

`Boolean`. `true` if the connection used Delegated Credentials, `false` otherwise.

`usedEch` Optional

`Boolean`. `true` if the connection used ECH (Encrypted Client Hello), `false` otherwise.

`usedOcsp` Optional

`Boolean`. `true` if the connection made an OCSP (Online Certificate Status Protocol) request, `false` otherwise.

`usedPrivateDns` Optional

`Boolean`. `true` if the connection made a private DNS lookup, such as with DoH (DNS over HTTPS), `false` otherwise.

`weaknessReasons` Optional

`String`. If `state` is "weak", this indicates the reason. Currently this may contain only a single value "cipher", indicating that the negotiated cipher suite is considered weak.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.