Skip to content

Move metadata discovery to network protocol #367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
backkem wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Move metadata discovery to network protocol #367

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 34 additions & 74 deletions application.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,13 @@ url: https://datatracker.ietf.org/doc/html/rfc5646#section-2; type: dfn; spec: R
url: https://datatracker.ietf.org/doc/html/rfc4122#section-4.4; type: dfn; spec: RFC4122; text: UUID
url: https://datatracker.ietf.org/doc/html/rfc6381#section-3; type: dfn; spec: RFC6381; text: codecs parameter
url: https://datatracker.ietf.org/doc/html/rfc8610#section-3; type: dfn; spec: RFC8610; text: concise data definition language
urlPrefix: https://w3c.github.io/openscreenprotocol/network.html#; type: dfn; spec: openscreen-network
text: agent-info
text: agent-info-request
text: agent-info-response
text: agent-info-event
text: agent-status-request
text: agent-status-response
</pre>

Introduction {#introduction}
Expand Down Expand Up @@ -218,109 +225,62 @@ Non-Functional Requirements {#requirements-non-functional}
Metadata Discovery {#metadata}
==============================

To learn further metadata, an agent may send an [=agent-info-request=] message
and receive back an [=agent-info-response=] message. Any agent may send this
request at any time to learn about the state and capabilities of another device,
which are described by the [=agent-info=] message in the
[=agent-info-response=].
The [Open Screen Network
Protocol](https://w3c.github.io/openscreenprotocol/network.html) defines the
[=agent-info=] message exchange mechanism, including the
[=agent-info-request=], [=agent-info-response=], and [=agent-info-event=]
messages. It also defines connection keep-alive via [=agent-status-request=]
and [=agent-status-response=] messages. See the Network Protocol for details
on message timing, pre-authentication behavior, and connection management.

If an agent changes any information in its [=agent-info=] message, it should
send an [=agent-info-event=] message to all other connected agents with the new
[=agent-info=] (without waiting for an [=agent-info-request=]).
This section defines the capability IDs used by the Open Screen Application
Protocol. Capabilities indicate which protocol features an agent supports and
are advertised in the capabilities field of the [=agent-info=] message.

The [=agent-info=] message contains the following fields:
Application Protocol Capabilities {#capabilities}
--------------------------------------------------

: display-name (required)
:: The display name of the agent, intended to be displayed to a user by the
requester. The requester should indicate through the UI if the responder
is not authenticated or if the display name changes.
The following capability IDs are defined by this specification:

: model-name (optional)
:: If the agent is a hardware device, the model name of
the device. This is used mainly for debugging purposes, but may be
displayed to the user of the requesting agent.

: capabilities (required)
:: The control protocols, roles, and media types the agent supports.
Presence indicates a capability and absence indicates lack of a
capability. Capabilities should should affect how an agent is
presented to a user, such as drawing a different icon depending on
the whether it receives audio, video or both.

: state-token (required)
:: A random alphanumeric value consisting of 8 characters in the range
[0-9A-Za-z]. This value is set before the agent makes its first connection
and must be set to a new value when the agent is reset or otherwise lost all
of its state related to this protocol.

: locales (required)
:: The agent's preferred locales for display of localized content, in the order
of user preference. Each entry is an RFC5646 [=language tag=].

The various capabilities have the following meanings:

: receive-audio
: <dfn>receive-audio</dfn> (1)
:: The agent can render audio via the other protocols it supports. Those other
protocols may report more specific capabilities, such as support for
certain audio codecs in the streaming protocol.

: receive-video
: <dfn>receive-video</dfn> (2)
:: The agent can receive video via the other protocols it supports. Those other
protocols may report more specific capabilities, such as support for
certain video codecs in the streaming protocol.

: receive-presentation
: <dfn>receive-presentation</dfn> (3)
:: The agent can receive presentations using the presentation protocol.

: control-presentation
: <dfn>control-presentation</dfn> (4)
:: The agent can control presentations using the presentation protocol.

: receive-remote-playback
: <dfn>receive-remote-playback</dfn> (5)
:: The agent can receive remote playback using the remote playback
protocol.

: control-remote-playback
: <dfn>control-remote-playback</dfn> (6)
:: The agent can control remote playback using the remote playback
protocol.

: receive-streaming
:: The agent can receiving streaming using the streaming protocol.
: <dfn>receive-streaming</dfn> (7)
:: The agent can receive streaming using the streaming protocol.

: send-streaming
: <dfn>send-streaming</dfn> (8)
:: The agent can send streaming using the streaming protocol.

Capabilities affect how an agent is presented to a user, such as drawing a
different icon depending on whether it receives audio, video, or both.

NOTE: See the [Capabilities Registry](https://github.com/w3c/openscreenprotocol/blob/main/capabilities.md)
for a list of all known capabilities (both defined by this specification, and
through [[#protocol-extensions]]).

Issue(343): Rewrite to not depend on QUIC, or move agent-status messges to the network spec

If a listening agent wishes to receive messages from an advertising agent or an
advertising agent wishes to send messages to a listening agent, it may wish to
keep the QUIC connection alive. Once neither side needs to keep the connection
alive for the purposes of sending or receiving messages, the connection should
be closed with an error code of 5139. In order to keep a QUIC connection alive, an
agent may send an [=agent-status-request=] message, and any agent that receives an
[=agent-status-request=] message should send an [=agent-status-response=] message. Such
messages should be sent more frequently than the QUIC idle_timeout transport
parameter (see Transport Parameter Encoding in QUIC) and QUIC PING
frames should not be used. An idle_timeout transport parameter of 25 seconds is
recommended. The agent should behave as though a timer less than the
idle_timeout were reset every time a message is sent on a QUIC stream. If the
timer expires, a [=agent-status-request=] message should be sent.

If a listening agent wishes to send messages to an advertising agent, the
listening agent can connect to the advertising agent "on demand"; it does not
need to keep the connection alive.

If an OSP agent suspends its network connectivity (e.g. for power saving
reasons), it should attempt to resume QUIC connections to the OSP agents to
which it was previously connected once network connectivity is restored. Once
reconnected, it should send `agent-status-request` messages to those agents.

The [=agent-info=] and [=agent-status-response=] messages may be extended to
include additional information not defined in this spec, as described in
[[#protocol-extension-fields]].
The [=agent-info=] message may be extended to include additional information
not defined in this spec, as described in [[#protocol-extension-fields]].

Message delivery using CBOR {#messages}
=======================================
Expand Down
43 changes: 3 additions & 40 deletions application_messages.cddl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,6 @@
; type key 10
agent-info-request = {
request
}

; type key 11
agent-info-response = {
response
1: agent-info ; agent-info
}

; type key 120
agent-info-event = {
0: agent-info ; agent-info
}

; Capability IDs defined by the Open Screen Application Protocol.
; The agent-info message (which contains capabilities) is defined
; in the Open Screen Network Protocol.
agent-capability = &(
receive-audio: 1
receive-video: 2
Expand All @@ -25,30 +12,6 @@ agent-capability = &(
send-streaming: 8
)

agent-info = {
0: text ; display-name
1: text ; model-name
2: [* agent-capability] ; capabilities
3: text ; state-token
4: [* text] ; locales
}

; type key 12
agent-status-request = {
request
? 1: status ; status
}

; type key 13
agent-status-response = {
response
? 1: status ; status
}

status = {
0: text ; status
}

request = (
0: request-id ; request-id
)
Expand Down
120 changes: 110 additions & 10 deletions network.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ url: https://datatracker.ietf.org/doc/html/rfc8610#section-3; type: dfn; spec: R
url: https://www.iso.org/standard/62021.html#; type: dfn; spec: iso18004; text: QR code
url: https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3; type: dfn; spec: RFC5280; text: digitalSignature
url: https://datatracker.ietf.org/doc/html/rfc8446#section-4.2.3; type: dfn; spec: RFC8446; text: signature scheme
url: https://datatracker.ietf.org/doc/html/rfc5646#section-2; type: dfn; spec: RFC5646; text: language tag
</pre>

Introduction {#introduction}
Expand Down Expand Up @@ -255,10 +256,27 @@ Transport and metadata discovery with QUIC {#transport}

If a [=listening agent=] wants to connect to or learn further metadata about an
[=advertising agent=], it initiates a [[!RFC9000|QUIC]] connection to the IP and port
from its SRV record. Prior to authentication, a message may be exchanged (such
as further metadata), but such info should be treated as unverified (such as
indicating to a user that a display name of an unauthenticated agent is
unverified).
from its SRV record.

Agents MAY exchange [=agent-info=] messages before [[#authentication]] completes
to allow early discovery of agent metadata for UI purposes. However, any
metadata received before authentication MUST be treated as unverified. The
network layer SHOULD indicate to users and application layers whether agent
metadata has been verified through authentication.

Prior to authentication, only the following messages are permitted:
- [=agent-info-request=], [=agent-info-response=], and [=agent-info-event=]
- Authentication messages defined in [[#authentication]]

The network layer MUST NOT deliver any other messages to the application layer
until authentication has completed successfully. This ensures the network
protocol maintains ownership over the security of unauthenticated connections.

To protect against abuse of pre-authentication metadata exchange (e.g., using
[=agent-info=] messages as a covert data transfer channel), the network layer
SHOULD enforce size limits on [=agent-info=] messages and rate limits on
metadata message exchanges. Extension fields in [=agent-info=] are permitted
but, like all pre-authentication data, MUST be treated as unverified.

The connection IDs used both by agents should be zero length. If zero length
connection IDs are chosen, agents are restricted from changing IP or port
Expand Down Expand Up @@ -348,8 +366,7 @@ The following X.509 v3 fields are to be set as follows:
</tr>
<tr>
<td>Issuer Name</td>
<td>CN = The `model-name` from the `agent-info` message, as
also set in the `agent-info` message.<br/>
<td>CN = The `model-name` from the [=agent-info=] message.<br/>
O = See note.<br/>
L = See note.<br/>
ST = See note.<br/>
Expand Down Expand Up @@ -428,6 +445,92 @@ Variable-length integers are encoded in the [=Variable-Length Integer Encoding=]
used by [[!RFC9000|QUIC]].


Metadata Discovery {#metadata}
----------------------------------

To learn metadata about another agent, an agent may send an
[=agent-info-request=] message and receive back an [=agent-info-response=]
message. Any agent may send this request at any time after a QUIC connection
is established.

If an agent changes any information in its [=agent-info=] message, it should
send an [=agent-info-event=] message to all other connected agents with the new
[=agent-info=] (without waiting for an [=agent-info-request=]).

The [=agent-info=] message contains the following fields:

: display-name (required)
:: The display name of the agent, intended to be displayed to a user by the
requester. The requester should indicate through the UI if the responder
is not authenticated or if the display name changes.

: model-name (optional)
:: If the agent is a hardware device, the model name of the device. This is
used mainly for debugging purposes, but may be displayed to the user of the
requesting agent.

: capabilities (required)
:: A list of capability IDs that the agent supports. Capability IDs are
unsigned integers. The meaning of specific capability IDs is defined by
application protocols that use this network protocol. See
[[#capabilities-registry]] for the extensibility mechanism.

: state-token (required)
:: A random alphanumeric value consisting of 8 characters in the range
[0-9A-Za-z]. This value is set before the agent makes its first connection
and must be set to a new value when the agent is reset or otherwise loses
all of its state related to this protocol.

: locales (required)
:: The agent's preferred locales for display of localized content, in the order
of user preference. Each entry is an RFC5646 [=language tag=].

### Capabilities Registry ### {#capabilities-registry}

Capability IDs allow agents to indicate which protocol features they support.
The capabilities field in [=agent-info=] contains a list of capability IDs.

Capability IDs 1-999 are reserved for the Open Screen Protocol. The
[Open Screen Application Protocol](https://w3c.github.io/openscreenprotocol/application.html)
defines capabilities in this range.

Capability IDs 1000 and above are available for extensions. Extension authors
should register their capability IDs in the public registry to prevent
conflicts.

See the [Capabilities
Registry](https://github.com/w3c/openscreenprotocol/blob/main/capabilities.md)
for a list of all known capabilities.

Connection Keep-Alive {#keep-alive}
----------------------------------

If a listening agent wishes to receive messages from an advertising agent or an
advertising agent wishes to send messages to a listening agent, it may wish to
keep the QUIC connection alive by periodically sending data on the connection.

To keep a QUIC connection alive, an agent may send an [=agent-status-request=]
message, and any agent that receives an [=agent-status-request=] message should
send an [=agent-status-response=] message. Such messages should be sent more frequently than the QUIC
idle_timeout transport parameter (see [=Transport Parameter Encoding=] in QUIC)
and QUIC PING frames should not be used. An idle_timeout transport parameter
of 25 seconds is recommended. The agent should behave as though a timer less
than the idle_timeout were reset every time a message is sent on a QUIC stream.
If the timer expires, an [=agent-status-request=] message should be sent.

Once neither side needs to keep the connection alive for the purposes of
sending or receiving messages, the connection should be closed with an error
code of 5139.

If a listening agent wishes to send messages to an advertising agent, the
listening agent can connect to the advertising agent "on demand"; it does not
need to keep the connection alive.

If an OSP agent suspends its network connectivity (e.g. for power saving
reasons), it should attempt to resume QUIC connections to the OSP agents to
which it was previously connected once network connectivity is restored.


Authentication {#authentication}
================================

Expand Down Expand Up @@ -772,12 +875,9 @@ requires users to make informed decisions about which agents to trust.
Because DNS-SD [=Instance Names=] are the primary information that the user
sees prior to authentication, careful presentation of these names is necessary.

Issue(346): Rephrase to not link DNS-SD with an agent-info, an application
message.

Agents must treat Instance Names as unverified information, and should check
that the Instance Name is a prefix of the display name received through the
<code>agent-info</code> message after a successful QUIC connection. Once an
[=agent-info=] message after a successful QUIC connection. Once an
agent has done this check, it can show the name as a <dfn noexport>verified
display name</dfn>.

Expand Down
Loading