diff --git a/EXPLAINER.md b/EXPLAINER.md index c130534..ca3fdb8 100644 --- a/EXPLAINER.md +++ b/EXPLAINER.md @@ -28,7 +28,7 @@ Build a generic Local Peer-to-Peer API and provide an arbitrary bidirectional co - Means to send and receive data after connection to a peer device has been established - 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. +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 Network Protocol](https://www.w3.org/TR/openscreen-network/). While not described here, the API is expected to be implementable on top of other transports when technically feasible. ### Non-goals @@ -111,7 +111,7 @@ 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 [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: +The Local Peer-to-Peer API uses the to mutual authentication provided by the Open Screen Network 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 communication medium. 2. Enabling secure local communication using the `DataChannel` and `WebTransport` APIs. @@ -272,7 +272,7 @@ A number of efforts exist in this area including the [TCP and UDP Socket API](ht 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/). +The following works are seen as precedent and guide the design of the Local Peer-to-Peer API: [Open Screen Network Protocol](https://www.w3.org/TR/openscreen-network/), [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/). ## References & Acknowledgements diff --git a/index.bs b/index.bs index 3409250..140d028 100644 --- a/index.bs +++ b/index.bs @@ -15,6 +15,10 @@ Abstract: Local Peer-to-Peer is a Web platform API proposal for local communicat Markup Shorthands: markdown yes, dfn yes, idl yes, markup yes +
+spec:html; type:dfn; text:allowed to use
+
+ Note: This specification is under active development and therefore incomplete. If you're looking for an overview of the proposal, please refer to the [Explainer](https://github.com/WICG/local-peer-to-peer/blob/main/EXPLAINER.md). Introduction {#intro} @@ -30,7 +34,7 @@ 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 [[!openscreenprotocol|Open Screen Protocol]]. 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 [[!openscreen-network|Open Screen Network Protocol]]. While not described here, the API is expected to be implementable on top of other transports when technically feasible. Terminology {#terminology} ====================================================== @@ -94,7 +98,7 @@ Note: The [=peer grant state=] is origin-level while the [=authentication state= Issue(wicg/local-peer-to-peer#24): See also related -The user agent may persist known peers, their [=authentication states=] and/or [=peer grant states=]. If the user agent chooses to do so, it must do so in accordance with the [[!openscreenprotocol|Open Screen Protocol]] Persistent State rules. Such a peer or its state is said to be persisted. +The user agent may persist known peers, their [=authentication states=] and/or [=peer grant states=]. If the user agent chooses to do so, it must do so in accordance with the [[!openscreen-network|Open Screen Network Protocol]] [Persistent State rules](https://www.w3.org/TR/openscreen-network/#persistent-state). Such a peer or its state is said to be persisted. Peer advertisement {#peer-advertisement} ---------------------------------------- @@ -137,7 +141,7 @@ Protocol concepts {#protocol-concepts} When asked to establish local peer connection, the user agent ... -A Local Peer-to-Peer session represents an authenticated [[!RFC9000|QUIC]] connection as defined in [[!openscreenprotocol|Open Screen Protocol]] or OSP. +A Local Peer-to-Peer session represents an authenticated [[!RFC9000|QUIC]] connection as defined in [[!openscreen-network|Open Screen Network Protocol]] or OSP. A [=Local Peer-to-Peer session=] has the following capabilities: @@ -151,23 +155,23 @@ A [=Local Peer-to-Peer session=] has the following capabilities: advertise agent - [[!openscreenprotocol]] - [discovery](https://www.w3.org/TR/openscreenprotocol/#discovery) + [[!openscreen-network|Open Screen Network Protocol]] + [discovery](https://www.w3.org/TR/openscreen-network/#discovery) discover agents - [[!openscreenprotocol]] - [discovery](https://www.w3.org/TR/openscreenprotocol/#discovery) + [[!openscreen-network|Open Screen Network Protocol]] + [discovery](https://www.w3.org/TR/openscreen-network/#discovery) discover metadata - [[!openscreenprotocol]] - [transport](https://www.w3.org/TR/openscreenprotocol/#transport) + [[!openscreen-network|Open Screen Network Protocol]] + [transport](https://www.w3.org/TR/openscreen-network/#transport) authenticate an agent - [[!openscreenprotocol]] - [authentication](https://www.w3.org/TR/openscreenprotocol/#authentication) + [[!openscreen-network|Open Screen Network Protocol]] + [authentication](https://www.w3.org/TR/openscreen-network/#authentication) [=open a data channel=] @@ -184,12 +188,12 @@ A [=Local Peer-to-Peer session=] has the following capabilities: -Part of these capabilities are defined below as [protocol extensions](https://www.w3.org/TR/openscreenprotocol/#protocol-extensions) to the [[!openscreenprotocol|Open Screen Protocol]]. +Part of these capabilities are defined below as [protocol extensions](https://www.w3.org/TR/openscreen-network/#protocol-extensions) to the [[!openscreen-network|Open Screen Network Protocol]]. Data channel extension {#data-channel-extension} ------------------------------------------------ -In order to signal support for this protocol extension, the agent should include the [=data-channels=] [=agent-capability=] as part of the [agent-info-response](https://www.w3.org/TR/openscreenprotocol/#agent-info-response) message exchanged during [=discover metadata=]. +In order to signal support for this protocol extension, the agent should include the [=data-channels=] [=agent-capability=] as part of the [agent-info-response](https://www.w3.org/TR/openscreen-network/#messages) message exchanged during [=discover metadata=]. To open a data channel an agent may send a [=data-channel-open-request=] message on a new [[!RFC9000|QUIC]] stream. The [=Local Peer-to-Peer session=] must be authenticated. The message must contain the following values: @@ -223,7 +227,7 @@ WebTransport extension {#webtransport-extension} The protocol extension to [=send data on a channel=] provides an ergonomic way to send simple messages. An agent can [=open a WebTransport session=] for communication that requires low overhead and more granular streams control. -In order to signal support for this protocol extension, the agent should include the [=quick-transport=] [=agent-capability=] as part of the [agent-info-response](https://www.w3.org/TR/openscreenprotocol/#agent-info-response) message exchanged during [=discover metadata=]. +In order to signal support for this protocol extension, the agent should include the [=quick-transport=] [=agent-capability=] as part of the [agent-info-response](https://www.w3.org/TR/openscreen-network/#messages) message exchanged during [=discover metadata=]. An agent can open a WebTransport session by dialing a new [[!RFC9000|QUIC]] connection using the agent certificates established during [=authenticate an agent=]. During connection establishment, the ALPN token "q2q" must be used in the TLS handshake. @@ -236,7 +240,7 @@ 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 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. +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 Network 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} ------------------------------------------- @@ -776,9 +780,9 @@ Refer to the [WebTransport examples](https://www.w3.org/TR/webtransport/#example Security and privacy considerations {#security-and-privacy-considerations} ========================================================================= -Open Screen Protocol {#security-osp} +Open Screen Network Protocol {#security-osp} ------------------------------------ -The Local Peer-to-Peer API is meant to be implementable on the [[!openscreenprotocol|Open Screen Protocol]]. The Security and Privacy considerations of the Open Screen Protocol must therefore be considered when implementing this API. +The Local Peer-to-Peer API is meant to be implementable on the [[!openscreen-network|Open Screen Network Protocol]]. The Security and Privacy considerations of the Open Screen Network Protocol must therefore be considered when implementing this API. Personally identifiable information {#security-pii} --------------------------------------------------- @@ -809,7 +813,7 @@ The Local Peer-to-Peer API requires user permission for a page to access any pee Persistent State {#security-persistent-state} --------------------------------------------- -The persisted state considerations of the [[!openscreenprotocol|Open Screen Protocol]] must be followed when implementing this API. +The persisted state considerations of the [[!openscreen-network|Open Screen Network Protocol]] [Persistent State rules](https://www.w3.org/TR/openscreen-network/#persistent-state) must be followed when implementing this API. Secure Contexts {#security-secure-context} ------------------------------------------ @@ -818,7 +822,7 @@ The Local Peer-to-Peer API must only be provided in a secure context. Appendix A: OSP Extension Messages {#appendix-a} ================================================ -The following messages are defined according to and as an extension to the [[!openscreenprotocol|Open Screen Protocol]] [Messages](https://www.w3.org/TR/openscreenprotocol/#appendix-a). +The following messages are defined according to and as an extension to the [[!openscreen-network|Open Screen Network Protocol]] [Messages](https://www.w3.org/TR/openscreen-network/#appendix-a). Note: The type keys and capability IDs for these extensions are not officially registered yet. They will be registered as this specification matures. diff --git a/security-privacy-questionnaire.md b/security-privacy-questionnaire.md index c595f84..c831c41 100644 --- a/security-privacy-questionnaire.md +++ b/security-privacy-questionnaire.md @@ -20,7 +20,7 @@ - A: By design no such information should be exposed. 7. Does this specification allow an origin to send data to the underlying platform? - - A: The specification is meant to be implementable using the Open Screen Protocol, a cross platform protocol. + - A: The specification is meant to be implementable using the Open Screen Network Protocol, a cross platform protocol. 8. Do features in this specification enable access to device sensors? - A: The specification doesn't allow direct access to device sensors. 9. Do features in this specification enable new script execution/loading @@ -39,7 +39,7 @@ - A: A [Permission Policy Integration](https://wicg.github.io/local-peer-to-peer/#permission-policy-integration) has been defined. 14. How do the features in this specification work in the context of a browser’s Private Browsing or Incognito mode? - - A: The [specification](https://www.w3.org/TR/openscreenprotocol/#private-browsing-mode) of the OpenScreen protocol are to be followed in this area. + - A: The [specification](https://www.w3.org/TR/openscreen-network/#private-browsing-mode) of the Open Screen Network Protocol are to be followed in this area. 15. Does this specification have both "Security Considerations" and "Privacy Considerations" sections? - A: Both Security and Privacy concerns have been considered.