Abstract

This document defines a mechanism that enables developers to declare a network error reporting policy for a web application. A user agent can use this policy to report encountered network errors that prevented it from successfully fetching requested resources.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of currentW3Cpublications and the latest revision of this technical report can be found in the at http://www.w3.org/TR/.        

This document was published by the as an Editor's Draft.     If you wish to make comments regarding this document, please send them to                (,   ). All comments are welcome.

Publication as an Editor's Draft does not imply endorsement by theW3CMembership. This is a draft document and may be updated, replaced or obsoleted by other              documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the .W3Cmaintains a    made in connection with the deliverables of the group; that page also includes   instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains   must disclose the information in accordance with .

This document is governed by the .

Table of Contents

1. Introduction

Accurately measuring performance characteristics of web applications is an important aspect in helping site developers understand how to improve their web applications. The worst case scenario is the failure to load the application, or a particular resource, due to a network error, and to address such failures the developer requires assistance from the user agent to identify when, where, and why such failures are occurring.

Today, application developers do not have real-time web application availability data from their end users. For example, if the user fails to load the page due to a network error, such as a failed DNS lookup, a connection timeout, a reset connection, or other reasons, the site developer is unable to detect and address this issue. Existing methods, such as synthetic monitoring provide a partial solution by placing monitoring nodes in predetermined geographic locations, but require additional infrastructure investments, and cannot provide truly global and near real-time availability data for real end users.

Network Error Logging (NEL) addresses this need by defining a mechanism enabling web applications to declare a reporting policy that can be used by the user agent to report network errors for a given origin. To take advantage of , a web application opts into using by supplying a NEL HTTP response header field that describes the reporting policy. Then, if the policy is available for a given origin, and an end user fails to successfully fetch a resource from that origin, the user agent logs the network error report and attempts to deliver it to the report URL defined by the policy - the delivery is done on a best effort basis and might be delayed due to connectivity issues or other reasons.

For example, if the user agent fails to fetch a resource from https://www.example.com due to an aborted TCP connection, the user agent would notify the report URL defined by the NEL policy associated with that origin, by delivering the following report:

{"nel-report": [     {
          "uri": "https://www.example.com/resource",       "referrer": "https://referrer.com/",       "server-ip": "123.122.121.120",       "elapsed-time": 321,       "age": 0,       "type": "tcp.aborted"     }   ]}

See for explanation of the communicated fields and format of the report, and for more hands-on examples of NEL registration and reporting process.

2. Network Error Logging

2.1 Key Concepts and Terminology

• origin

• Defined by the Origin specification. []

• JSON object

• JSON stringification

• Defined in the JSON specification. []

• URL

• Defined by [].

2.2 Policy Delivery and Processing

The server delivers the to the user agent via an HTTP response header field (). If the result of executing algorithm ([]) on that served the is Potentially Trustworthy then the user agent MUST either:

• Register the host as a if it is not already registered.

• Update the registered policy for the if the provided policy is different than that already stored by the user agent.

Otherwise, if the result of the algorithm is not Potentionally Trustworthy, then the user MUST ignore the provided .

2.2.1 NEL Header Field

TheNEL header fieldis used to communicate theNEL policyto the user agent. The ABNF (Augmented Backus-Naur Form) syntax for the is as follows:

NEL = "NEL" ":" [ directive ]  *( ";" [ directive ] ) directive                 = directive-name [ "=" directive-value ] directive-name            = token directive-value           = token | quoted-string

See [] section 3.2.6 for definitions of token and quoted-string. This specification defines three NEL directives: , , and . The overall requirements for directives are:

• Directive may be optional or required.

• Directive names are case-insensitive.

• Directive order is not significant.

• Directive should be specified once.

User agents MUST ignore any unknown or invalid directive(s), or other header field value data, that does not conform to the syntax defined in this specification. A valid MUST, at a minimum, contain all of the "REQUIRED" directives defined in this specification.

• If a directive is specified multiple times within the same , the user agent MUST process the first declaration and ignore the rest.

• If multiple valid 's are present, the user agent MUST process the first valid header field and ignore the rest.

The user agent MUST ignore the NEL header specified via a meta element to mitigate hijacking of error reporting via scripting attacks. The MUST be delivered via the .

Note

The restriction on meta element is consistent with [] specification, which restricts reporting registration to HTTP header fields only for same reasons.

2.2.1.1 The report-uri Directive

Thereport-uridirective specifies a URL to which the user agent sends reports about network errors. The directive is a REQUIRED field to register an , and OPTIONAL if the intent is to remove a previous registration - see . The ABNF grammar for the name and value of the directive is:

directive-name    = "report-uri" directive-value   = 1*absolute-URI

The set of report URLsis the value of the directive, which contains one or more absolute-URI's - see [] section 4.3. Each absolute-URI value SHOULD be delimited within double-quotes.

The result of executing the algorithm on origin of each in the provided MUST return Potentially Trustworthy. that fail this criteria MUST be ignored by the user agent. The process of sending network error reports to the specified URL's in this directive's value is defined in this documents section.

Note

To improve delivery of NEL reports the application should set report-uri to an alternative origin whose infrastructure is not coupled with the origin from which the resource is being fetched — otherwise network errors cannot be reported until the problem is solved, if ever — and provide multiple report-uri's to provide fallback alternatives if the preceding report-uri is unreachable.

2.2.1.2 The max-age Directive

The REQUIRED max-agedirective specifies the number of seconds, after the reception of the NEL header field, during which the user agent regards the host (from whom the policy was received) as a . The ABNF grammar for the name and value of the directive is:

directive-name    = "max-age" directive-value   = delta-seconds

See [] section 1.2.1 for definition of delta-seconds. A value of zero (i.e. "max-age=0") signals the user agent to cease regarding the host as a , including the directive if provided.

2.2.1.3 The includeSubDomains Directive

The OPTIONAL includeSubDomainsdirective is a valueless directive that, if present, signals the user agent that the applies not only to the that served the , but also to any whose component is a subdomain of the component of the ’s .

2.3 Policy Storage and Maintenance

An HTTP host declares itself anNEL originby issuing an , which is communicated via the from a . Upon error-free receipt and processing of this header by a conformant user agent, the user agent regards the host as aknown NEL origin.

The user agent MUST maintain the of any given separately from any NEL policies issued by any other . Only the given can update or cause deletion of its . This is accomplished by sending a to the user agent with new values for the policy , , and . Thus, the user agent MUST store the "freshest" information on behalf of an , and specifying a zero time duration MUST cause the user agent to delete the (including any asserted directive) for that .

2.4 Reporting

Anetwork erroris any condition where a connection or a  protocol error is encountered by the user agent, thus preventing it from successfully completing the request-response exchange. This may include, but is not limited to DNS, TCP, TLS, and HTTP connection and protocol errors. For example, a is triggered when the user agent:

• Fails to resolve the DNS name

• Fails to establish a TCP connection

• Fails to establish a secure TLS tunnel

• Fails to fetch the resource due to a TLS protocol error

• Fails to fetch the resource due to a HTTP protocol error

• Fails to fetch the resource due to a socket timeout or error

• Fails to fetch the resource due to a redirect loop

The user agent MAY classify and report server error responses (, []) as network errors. For example, a network error report may be triggered when a fetch fails due to proxy or gateway errors, service downtime, and other types of server errors.

The failure to fetch a resource when the user agent is known to be offline (when returns false) MUST NOT be considered to be a .

Note

Note that the above definition of "network error" is different from definition in []. The definition of in this specification is a subset of [] definition - i.e. all of the above conditions would trigger a "network error" in [] processing, but conditions such as blocked requests due to mixed content, CORS failures, etc., would not.

When a occurs for a URL that belongs to a the user agent SHOULD log the error and attempt to deliver it to the defined by the of the associated :

• The user agent SHOULD make best effort to deliver the error report as soon as possible to provide the necessary real-time feedback.

• The user agent MAY delay delivery of the report to account for poor or missing connectivity (e.g. temporarily offline due to poor service).

• The user agent MAY abandon delivery of the report if the time of error exceeds 24 hours, or if the is not responding or returns an error.

• The user agent MAY aggregate multiple error reports for the same and deliver them in a single report.

To generate anetwork error object, the user agent MUST use an algorithm equivalent to the following:

1. Prepare a JSON object neterror with the following keys and values:

• abandoned

• User aborted the resource fetch before it is complete

• unknown

• error type is unknown

• http.protocol.error

• The connection was aborted due to an HTTP protocol error

• http.response.invalid

• Response is empty, has a content-length mismatch, has improper encoding, and/or other conditions that prevent user agent from processing the response

• http.response.redirect_loop

• The request was aborted due to a detected redirect loop

• http.failed

• The connection failed due to errors in HTTP protocol not covered by previous errors

• tls.version_or_cipher_mismatch

• The TLS connection was aborted due to version or cipher mismatch

• tls.bad_client_auth_cert

• The TLS connection was aborted due to invalid client certificate

• tls.cert.name_invalid

• The TLS connection was aborted due to invalid name

• tls.cert.date_invalid

• The TLS connection was aborted due to invalid certificate date

• tls.cert.authority_invalid

• The TLS connection was aborted due to invalid issuing authority

• tls.cert.invalid

• The TLS connection was aborted due to invalid certificate

• tls.cert.revoked

• The TLS connection was aborted due to revoked server certificate

• tls.cert.pinned_key_not_in_cert_chain

• The TLS connection was aborted due to a key pinning error

• tls.protocol.error

• The TLS connection was aborted due to a TLS protocol error

• tls.failed

• The TLS connection failed due to reasons not covered by previous errors

• tcp.timed_out

• TCP connection to the server timed out

• tcp.closed

• The TCP connection was closed by the server

• tcp.reset

• The TCP connection was reset

• tcp.refused

• The TCP connection was refused by the server

• tcp.aborted

• The TCP connection was aborted

• tcp.address_invalid

• The IP address is invalid

• tcp.address_unreachable

• The IP address is unreachable

• tcp.failed

• The TCP connection failed due to reasons not covered by previous errors

• dns.unreachable

• DNS server is unreachable

• dns.name_not_resolved

• DNS server responded but is unable to resolve the address

• dns.failed

• Request to the DNS server failed due to reasons not covered by previous errors

• A host identified by an IPv4 address is represented in dotted-decimal notation (a sequence of four decimal numbers in the range 0 to 255, separated by "."). []

• A host identified by an IPv6 address is represented as an ordered list of eight 16-bit pieces (a sequence of x:x:x:x:x:x:x:x, where the 'x's are one to four hexadecimal digits of the eight 16-bit pieces of the address). []

• uri

• The URL that encountered the , with any component removed.

• referrer

• The referrer information of the request, as ([]) associated with its .

• server-ip

• The IP address of the host to which the user agent sent the request, if available. Otherwise, an empty string.

• protocol

• The  used to fetch the resource as identified by the ALPN Protocol ID, if available. Otherwise, an empty string.

• status-code

• The of the HTTP response, if available. Otherwise, the number 0.

• elapsed-time

• The elapsed number of milliseconds between the start of the resource fetch and when it was aborted by the user agent.

• age

• The elapsed number of milliseconds between the time when the user agent aborted the request and when the error report is being delivered.

• type

• The description of the error type, which may be one the following strings:

  The user agent MAY extend the above error type list with custom values - e.g. new error types to accommodate new protocols, or more detailed error descriptions of existing ones. When doing so, the user agent SHOULD follow the dot-delimited pattern ([group].[optional-subgroup].[error-name]) to facilitate simple and consistent processing of the error reports - e.g. the collector may provide aggregation by category and/or one or multiple subgroups.

Return neterror.

To send network error reports, the user agent MUST use an algorithm equivalent to the following:

1. Prepare a JSON objectreport objectwith the following keys and values:

• nel-report

• An array object containing one or more .

Letreport bodybe the JSON stringification of the report object.For each report URL in the set of report URLs:

1. to using HTTP method POST, with a Content-Type header field of application/nel-report, and an entity body consisting of . If the origin of is not the same as the origin of the for which the report is generated, the block cookies flag MUST also be set. The for these is theNetwork Error Logging task source.

2. If the fetch is successful (2xx HTTP response code), the user agent MUST abort the remaining steps.

3. If the fetch failed with a HTTP response code ([]), the user agent MUST update the by removing the current from the .

4. If the fetch failed after multiple delivery attempts the user agent MAY update the by removing the current from the .

   Note

   The user agent is allowed to garbage collect report-uri's that are no longer functional, but it should account for common failure cases such as captive portals, which may temporarily prevent it from delivering the error reports. The exact implementation logic is deferred to the user-agent, which may use own mechanisms and heuristics to detect such cases.

5. If the was updated and the new contains an empty the user agent MUST remove the and abort the remaining steps.

6. If the user agent has reached the end of the set of , the user agent MUST sleep before returning to the beginning of the set and reattempting delivery - e.g. use exponential backoff. Otherwise, the user agent MUST attempt immediate delivery of the error report to the next in the .

2.5 Examples

2.5.1 Sample Policy Definitions

Example 1

> GET / HTTP/1.1 > Host: example.com < HTTP/1.1 200 OK < ... < NEL: report-uri="https://example.com/report"; max-age=2592000

The above provided in the server response specifies that the user agent should register a new , or update an existing one if one already exists, for the example.com : the user agent should report network errors to https://example.com/report and the policy applies for 2592000 seconds (30 days).

Note that above registration will only succeed if the response is communicated from a Potentially Trustworthy origin - see .

Example 2

> GET / HTTP/1.1 > Host: example.com < HTTP/1.1 200 OK < ... < NEL: report-uri="https://other-origin.com/report"; max-age=2592000

The above provided in the server response is similar to the previous example but tells the user agent to report network errors to https://other-origin.com/report. The use of an alternative origin that is not coupled with the origin that is being accessed is strongly encouraged to enable real-time reporting and improved report delivery - see .

Example 3

> GET / HTTP/1.1 > Host: example.com < HTTP/1.1 200 OK < ... < NEL: report-uri="https://example.com/report" "https://other-origin.com/report"; max-age=2592000; includeSubDomains

The above provided in the server response specifies that the user agent should report network errors to https://example.com/report, or https://other-origin.com/report if the former is unreachable. Further, the policy is extended to all of the subdomains of the issuing - see .

Example 4

> GET / HTTP/1.1 > Host: example.com < HTTP/1.1 200 OK < ... < NEL: max-age=0

The above provided in the server response contains set to zero, which indicates that the user agent must delete the current registered associated with the example.com and all of its subdomains:

• is implicit when is zero

• is optional when removing a previously registered policy

2.5.2 Sample Network Error Reports

This section contains an example network error report the user agent might send when a network error is encountered for a .

{
      "nel-report": [       {
            "uri": "https://www.example.com/",         "referrer": "http://example.com/",         "server-ip": "123.122.121.120",         "protocol": "h2",         "status-code": 200,         "elapsed-time": 823,         "age": 0,         "type": "http.protocol.error"       }     ]   }

The above report indicates that the user agent attempted to navigate from "example.com" to "www.example.com" (), which successfully resolved to the "123.122.121.120" IP address. However, while the user agent received a "200" response from the server via the "h2" protocol, it encountered a protocol error in the exchange and was forced to abandon the navigation. 823 milliseconds elapsed between the start of navigation and when the user agent aborted the navigation. Finally, the user agent sent this report immediately after the network error was encountered - i.e. the report age is 0.

{
      "nel-report": [       {
            "uri": "https://widget.com/thing.js",         "referrer": "https://www.example.com/",         "server-ip": "234.233.232.231",         "protocol": "",         "status-code": 0,         "elapsed-time": 143,         "age": 0,         "type": "http.dns.name_not_resolved"       }     ]   }

The above report indicates that the user agent attempted to fetch  "https://widget.com/thing.js", which belongs to a previously registered , from "www.example.com" origin. However, the user agent was unable to resolve the DNS name and the request was aborted by the user agent after 143 milliseconds. Because "widget.com" is a known NEL origin, a network error report was logged and sent to the report URL specified by the NEL policy of that host immediately after the network error was encountered - i.e. the report age is 0.

2.6 Use cases

2.6.1 Reporting of Navigation Failures

A navigation request initiated by the user (e.g. via a click on a link, direct input via the location bar, script-initiated due to user interaction, etc.) may fail due any number of connectivity reasons: DNS failure, TCP error, TLS protocol violation, and so on. These errors may be caused by network misconfiguration, transient routing issues, server downtime, malware or other attacks against the user, etc.

In such cases the destination host is often left unaware of the failed navigation since, by definition, it cannot see the request reach its infrastructure and it is unable to investigate the problem. To address this, the host can register an with the user agent, which specifies where reports of such failures should be delivered such that they can be investigated.

2.6.2 Reporting of First-party Subresource Fetch Failures

A typical application requires dozens of resources, the fetching of which is typically initiated via HTML, CSS, or JavaScript. The application requesting such resources can observe failures of most such fetches (e.g. via onerror callbacks), but it does not have access to the detailed network error report of why the failure has occurred - e.g. DNS failure, TCP error, TLS protocol violation, etc.

To address this, the application can register relevant NEL policies with the user agent for the first-party hosts from which the subresources are being fetched. Then, if such a policy is present and a network error is encountered for a resource associated with a registered , the user agent will report the detailed network error report and enable the application developers to investigate the error.

2.6.3 Reporting of Third-party Subresource Fetch Failures

In the case where a resource is embedded by a third party, the provider of the resource is often unable to instrument and observe the failure. For example, if example.com embeds a widget.com/thing.js resource on its site, and the user visiting example.com fails to fetch such resource due to a network error, the widget.com host is both unaware of the failure and unable to detect it.

To address this, widget.com can register an NEL policy for its host. Then, if such policy is present and a network error is encountered while fetching a resource — regardless of whether it is being requested from a first-party or third-party origin — from the registered , the user agent will report the network error and enable the provider to investigate the error.

2.7 Privacy Considerations

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 could be used as a "supercookie" by setting a distinct policy with a custom (per-user) reporting URI to act as an identififer in combination with (or instead of) HTTP cookies.

To mitigate some of the above risks, NEL registration is restricted to , and delivery of network error reports is similarly restricted to . This disallows a transient HTTP MITM from trivially abusing NEL as a persistent tracker.

In addition to above restrictions, the user agents MUST:

• Clear the stored NEL policies when the user clears their browsing data (cookies, site data, history, etc).

• Refuse to process Set-Cookie response headers when delivering network error reports.

When deploying NEL the developer SHOULD consider privacy implications of NEL reports delivered to the specified collectors. For example, reports may contain URLs with sensitive data (e.g. "Capability URLs") that may need special precautions (see []), and may require the developer to operate their own NEL collectors to prevent reporting of such URLs to third parties.

2.8 IANA Considerations

The permanent message header field registry  should be updated with the following registrations ([]):

2.8.1 NEL

• Header field name

• NEL

• Applicable protocol

• http

• Status

• standard

• Author/Change controller

• W3C

• Specification document

• This specification (see )