Merge branch 'filling-out-spec' of https://github.com/webscreens/open…

…screenprotocol into filling-out-spec

biblio.json

@@ -0,0 +1,26 @@
+{
+    "CDDL": {
+        "authors": [
+            "H. Birkholz",
+            "C. Vigano",
+            "C. Bormann"
+        ],
+        "href": "https://datatracker.ietf.org/doc/draft-ietf-cbor-cddl/",
+        "title": "Concise data definition language (CDDL): a notational convention to express CBOR and JSON data structures",
+        "status": "Internet Draft",
+        "publisher": "IETF"
+    },
+    "QUIC": {
+        "authors": [
+            "J. Iyengar",
+            "M. Thomson"
+        ],
+        "date": "23 October 2018",
+        "href": "https://tools.ietf.org/html/draft-ietf-quic-transport-16",
+        "title": "Concise data definition language (CDDL): a notational convention to express CBOR and JSON data structures",
+        "status": "Internet Draft",
+        "publisher": "IETF"
+    }
+}
+
+

index.bs

@@ -64,7 +64,7 @@ The Open Screen Protocol connects browsers to devices capable of rendering Web
 content for a shared audience.  Typically, these are devices like
 Internet-connected TVs, HDMI dongles, or "smart" speakers.
 
-The protocol is suite of subsidiary network protocols that enable two user
+The protocol is a suite of subsidiary network protocols that enable two user
 agents to implement the [[PRESENTATION-API|Presentation API]] and
 [[REMOTE-PLAYBACK|Remote Playback API]] in an interoperable fashion.  This means
 that a user can expect these APIs work as intended when connecting two devices
@@ -238,37 +238,35 @@ Non-Functional Requirements {#requirements-non-functional}
 Discovery with mDNS {#discovery}
 ===============================
 
-Agents may discover one another using
-[DNS-SD](https://tools.ietf.org/html/rfc6763) over
-[mDNS](https://tools.ietf.org/html/rfc6762).  To do so, agents must
-use the service name "_openscreen._udp.local".
+Agents may discover one another using [[RFC6763|DNS-SD]] over [[RFC6762|mDNS]].
+To do so, agents must use the service name "_openscreen._udp.local".
 
 Advertising agents must include DNS TXT records with the following
 keys and values:
 
-- key "fp" with value of the certificate fingerpint of the advertising agent.
-  The format of the fingerprint is defined by [RFC 8122 section
-  5](https://tools.ietf.org/html/rfc8122#section-5), excluding the
-  "fingerprint:" prefix and including the hash function, space, and hex-encoded
-  fingerprint.  The fingerprint value also functions as an ID for the agent.
-  All agents must support the following hash functions: "sha-256", "sha-512".
-  Agents must not support the following hash functions: "md2", "md5". 
+-   key "fp" with value of the certificate fingerpint of the advertising agent.
+    The format of the fingerprint is defined by [RFC 8122 section
+    5](https://tools.ietf.org/html/rfc8122#section-5), excluding the
+    "fingerprint:" prefix and including the hash function, space, and hex-encoded
+    fingerprint.  The fingerprint value also functions as an ID for the agent.
+    All agents must support the following hash functions: "sha-256", "sha-512".
+    Agents must not support the following hash functions: "md2", "md5".
 
   <!-- TODO: include cross references to the specs for these hash functions. -->
 
-- key "mv" with an unsigned integer value that indicates that
-  metadata has changed.   The advertising agent must update it to a greater
-  value.  This signals to the listening agent that it should connect to the
-  advertising agent to discover updated metadata.
+-   key "mv" with an unsigned integer value that indicates that
+    metadata has changed.   The advertising agent must update it to a greater
+    value.  This signals to the listening agent that it should connect to the
+    advertising agent to discover updated metadata.
 
   <!-- TODO: Add examples of sample mDNS records. -->
- 
+
 An agent that advertises this service name must implement the
 transport and metadata discovery mechanism with QUIC described below.
 If a future version of this protocol uses mDNS but breaks
 compatibility with that mechanism, it should change the service name
-to a new value indicating a new mechanism for metadata discovery
-.  If future versions of this protocol or extensions to this
+to a new value indicating a new mechanism for metadata discovery.
+If future versions of this protocol or extensions to this
 protocol are compatible with the metadata discovery mechanism, they
 can use it to indicate support for future versions and extensions.
 
@@ -277,8 +275,7 @@ Transport and metadata discovery with QUIC {#transport}
 =======================================================
 
 If a listening agent wants to connect to an advertising agent, or to
-learn further metdata about it, it initiates a
-[QUIC](https://tools.ietf.org/html/draft-ietf-quic-transport-16) connection to
+learn further metadata about it, it initiates a [[!QUIC]] connection to
 the IP and port from the 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
@@ -288,17 +285,17 @@ To learn further metadata, an agent may send an agent-info-request
 message (see Appendix A) and receive back an agent-info-response message.  The
 messages may contain the following information with the following meaning:
 
-- display-name: (required) The display name of the responding agent intended to be
-  displayed to a user by the requesting agent.  If the responding agent is
-  not yet authenticated, the requesting agent should make UI affordance for
-  indicating to the user that the display name is not yet verified.  If the
-  responding agent changes its display name, the requesting agent should
-  make UI affordance for indicating to the user that the display name has
-  changed. 
+-   display-name: (required) The display name of the responding agent intended
+    to be displayed to a user by the requesting agent.  If the responding agent
+    is not yet authenticated, the requesting agent should make UI affordance for
+    indicating to the user that the display name is not yet verified.  If the
+    responding agent changes its display name, the requesting agent should
+    make UI affordance for indicating to the user that the display name has
+    changed.
 
-- model-name: (optional) If the agent is a hardward 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.
+-   model-name: (optional) If the agent is a hardward 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.
 
 <!-- TODO: Add device type and/or capabilities -->
 
@@ -312,15 +309,13 @@ be closed with an error code of 1.  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 section 18 of
-[QUIC](https://tools.ietf.org/html/draft-ietf-quic-transport-16)) and QUIC PING
+parameter (see section 18 of [[!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 client agent wishes to send messages to a server agent, the client
 agent can connect to the server agent "on demand"; it does not need to
 keep the connection alive.
@@ -336,26 +331,26 @@ to easily extend this message.
 Messages delivery using CBOR and QUIC streams {#control}
 ========================================================
 
-Messages are serialized using [CBOR](https://tools.ietf.org/html/rfc7049).  To
+Messages are serialized using [[!RFC7049|CBOR]].  To
 send a group of messages in order, that group of messages must be sent in one
 QUIC stream.  Independent groups of messages (with no ordering dependency
 across groups) should be sent in different QUIC streams.  In order to put
 multiple CBOR-serialized messages into the the same QUIC stream, the following
 is used.
 
-For each message, the sender must write to the QUIC stream the following: 
-1. A type key representing the type of the message, encoded as a variable-length
-   integer (see Appendix A for type keys) 
+For each message, the sender must write to the QUIC stream the following:
+
+1.  A type key representing the type of the message, encoded as a variable-length
+    integer (see Appendix A for type keys)
 
-2. The message length encoded as a variable-length integer 
+2.  The message length encoded as a variable-length integer
 
-3. The messge encoded as CBOR (whose length must match the prefixed length)
+3.  The messge encoded as CBOR (whose length must match the value in step 2)
 
 If an agent receives a message for which it does not recognize a
 type key, it must close the QUIC connection with an application error
 code of 2 and should include the unknown type key in the reason phrase
-(see [QUIC](https://tools.ietf.org/html/draft-ietf-quic-transport-16)
-sections 19.4).
+(see [[!QUIC]] section 19.4).
 
 Variable-length integers are encoded in the same format as defined by [QUIC
 transport section
@@ -399,8 +394,7 @@ Mitigations and defenses {#security-defenses}
 
 Appending A: Messages
 =====================
-The following messages are defined with
-[CDDL](https://datatracker.ietf.org/doc/draft-ietf-cbor-cddl/). When
+The following messages are defined with [[CDDL]]. When
 integer keys are used, a comment is appended to the line to indicate
 the name of the field. Each root message (one that can be put into a
 QUIC stream without being inclosed by another message) has a comment