diff --git a/EXPLAINER.md b/EXPLAINER.md index 975b4f9..82568cb 100644 --- a/EXPLAINER.md +++ b/EXPLAINER.md @@ -1,8 +1,8 @@ # Local Peer-to-Peer API Explained -The Local Peer-to-Peer API enables browsers to connect securely over the Local Area Network, without the aid of a server in the middle. +The Local Peer-to-Peer API enables browsers to connect securely over a [local communication medium](https://wicg.github.io/local-peer-to-peer/#local-communication-medium), without the aid of a server in the middle. -The API provides a powerful new building block for developers while ensuring a seamless, secure and privacy preserving experience for the user. By putting the user-agent in control during discovery and authentication, bare minimal network topology information is exposed to an origin. +The API provides a powerful new building block for developers while ensuring a seamless, secure and privacy preserving experience for the user. By putting the user-agent in control during discovery and authentication, bare minimal [communication medium topology](https://wicg.github.io/local-peer-to-peer/#communication-medium-topology) information is exposed to an origin. Please refer to the [specification](https://WICG.github.io/local-peer-to-peer/) for the the formal draft spec. @@ -16,13 +16,13 @@ This proposal sets to make a part of this Tim's vision a reality while adhering ### Goals -Build a generic Local Peer-to-Peer API and provide an arbitrary bidirectional channel on the web for devices under short-range communication environment, including: +Build a generic Local Peer-to-Peer API and provide an arbitrary bidirectional communication channel to the web for devices in the context of a [local communication medium](https://wicg.github.io/local-peer-to-peer/#local-communication-medium), including: -- Methods to discover, request, and connect to peers on the local network +- Methods to discover, request, and connect to peers on the local communication medium - Listeners to notify if these method calls succeed or fail - Listeners to notify if the connection is received or its status is updated - Means to send and receive data after connection to a peer device has been established -- Means to enable secure HTTPS connections on the local network +- Means to enable secure HTTPS connections on the local communication medium As a commitment to an open standards-based implementation path, this specification describes how the API can be implemented on top of the [Open Screen Protocol](https://w3c.github.io/openscreenprotocol/). While not described here, the API is expected to be implementable on top of other transports when technically feasible. @@ -40,7 +40,7 @@ As a commitment to an open standards-based implementation path, this specificati ![G](./images/n2.svg) -Figure 1: Collaborate from nearby devices in Google Doc +Figure 1: Collaborate using local communication in Google Doc ### UC2: Disaster relief @@ -81,20 +81,19 @@ Figure 3: Play web game cross smart TV and mobile phone The following are the high-level requirements derived from the use cases: -- R1: Discover nearby device(s) -- R2: Advertise yourself to nearby device(s) -- R3: Establish a bi-directional communication channel between two nearby devices -- R4: Allow secure connection to locally hosted web pages. +- R1: Discover device(s) on the local communication medium +- R2: Advertise yourself to device(s) on the local communication medium +- R3: Establish a bi-directional communication channel between two devices on the local communication medium +- R4: Allow secure connection to web pages hosted on the local communication medium. - R5: User consent and delegation per web origin. ### Prerequisites -What is a prerequisite for all these use cases is that the participating devices are physically nearby to each other and as such able to establish a direct connection using either a wireless connectivity technology such as Wi-Fi Direct, Wi-Fi via access point, or a wired computer networking technology such as Ethernet. This connection technology and its details are abstracted out by both the Web API exposed to web developers as well as the UI/UX visible to the user. +What is a prerequisite for all these use cases is that the participating devices can be connected via a [local communication medium](https://wicg.github.io/local-peer-to-peer/#local-communication-medium) because they are physically nearby to each other and as such able to establish a direct connection using either a wireless connectivity technology such as Wi-Fi Direct, Wi-Fi via access point, or a wired computer networking technology such as Ethernet. This connection technology and its details are abstracted out by both the Web API exposed to web developers as well as the UI/UX visible to the user. In summary, the following are the prerequisites: -- The participating devices are physically nearby (the definition of "nearby" is an implementation detail) -- The participating devices are able to establish a direct connection using some connection technology (the supported technologies may vary depending on hardware and OS capabilities and remain an implementation detail) +- The participating devices share a local communication medium. ### References @@ -107,14 +106,14 @@ In summary, the following are the prerequisites: ## Solution Approach -The Local Peer-to-Peer API uses the to mutual authentication provided by the Open Screen Protocol to establish mutual TLS certificates between peers. These certificates serve as a trust anchor for secure communication. The Local Peer-to-Peer specification defines two uses of this new trust anchor: +The Local Peer-to-Peer API uses the to mutual authentication provided by the Open Screen Protocol to establish mutual TLS certificates between peers. These certificates serve as a trust anchor for secure [local communication](https://wicg.github.io/local-peer-to-peer/#local-communication). The Local Peer-to-Peer specification defines two uses of this new trust anchor: -1. Enabling HTTPS on the local network. -2. Enabling data communication on the local network using the `DataChannel` and `WebTransport` APIs. +1. Enabling HTTPS on the local communication medium. +2. Enabling secure local communication using the `DataChannel` and `WebTransport` APIs. ### API Design -Peer-to-Peer communication starts with service discovery. For this purpose, the LP2PReceiver API allows an origin to advertise itself. The LP2PRequest API allows discovery of a peer on the network. The design if these APIs is inspired by the work of the Presentation API's PresentationRequest & PresentationReceiver. Data exchange itself is provided by two APIs: `LP2PDataChannel` & `LP2PQuicTransport`. The [LP2PDataChannel API](https://wicg.github.io/local-peer-to-peer/#lp2p-data-channel) is inspired by the RTCDataChannel API. This API caters to simple message passing use-cases and developer familiar with WebRTC. The API design augments that of the WebRTC RTCDataChannel API. The [LP2PQuicTransport API](<](https://wicg.github.io/local-peer-to-peer/#lp2p-quic-transport)>) design is inspired by the WebTransport API. This API is designed for use-cases where more direct control over the underlying transport is preferred. +Peer-to-Peer communication starts with service discovery. For this purpose, the LP2PReceiver API allows an origin to advertise itself. The LP2PRequest API allows discovery of a peer on the local communication medium. The design if these APIs is inspired by the work of the Presentation API's PresentationRequest & PresentationReceiver. Data exchange itself is provided by two APIs: `LP2PDataChannel` & `LP2PQuicTransport`. The [LP2PDataChannel API](https://wicg.github.io/local-peer-to-peer/#lp2p-data-channel) is inspired by the RTCDataChannel API. This API caters to simple message passing use-cases and developer familiar with WebRTC. The API design augments that of the WebRTC RTCDataChannel API. The [LP2PQuicTransport API](<](https://wicg.github.io/local-peer-to-peer/#lp2p-quic-transport)>) design is inspired by the WebTransport API. This API is designed for use-cases where more direct control over the underlying transport is preferred. ## Shorthand APIs @@ -140,7 +139,7 @@ _Note_: the shorthand APIs are a work in progress. They are illustrative and wil ## Local HTTPS -The Local Peer-to-Peer API's authentication process establishes mutual TLS certificates between peers on the local network. These certificates can serve as a trust anchor to validate certificates used by HTTPS servers on the local network. +The Local Peer-to-Peer API's authentication process establishes mutual TLS certificates between peers on a [local communication medium](https://wicg.github.io/local-peer-to-peer/#local-communication-medium). These certificates can serve as a trust anchor to validate certificates used by HTTPS servers on the local communication medium. Please refer to [Local HTTPS](https://wicg.github.io/local-peer-to-peer/#local-https) in the specification for more details. @@ -148,7 +147,7 @@ _Note_: Local HTTPS is a work in progress, see [#34](https://github.com/WICG/loc ## Peer discovery -Before any connection can be established, two peers on the local network must find each other. This is done using the `LP2PReceiver` and `LP2PRequest` interfaces: +Before any connection can be established, two peers on the local communication medium must find each other. This is done using the `LP2PReceiver` and `LP2PRequest` interfaces: ```js // Peer A @@ -240,7 +239,7 @@ The Local Peer-to-Peer API has been designed specifically with security and priv ## Considered Alternatives -When a user wants to connect between two devices on the same network, for example to another device nearby—be it another device the user owns or that of a friend—the user has multiple ways to accomplish this task: +When a user wants to connect between two devices on the same local communication medium, for example to another device nearby—be it another device the user owns or that of a friend—the user has multiple ways to accomplish this task: 1. _A cloud service_. The web has many ways of connections to a third-party cloud service: HTTP, WebSocket or WebTransport. However, all of these methods require a round trip through the internet. This is inherently dependant on external resources, it consumes network bandwidth and can be slow or costly and has privacy implications in all but the strongest E2E encryption schemes. @@ -248,9 +247,9 @@ When a user wants to connect between two devices on the same network, for exampl 3. _A WebRTC connection_. While WebRTC is a P2P protocol, it still requires a setup step usually referred to as 'signaling'. There is no good way to perform this step without relying on an existing connection between peers, commonly a cloud service is used. -None of these solutions to this seemingly common task provide a compelling user experience. When the devices are physically nearby the user's expectation is the connection process should be as seamless as any physical interaction. With close-range communication technologies widely supported on today's devices we believe this user experience can be vastly improved. +None of these solutions to this seemingly common task provide a compelling user experience. When the devices share a local communication medium the user's expectation is the connection process should be as seamless as any physical interaction. With a variety of [local communication](https://wicg.github.io/local-peer-to-peer/#local-communication) technologies widely supported on today's devices we believe this user experience can be vastly improved. -We need an optimized network path to use a local network connected by the devices for web applications. +This illustrates the gap for an optimized path for [local communication](https://wicg.github.io/local-peer-to-peer/#local-communication) by web applications. ![problem](./images/problem.svg) @@ -266,7 +265,7 @@ Certain use cases can benefit from an internet-based P2P fallback if local commu A number of efforts exist in this area including the [TCP and UDP Socket API](https://www.w3.org/TR/tcp-udp-sockets/), [Discovery API](https://www.w3.org/TR/discovery-api/) and [FlyWeb](https://flyweb.github.io/). -The Local Peer-to-Peer approach differs from previous work by putting the user-agent in control during device discovery and mutual authentication. This approach allows exposing bare minimal information about the device to an origin. The list of discovered devices is never shared with the origin and individual peer descriptors such as nickname are only shared with the origin after authentication and user consent. No network information such as IP addresses is ever shared with an origin. +The Local Peer-to-Peer approach differs from previous work by putting the user-agent in control during device discovery and mutual authentication. This approach allows exposing bare minimal information about the device to an origin. The list of discovered devices is never shared with the origin and individual peer descriptors such as nickname are only shared with the origin after authentication and user consent. No [communication medium topology](https://wicg.github.io/local-peer-to-peer/#communication-medium-topology) information such as IP addresses is ever shared with an origin. The following works are seen as precedent and guide the design of the Local Peer-to-Peer API: [Open Screen Protocol](https://www.w3.org/TR/openscreenprotocol/), [Presentation API](https://www.w3.org/TR/presentation-api/), [Remote Playback API](https://www.w3.org/TR/remote-playback/) [WebRTC](https://www.w3.org/TR/webrtc/), [ORTC (draft)](https://draft.ortc.org/), [WebTransport](https://www.w3.org/TR/webtransport/), [P2P WebTransport (draft)](https://w3c.github.io/p2p-webtransport/). diff --git a/index.bs b/index.bs index 736835c..3409250 100644 --- a/index.bs +++ b/index.bs @@ -22,7 +22,7 @@ Introduction {#intro} *This section is non-normative.* -The Local Peer-to-Peer API aims to give browsers the means to communicate directly, without the aid of a server in the middle. It is designed to enable this communication within the confines of a local communication medium such as the Local Area Network. +The Local Peer-to-Peer API aims to give browsers the means to communicate directly, without the aid of a server in the middle. It is designed to enable this communication within the confines of a [=local communication medium=]. Many modern Web security measures rely on the presence of naming, signaling and certificate authorities. Local use-cases where these authorities are not readily available have started lagging behind in user experience or are not supported altogether. The Local Peer-to-Peer API aims to bring back first-class support for local communication use-cases while working within the same strict user-friendliness, security and privacy requirements. @@ -30,7 +30,16 @@ Examples of potential uses of this API include: Collaboration tools that work du This specification aims to strike a balance between creating a powerful new building block for developers and providing a seamless, secure and privacy preserving experience for browser users. As an example: while the API doesn't provide raw socket access, it does aim to give developers the flexibility to innovate on top by providing a persistent, two-way communication channel with little overhead. -The API is designed to be backed by an authenticated, streams-based transport. As a commitment to an open standards-based implementation path, this specification describes how the API can be implemented on top of the [Open Screen Protocol](https://w3c.github.io/openscreenprotocol/). While not described here, the API is expected to be implementable on top of other transports when technically feasible. +The API is designed to be backed by an authenticated, streams-based transport. As a commitment to an open standards-based implementation path, this specification describes how the API can be implemented on top of the [[!openscreenprotocol|Open Screen Protocol]]. While not described here, the API is expected to be implementable on top of other transports when technically feasible. + +Terminology {#terminology} +====================================================== + +The term local communication medium refers to a communication medium that provides a local, direct communication channel between the communicating devices. This is a purposefully broad term that covers any medium that can be used to establish a an authenticated, streams-based transport between the devices. Examples may include but are not limited to: a wired or wireless local area network, a Thread network, Bluetooth Low Energy or Wi-Fi Direct. This spec will not mandate which underlying technologies must be supported. + +The term local communication refers to data communication over the [=local communication medium=]. + +The term communication medium topology refers to the composition of the [=local communication medium=] which may include sensitive information such as IP or other address information or the number of devices connected to the medium. Permission Policy Integration {#permission-policy-integration} ====================================================== @@ -70,9 +79,9 @@ Note: This section and its subsections use RFC 2119 terminology in a relaxed man The user agent is in charge of managing peers. -A peer is an equal participants in the network that forms a peer-to-peer network of nodes. These nodes can communicate without the need for a central coordination by a server. +A peer is an equal participant in the [=local communication=]. These nodes can communicate without the need for a central coordination by a server. -A user agent has an associated local peer-to-peer manager in charge of managing [=peers=]. Its responsibility is to [=start local peer discovery=], [=establish local peer connections=] and [=acquire a local peer grant=] on a per-origin basis. This is done to avoid exposing information about a user's local network topology. +A user agent has an associated local peer-to-peer manager in charge of managing [=peers=]. Its responsibility is to [=start local peer discovery=], [=establish local peer connections=] and [=acquire a local peer grant=] on a per-origin basis. This is done to avoid exposing information about the [=communication medium topology=]. Known peers {#known-peers} -------------------------- @@ -227,18 +236,18 @@ Note: The WebTransport-over-QUIC protocol is yet to be defined. Potentially cons Local HTTPS {#local-https} ========================== -Authentication establishes a mutual trust anchor between peers on the local network. This trust anchor can also be used to validate certificates used by HTTP servers on the local network. An Open Screen Protocol agent certificate can be identified by the common name of its subject ending in "._openscreen._udp". When a user agent loads a webpage and finds an agent certificate in the certificate chain, it can use it as a trust anchor for authentication of the server. If the corresponding agent is not [=authenticated=], the user agent should prompt the user to authenticate the agent before proceeding with certificate validation. +Authentication establishes a mutual trust anchor between peers on the [=local communication medium=]. This trust anchor can also be used to validate certificates used by HTTP servers on the [=local communication medium=]. An Open Screen Protocol agent certificate can be identified by the common name of its subject ending in "._openscreen._udp". When a user agent loads a webpage and finds an agent certificate in the certificate chain, it can use it as a trust anchor for authentication of the server. If the corresponding agent is not [=authenticated=], the user agent should prompt the user to authenticate the agent before proceeding with certificate validation. Endpoint discovery {#local-https-discovery} ------------------------------------------- -If a peer is [=authenticated=], it may advertize one or more HTTPS endpoints it provides. A user agent may display these to the user to connect to servers on the local network without knowledge of the corresponding hostname and/or IP address. +If a peer is [=authenticated=], it may advertize one or more HTTPS endpoints it provides. A user agent may display these to the user to connect to servers on the [=local communication medium=] without knowledge of the corresponding hostname and/or IP address. Issue: define endpoint-info messages LP2PReceiver Interface {#lp2p-receiver} ================================================ -The LP2PReceiver interface allows advertising on the local network, enabling other peers to discover and connect. +The LP2PReceiver interface allows advertising on the [=local communication medium=], enabling other peers to discover and connect. 
 [Exposed=(Window,Worker), SecureContext]
@@ -789,7 +798,7 @@ Issue(WICG/local-peer-to-peer#15): Define filtering to provide additional contex
 Impact on same-origin policy {#security-same-origin}
 ----------------------------------------
 
-This document extends the Web platform with the ability to set up real-time, direct communication between browsers and other devices, including other browsers, within the local area network.
+This document extends the Web platform with the ability to set up real-time, direct communication between browsers and other devices, including other browsers, within a [=local communication medium=].
 
 This means that data and media can be shared between applications running in different browsers, or between an application running in the browser and another user agent that is not a browser such as a headless service provided by a smart TV or smart fridge. This extends the usual barriers in the Web's security model that prevents sending data between entities with different origins.