The Network Information API enables web applications to access information about the network connection in use by the device.
## Use cases and requirements
This document attempts to address the [requirements](https://github.com/w3c-webmob/netinfo/blob/master/README.md) from the [Review of Apps that Use Network Information](https://github.com/w3c-webmob/netinfo) document published by the Web and Mobile Interest Group. Those are:
* Provide access to the connection type the system is using to communicate with the network (e.g., cellular, bluetooth, ethernet, wifi, other, or none). This information needs to be available either immediately on page load or as close as possible to it.
* Provide a means for scripts to be notified if the connection type changes. This is to allow developers to make dynamic changes to the DOM and/or inform the user that the network connection type has changed (and that it could impact them in some way).
## Definitions
For clarity, a megabit is 1,000,000 bits, and megabits per second is equivalent to transferring:
* 1,000,000 bits per second
* 1,000 kilobits per second
* 125,000 bytes per second
* 125 kilobytes per second
* and so on...
## Connection types
### Effective connection types
This section defines the effective connection types (ECT):
Table of effective connection types
ECT |
Minimum RTT (ms) |
Maximum downlink (Kbps) |
Explanation |
slow-2g |
1900 |
50 |
The network is suited for small transfers only such as text-only pages. |
2g |
1300 |
70 |
The network is suited for transfers of small images. |
3g |
200 |
700 |
The network is suited for transfers of large assets such as high resolution images, audio, and SD video. |
4g |
0 |
∞ |
The network is suited for HD video, real-time video, etc. |
The above roundtrip and bandwidth values are based on real user measurement observations:
- `slow-2g` is the 66.6th percentile of 2G observations
- `2g` is the 50th percentile of 2G observations
- `3g` is the 50th percentile of 3G observations
The absolute values provided above are based on real user measurement on Chrome on Android, as captured in April 2017. The user agent MAY update these values in the future to reflect changes in the measurement data.
## Extensions to the `Navigator` interface
The `NavigatorNetworkInformation` interface exposes access to `NetworkInformation` interface.
[NoInterfaceObject, Exposed=(Window,Worker)]
interface NavigatorNetworkInformation {
readonly attribute NetworkInformation connection;
};
Navigator implements NavigatorNetworkInformation;
WorkerNavigator implements NavigatorNetworkInformation;
### The `connection` attribute
The `connection` attribute, when getting, returns an object that implements the `NetworkInformation` interface.
## The `NetworkInformation` interface
The `NetworkInformation` interface provides a means to access information about the network connection the user agent is currently using.
[Exposed=(Window,Worker)]
interface NetworkInformation : EventTarget{
readonly attribute ConnectionType type;
readonly attribute EffectiveConnectionType effectiveType;
readonly attribute Megabit downlinkMax;
readonly attribute Megabit downlink;
readonly attribute Millisecond rtt;
attribute EventHandler onchange;
};
typedef unrestricted double Megabit;
typedef unsigned long long Millisecond;
### `type` attribute
The `type` attribute, when getting, returns the connection type that the user agent is using.
### `effectiveType` attribute
The `effectiveType` attribute, when getting, returns the effective connection type that is determined using a combination of recently observed round trip times and downlink bandwidth.
### `downlinkMax` attribute
The `downlinkMax` attribute represents an upper bound on the downlink speed of the first network hop. The reported value is in megabits per second and determined by the properties of the underlying connection technology.
The user agent has no knowledge of the total number or the performance characteristics of the various network hops required to fulfill a particular request; different requests may follow different routes and have different performance characteristics. The reported
upper bound on the downlink speed of the first network hop value is determined by the properties of the
underlying connection technology of the first network hop. The end-to-end performance of any request cannot exceed this value, but it is also not a guarantee of performance and may be significantly worse.
### `onchange` attribute
The `onchange` event handler attribute handles "change" events fired during the steps to update the connection values.
### `downlink` attribute
The `downlink` attribute represents the effective bandwidth estimate in megabits per second based on recently observed throughput on the client, rounded to nearest 25 kilobits per second.
### `rtt` attribute
The `rtt` attribute represents the effective round-trip time estimate in milliseconds based on recently observed round-trip times on the client, rounded to nearest 25 milliseconds.
## Underlying connection technology
The relationship between an underlying connection technology and its upper bound on the downlink speed of the first network hop is determined by the available network interfaces that may be used to fulfill new network requests.
The downlinkMax for an available interface is determined via the standardized, or generally accepted, maximum download data rate captured in the table of maximum downlink speeds. Where possible, this value may be refined to report a more accurate upper bound based on current properties of the interface - e.g. signal strength, modulation algorithm, and other "network weather" variables.
The upper bound on the downlink speed of the first network hop is determined by the rules described in handling changes to the underlying connection.
The enumeration of available network interfaces and their generation and version is not directly exposed to script. Instead, `downlinkMax` exposes a single value in
megabits per second that accounts for all available interfaces and their current network conditions.
Table of maximum downlink speeds
Connection type |
Underlying connection technology |
Generation or Version |
Max downlink speed (Mbit/s) |
Data available as JSON. |
### Handling changes to the underlying connection
When the properties of the underlying connection technology change, due to a switch to a different connection type or effective connection type, change in upper bound on the downlink speed of the first network hop, or change in effective downlink or rtt estimates, the user agent MUST run the steps to update the connection values:
1. Let new-type be the connection type that represents the underlying connection technology.
1. Let new-effective-type be the effective connection type determined by current downlink and rtt values.
1. Let new-downlink be the downlink value.
1. Let new-rtt be the rtt value.
1. If new-type is "none", set max-value to `0`.
1. if new-type is "unknown", set max-value to `+Infinity`.
1. If new-type is "mixed", set max-value to an applicable value for the interface configuration used to service new network requests - e.g. if multiple interfaces may be used, sum their downlinkMax for an available interface values.
1. Otherwise, set max-value to downlinkMax for an available interface.
1. If max-value is not equal to the value of `connection.downlinkMax`, or if new-type is not equal to the value of `connection.type`, or if new-downlink is not equal to the value of `connection.downlink`, or if new-rtt is not equal to the value of `connection.rtt`:
1. Using the networking task source, queue a task to perform the following:
1. Set `connection.downlinkMax` to max-value.
1. Set `connection.type` to new-type.
1. set `connection.effectiveType` to new-effective-type.
1. Set `connection.downlink` to new-downlink.
1. Set `connection.rtt` to new-rtt.
1. Fire an event named `change` at the `NetworkInformation` object.
## The ConnectionType enum
enum ConnectionType {
"bluetooth",
"cellular",
"ethernet",
"mixed",
"none",
"other",
"unknown",
"wifi",
"wimax"
};
## The EffectiveConnectionType enum
enum EffectiveConnectionType {
"slow-2g",
"2g",
"3g",
"4g"
};
## Privacy Considerations
The Network Information API exposes information about the observed network bandwidth, latency and the first network hop between the user agent and the server; specifically, the type of connection and the upper bound of the downlink speed, as well as signals whenever this information changes. Such information may be used to:
- Fingerprint a user based on characteristics of a particular network (e.g. type and downlink estimates) at a point in time, and by observing change in such characteristics over a period of time.
- Fingerprint a user based on transitions between one or more networks (e.g. based on order of transitions by type, downlink estimates, and time).
- Infer user location (e.g. are they home, at work, or in transit) based on above criteria.
However, above considerations are not new, and sufficiently motivated attackers may already obtain such information using other technologies:
- The attacker can use JavaScript to observe the duration (e.g. time from start of fetch to `onload` event) of any network fetch on the client, and may get more detailed timing data about the same fetch via the Resource Timing API.
- The attacker can use WebRTC to identify client's public and private IP addresses via STUN, or similar mechanisms.
- The attacker can observe the client IP, fetch duration, RTT, transfer speed, and other low-level socket metrics of a fetch on the server.
Further, by repeating one of the above strategies (e.g. via invoking periodic fetch or refresh of a resource; via periodic SSE or WebSocket messages; via periodic STUN requests, etc.), the attacker can observe changes over time in the performance characteristics of client's connection and IP address. Such data can then be used to refine the user fingerprint, infer users location (e.g. are they home, at work, or in transit), and extract various behavioral patterns.
The above list is not a complete overview. However, as the above examples illustrate, the attacks are possible both from the sender and the receiver:
- If the attacker can initiate or observe a network fetch of any kind from the client, then they can observe its performance characteristics and how they change over time.
- If the attacker can convince the client to fetch a resource from their server, then they can similarly observe the performance characteristics of the fetch and how they change over time.
Mitigating such attacks initiated from the client requires preventing the attacker from observing and initiating network requests - e.g., use HTTPS to prevent trivial content injection by malicious parties; disable JavaScript to prevent scripted resource fetch of any kind. Mitigating attacks from the sender is possible via the use of a VPN or an HTTP proxy - e.g. to hide the client's true IP address, to introduce additional latency, and so on.
As such, while the Network Information API makes it easier to obtain information about the first network hop, by avoiding the need to observe or make network requests, it does not expose anything that is not already available to a sufficiently-motivated attacker.
If the client wants to mitigate this class of attacks, they should disable JavaScript, monitor that all outbound requests are made to trusted origins, and make diligent use of anonymizing VPN/proxy services.
## Acknowledgments
This document reuses text from the [[!HTML]] specification
as permitted by the license of that specification.