The following terms are defined in the DNS specification: [[!RFC1034]]
+The following terms are defined in the Fetch specification: [[!FETCH]]
@@ -139,6 +148,7 @@The following terms are defined in the Secure Contexts specification: [[!SECURE-CONTEXTS]]
+ Regardless of which fetch algorithm and which underlying application and + transport protocols are used, servicing a network request consists + of the following phases: +
+ ++ The only mandatory phase is the transmission of request and + response; the other phases might not be needed for every network + request. For instance, DNS results can be cached locally in the + user agent, eliminating DNS resolution for future requests to the + same domain. Similarly, HTTP persistent connections allow open + connections to be shared for multiple requests to the same origin. + However, if multiple phases occur, they will occur in the above + order. +
+ ++ We would like to move the definition of these phases into [[FETCH]] so + that they are more reusable. +
+A network request is successful if the user agent is able @@ -298,6 +351,28 @@
+ Each network error has a phase, which describes which phase the + error occurred in: +
+ +dnsconnectionapplicationThere are several predefined network error types defined in . @@ -314,6 +389,12 @@
+ Each NEL policy has a received IP address, which is the + IP address of the server that the user agent received this NEL + policy from. +
+Each NEL policy has an origin. @@ -536,15 +617,16 @@
Potentially Trustworthy.
+ The result of executing the "Is origin potentially
+ trustworthy?" algorithm on request's
+ origin is not Potentially
+ Trustworthy.
+ Plumb this through more explicitly in [[FETCH]]. +
+Potentially Trustworthy, abort these steps.
+ If the result of executing the "Is origin potentially
+ trustworthy?" algorithm on request's origin is
+ not Potentially Trustworthy, abort these
+ steps.
phase"application".
+ typeserver_ip property is
+ non-empty, and not equal to policy's received IP
+ address:
+
+ phase to
+ dns. type to
+ dns.address_changed.
+ status_code and
+ elapsed_time properties.
+ + This step "downgrades" a NEL report if the IP addresses of the + server and the policy don't match. + This is a privacy protection, ensuring that NEL reports are only sent + to the owner of the service that the report describes. If the IP + addresses don't match, then the user agent can only verify that the + NEL policy was sent by the owner of the origin's + domain name; it cannot verify that the policy was sent by the + owner of the server this domain name resolves to. We + therefore downgrade the report to only contain information about + DNS resolution. See and + for more details. +
+include,
+ and request body's phase property is not
+ dns, abort these steps.
+ Queue the report for delivery via the Reporting API. [[!REPORTING]]
@@ -848,16 +993,40 @@
+ All of the network errors in this section occur during DNS
+ resolution, and therefore have a phase
+ of dns.
+
dns.unreachabledns.name_not_resolveddns.faileddns.address_changed
+ All of the network errors in this section occur during secure
+ connection establishment, and therefore have a phase of connection.
+
tcp.timed_outtls.version_or_cipher_mismatchtls.failed
+ All of the network errors in this section occur during the
+ transmission of request and response, and therefore have a phase of application.
+
http.protocol.errorabandonedunknown
- This NEL header defines a similar NEL policy to the
- previous example, instructing the user agent to report network errors
- about example.com to the endpoint group named
- network-errors. Because of the include_subdomains
- field, this policy also applies to all subdomains of
- example.com.
-> GET / HTTP/1.1
-> Host: example.com
-
< HTTP/1.1 200 OK
< ...
< NEL: {"max_age": 0}
@@ -1074,6 +1235,215 @@ Sample Network Error Reports
+
+
+ DNS misconfiguration
+
+
+> GET / HTTP/1.1
+> Host: example.com
+
+< HTTP/1.1 200 OK
+< ...
+< Report-To: {"group": "network-errors", "max_age": 2592000,
+ "endpoints": [{"url": "https://example.com/upload-reports"}]}
+< NEL: {"report_to": "network-errors", "max_age": 2592000, "include_subdomains": true}
+
+
+
+ This NEL header allows the owner of
+ example.com to detect when they have misconfigured their
+ DNS servers — for instance, when they have forgotten to add a new
+ resource record resolving new-subdomain.example.com to an
+ IP address. If a user agent tries to make a request to
+ new-subdomain.example.com, it might generate the following
+ report:
+
+
+
+{
+ "age": 0,
+ "type": "network-error",
+ "url": "https://new-subdomain.example.com/",
+ "body": {
+ "uri": "https://new-subdomain.example.com/",
+ "sampling_fraction": 1.0,
+ "server_ip": "",
+ "protocol": "http/1.1",
+ "method": "GET",
+ "status_code": 0,
+ "elapsed_time": 48,
+ "type": "dns.name_not_resolved"
+ }
+}
+
+
+
+
+
+ Origins with multiple IP addresses
+
+
+ For origins whose domain name resolves to multiple IP
+ addresses, NEL will sometimes "downgrade" an error report, providing
+ less information about the cause of the error, since it cannot verify
+ that the owner of the origin is the same as the owner of the
+ server handling the request.
+
+
+
+ As an example, assume that example.com is handled by three
+ servers, each with a different IP address. The owner of the
+ service configures DNS to resolve example.com to
+ 192.168.0.1, 192.168.0.2, and
+ 192.168.0.3, and relies on user agents to balance their
+ requests across these three IP addresses. The service owner delivers
+ the following NEL policy:
+
+
+
+> GET / HTTP/1.1
+> Host: example.com
+
+< HTTP/1.1 200 OK
+< ...
+< Report-To: {"group": "network-errors", "max_age": 2592000,
+ "endpoints": [{"url": "https://example.com/upload-reports"}]}
+< NEL: {"report_to": "network-errors", "max_age": 2592000,
+ "success_fraction": 1.0, "failure_fraction": 1.0}
+
+
+
+ Given the above, consider the following sequence of events:
+
+
+
+ -
+
+ The user agent sends a request to 192.168.0.1,
+ and receives a successful response from the server.
+ This response includes the above NEL policy, and the user
+ agent sets the policy's received IP address to
+ 192.168.0.1. Since the received IP address
+ matches the server's IP address (which it must for any
+ successful request), it generates the following NEL report:
+
+
+
+{
+ "age": 0,
+ "type": "network-error",
+ "url": "https://example.com/",
+ "body": {
+ "uri": "https://example.com/",
+ "sampling_fraction": 1.0,
+ "server_ip": "192.168.0.1",
+ "protocol": "http/1.1",
+ "method": "GET",
+ "status_code": 200,
+ "elapsed_time": 57,
+ "type": "ok"
+ }
+}
+
+
+
+ -
+
+ The user agent sends a new request to
+ 192.168.0.2, and receives another successful
+ response. This response also includes the NEL policy,
+ and the user agent updates the policy's received IP address
+ to 192.168.0.2. Since the received IP address
+ matches the server's IP address (which it must for any
+ successful request), it generates the following NEL report:
+
+
+
+{
+ "age": 0,
+ "type": "network-error",
+ "url": "https://example.com/",
+ "body": {
+ "uri": "https://example.com/",
+ "sampling_fraction": 1.0,
+ "server_ip": "192.168.0.2",
+ "protocol": "http/1.1",
+ "method": "GET",
+ "status_code": 200,
+ "elapsed_time": 34,
+ "type": "ok"
+ }
+}
+
+
+
+ -
+
+ The user agent then tries to send a request to
+ 192.168.0.3, but isn't able to establish a connection
+ to the server. The user agent still has the NEL policy in
+ the policy cache, and would ideally use this policy to
+ generate a tcp.timed_out report about the failed
+ network request. However, the because policy's received
+ IP address (192.168.0.2) doesn't match the IP
+ address that this request was sent to, the user agent cannot
+ verify that the server at 192.168.0.3 is actually owned
+ by the owners of example.com. The user agent must
+ therefore downgrade the report to dns.address_changed:
+
+
+
+{
+ "age": 0,
+ "type": "network-error",
+ "url": "https://example.com/",
+ "body": {
+ "uri": "https://example.com/",
+ "sampling_fraction": 1.0,
+ "server_ip": "192.168.0.3",
+ "protocol": "http/1.1",
+ "method": "GET",
+ "status_code": 0,
+ "elapsed_time": 0,
+ "type": "dns.address_changed"
+ }
+}
+
+
+
+ -
+
+ The user agent then tries to send another request to
+ 192.168.0.1, but once again isn't able to establish a
+ connection to the server. Even though the user agent received the
+ NEL policy from 192.168.0.1 at some point in the
+ past, the policy's received IP address only records where it
+ was most recently received from — in this case,
+ 192.168.0.2. The user agent must therefore downgrade
+ the report to dns.address_changed:
+
+
+
+{
+ "age": 0,
+ "type": "network-error",
+ "url": "https://example.com/",
+ "body": {
+ "uri": "https://example.com/",
+ "sampling_fraction": 1.0,
+ "server_ip": "192.168.0.1",
+ "protocol": "http/1.1",
+ "method": "GET",
+ "status_code": 0,
+ "elapsed_time": 0,
+ "type": "dns.address_changed"
+ }
+}
+
+
+
+
@@ -1107,9 +1477,80 @@ Reporting of Third-party Subresource Fetch Failures
Privacy Considerations
- NEL provides network error reports that could expose new information about the user's network configuration. For example, an attacker could abuse NEL reporting to probe users network configuration. Also, similar to HSTS, HPKP, and pinned CSP policies, the stored NEL policy could be used as a "supercookie" by setting a distinct policy with a custom (per-user) reporting URI to act as an identifier in combination with (or instead of) HTTP cookies.
+
+ NEL provides network error reports that could expose new information about
+ the user's network configuration. For example, an attacker could abuse NEL
+ reporting to probe the user's network configuration, or to scan for
+ servers on the user's internal network. Also, similar to HSTS, HPKP, and
+ pinned CSP policies, the stored NEL policy could be used as a
+ "supercookie" by setting a distinct policy with a custom (per-user)
+ reporting URI to act as an identifier in combination with (or instead of)
+ HTTP cookies.
+
- To mitigate some of the above risks, NEL registration is restricted to trustworthy origins, and delivery of network error reports is similarly restricted to trustworthy origins. This disallows a transient HTTP MITM from trivially abusing NEL as a persistent tracker.
+
+ To mitigate some of the above risks, NEL registration is restricted to
+ potentially trustworthy origins, and delivery of network error
+ reports is similarly restricted to potentially trustworthy origins.
+ This disallows a transient HTTP MITM from trivially abusing NEL as a
+ persistent tracker.
+
+
+
+ NEL is intended to augment existing server-side monitoring. NEL reports
+ should only be sent to the owner of the service being requested. For
+ errors that occur during DNS resolution, NEL reports are only
+ generated when the NEL policy was received from the owner of the
+ domain namespace tree that contains the policy origin. For
+ errors that occur during secure connection establishment or
+ transmission of request and response, NEL reports are only
+ generated when the NEL policy was received from the owner of the
+ server that the request was sent to.
+
+
+
+ This rationale explains the treatment of the received IP address
+ and subdomains flag of a NEL policy. By checking that the
+ policy's received IP address matches the IP address of the
+ server, NEL extends the trust boundary of the policy to include not
+ just the policy's origin, but also the
+ specific server that the user agent is communicating with. This helps
+ prevent (for instance) DNS rebinding attacks, where an attacker delivers a
+ long-lived NEL policy from a server that they own, and then changes
+ their name servers to resolve the policy origin to a server they
+ don't control. Without the received IP address verification, this
+ would cause user agents to send reports about the second server to the
+ attacker.
+
+
+
+ Similarly, subdomain NEL policies are
+ limited, and can only be used to generate reports about subdomains of the
+ policy origin during the DNS resolution phase of a
+ request. During this phase, there is no server to verify
+ ownership of, and the fact that the policy was received from a superdomain
+ of the request's origin is enough to establish ownership of
+ the error. This allows the owners of a particular portion of the
+ domain namespace tree to use NEL to detect errors, while preventing them from
+ using malicious DNS entries to collect information about servers they
+ don't control.
+
+
+
+ To prevent information leakage, NEL reports about a request do not
+ contain any information that is not visible to the server when
+ processing the request. For errors during DNS resolution, a
+ NEL report only contains information available from DNS itself. This
+ prevents servers from abusing NEL to collect more information about
+ their users than they already have access to.
+
+
+
+ As an example, NEL reports specifically do not contain any information
+ about which DNS resolver was used to resolve a request's
+ domain name into an IP address.
+
In addition to above restrictions, the user agents MUST: