/
index.bs
2119 lines (1642 loc) · 93.3 KB
/
index.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class='metadata'>
Title: Open Screen Protocol
Shortname: openscreenprotocol
Level: 1
Status: w3c/ED
ED: https://webscreens.github.io/openscreenprotocol/
Canonical URL: ED
Editor: Mark Foltz, Google, https://github.com/mfoltzgoogle, w3cid 68454
Repository: webscreens/openscreenprotocol
Abstract: The Open Screen Protocol is a suite of network protocols that allow
user agents to implement the [[PRESENTATION-API|Presentation API]] and
the [[REMOTE-PLAYBACK|Remote Playback API]] in an interoperable
fashion.
Group: Second Screen Community Group
Mailing List: public-webscreens@w3c.org
Mailing List Archives: https://lists.w3.org/Archives/Public/public-webscreens/
Markup Shorthands: markdown yes, dfn yes, idl yes
</pre>
<p boilerplate="copyright">
<a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">
Copyright</a> © [YEAR] the Contributors to the [TITLE] Specification,
published by the <a href="https://www.w3.org/community/webscreens/">
Second Screen Community Group</a> under the
<a href="https://www.w3.org/community/about/agreements/cla/">
W3C Community Contributor License Agreement (CLA)</a>. A human-readable
<a href="http://www.w3.org/community/about/agreements/cla-deed/">summary</a>
is available.
</p>
Issue: Add short names to Presentation API spec, so that BS autolinking works as designed.
Issue: Can autolinks to HTML51 be automatically generated?
<pre class="anchors">
urlPrefix: https://w3c.github.io/presentation-api/#dfn-; type: dfn; spec: PRESENTATION-API
text: available presentation display
text: controller
text: controlling user agent
text: controlling browsing context
text: presentation
text: presentation display
text: presentation display availability
text: presentation id
text: presentation request url
text: receiver
text: receiving browsing context
text: receiving user agent
text: available presentation display
urlPrefix: https://w3c.github.io/presentation-api/; type: interface; spec: PRESENTATION-API
text: PresentationConnection
urlPrefix: https://w3c.github.io/remote-playback/#dfn-; type: dfn; spec: REMOTE-PLAYBACK
text: availability sources set
text: compatible remote playback device
text: initiate remote playback
text: media element state
text: media resources
text: remote playback devices
text: remote playback source
urlPrefix: https://www.w3.org/TR/html51/single-page.html; type: dfn; spec: HTML51
text: media element
url: https://tools.ietf.org/html/rfc6762#section-9; type: dfn; spec: RFC6762; text: conflict resolution
url: https://tools.ietf.org/html/rfc6763#section-7; type: dfn; spec: RFC6763; text: service name
url: https://tools.ietf.org/html/rfc6763#section-4.1.1; type: dfn; spec: RFC6763; text: instance name
url: https://tools.ietf.org/html/rfc5646#section-2; type: dfn; spec: RFC5646; text: language tag
url: https://tools.ietf.org/html/rfc4122#section-4.4; type: dfn; spec: RFC4122; text: UUID
</pre>
<h2 class='no-num no-toc no-ref' id='document-status'>Status of this document</h2>
This specification was published by the [Second Screen Community
Group](https://www.w3.org/community/webscreens/). It is not a W3C Standard nor
is it on the W3C Standards Track. It should not be viewed as a stable
specification, and may change in substantial ways at any time. A future version
of this document will be published as a Community Group Report.
Please note that under the [W3C Community Contributor License Agreement
(CLA)](https://www.w3.org/community/about/agreements/cla/) there is a limited
opt-out and other conditions apply.
Learn more about [W3C Community and Business
Groups](http://www.w3.org/community/).
Introduction {#introduction}
============================
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 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
from independent implementations of the Open Screen Protocol.
The Open Screen Protocol is a specific implementation of these two APIs, meaning
that it does not handle all possible ways that browsers and presentation
displays could support these APIs. The Open Screen Protocol specifically
supports browsers and displays that are connected via the same local area
network, and that initiate presentation or remote playback by sending a URL
from the browser to the target display.
The Open Screen Protocol is intended to be extensible, so that additional
capabilities can be added over time. This may include new implementations of
existing APIs, or new APIs.
Terminology {#terminology}
--------------------------
We use the term "agent" to mean any implementation of this protocol
(browser, device, or otherwise), acting as a controller or a receiver.
We borrow terminology from the [[PRESENTATION-API|Presentation API]]. We call
the agent that is used to discover and initiate presentation of Web content on
another device the [=controller=] (or [=controlling user agent=] when it is a
browser). We call the agent on the device rendering the Web content the
[=receiver=] or [=presentation display=] (or [=receiving user agent=] when it is
a browser). [=presentation display availability=] refers to whether or not a
[=receiver=] is compatible with a [=presentation request URL=]. However, in the
[[PRESENTATION-API|Presentation API]], a "controller" refers to as a specific
browsing context within the browser, whereas here the "controller" refers to the
browser itself, although it may be acting on behalf of a browsing context.
We borrow terminology from the [[REMOTE-PLAYBACK|Remote Playback API]]. The
agent responsible for rendering media of a remote playback is called the
[=remote playback device=]. In this document, we also refer to it as the
*receiver* because it is shorter and keeps terminology consistent between
presentations and remote playbacks. Similarly, we use the term "controller"
(referred to as the "user agent" in the [[REMOTE-PLAYBACK|Remote Playback API]])
to refer to the agent that starts, terminates, and controls the remote playback.
For media streaming, we refer to the agent sending media as the media
*sender* and the agent receiving the media as the media *receiver*.
Note that a media *receiver* may or may not be a *receiver* or
*controller* as defined by the Presentation API or Remote Playback
API. Also note that an agent may be both a *sender* and *receiver*.
For additional terms and idioms specific to the [[PRESENTATION-API|Presentation
API]] or [[REMOTE-PLAYBACK|Remote Playback API]], please consult the respective
specifications.
Issue(144): Receiver/Controller/Agent terminology.
Requirements {#requirements}
============================
Presentation API Requirements {#requirements-presentation-api}
--------------------------------------------------------------
1. A controlling user agent must be able to discover the presence of a
presentation display connected to the same IPv4 or IPv6 subnet and reachable
by IP multicast.
2. A controlling user agent must be able to obtain the IPv4 or IPv6 address of
the display, a display name for the display, and an IP port number for
establishing a network transport to the display.
3. A controlling user agent must be able to determine if the receiver is
reasonably capable of rendering a specific [=presentation request URL=].
4. A controlling user agent must be able to start a new presentation on a receiver given a
[=presentation request URL=] and [=presentation ID=].
5. A controlling user agent must be able to create a new
{{PresentationConnection}} to an existing presentation on the
receiver, given its [=presentation request URL=] and [=presentation ID=].
6. It must be possible to close a {{PresentationConnection}} between a
controller and a presentation, and signal both parties with the
reason why the connection was closed.
7. Multiple controllers must be able to connect to a single presentation
simultaneously, possibly from from one or more [=controlling user agents=].
8. Messages sent by the controller must be delivered to the presentation (or
vice versa) in a reliable and in-order fashion.
9. If a message cannot be delivered, then the controlling user agent must be
able to signal the receiver (or vice versa) that the connection should be
closed with reason `error`.
10. The controller and presentation must be able to send and receive `DOMString`
messages (represented as `string` type in ECMAScript).
11. The controller and presentation must be able to send and receive binary
messages (represented as `Blob` objects in HTML5, or `ArrayBuffer` or
`ArrayBufferView` types in ECMAScript).
12. The controlling user agent must be able to signal to the receiver to
terminate a presentation, given its [=presentation request URL=] and [=presentation
ID=].
13. The receiver must be able to signal all connected controlling user agents
when a presentation is terminated.
Remote Playback API Requirements {#requirements-remote-playback}
----------------------------------------------------------------
1. A [=controlling user agent=] must be able to find out whether there is at
least one compatible [=remote playback device=] available for a given
{{HTMLMediaElement}}, both instantaneously and continuously.
2. A controlling user agent must be able to to [=initiate remote playback=] of
an {{HTMLMediaElement}} to a compatible remote playback device.
3. The controlling user agent must be able send media sources as URLs and text
tracks from an {{HTMLMediaElement}} to a compatible remote playback device.
4. During remote playback, the controlling user agent and the remote playback
device must be able to synchronize the [=media element state=] of the
{{HTMLMediaElement}}.
5. During remote playback, either the controlling user agent or the
remote playback device must be able to disconnect from the other party.
6. The controlling user agent should be able to pass locale and text
direction information to the remote playback device to assist in rendering
text during remote playback.
Non-Functional Requirements {#requirements-non-functional}
----------------------------------------------------------
1. It should be possible to implement an Open Screen presentation display using
modest hardware requirements, similar to what is found in a low end
smartphone, smart TV or streaming device. See the [Device
Specifications](device_specs.md) document for expected presentation display
hardware specifications.
2. It should be possible to implement an Open Screen controlling user agent on a
low-end smartphone. See the [Device Specifications](device_specs.md) document
for expected controlling user agent hardware specifications.
3. The discovery and connection protocols should minimize power consumption,
especially on the controlling user agent which is likely to be battery
powered.
4. The protocol should minimize the amount of information provided to a passive
network observer about the identity of the user, activity on the controlling
user agent and activity on the receiver.
5. The protocol should prevent passive network eavesdroppers from learning
presentation URLs, presentation IDs, or the content of presentation messages
passed between controllers and presentations.
6. The protocol should prevent active network attackers from impersonating a
display and observing or altering data intended for the controller or
presentation.
7. The controlling user agent should be able to discover quickly when a
presentation display becomes available or unavailable (i.e., when it connects
or disconnects from the network).
8. The controlling user agent should present sensible information to the user
when a protocol operation fails. For example, if a controlling user agent is
unable to start a presentation, it should be possible to report in the
controlling user agent interface if it was a network error, authentication
error, or the presentation content failed to load.
9. The controlling user agent should be able to remember authenticated
presentation displays. This means it is not required for the user to
intervene and re-authenticate each time the controlling user agent connects
to a pre-authenticated display.
10. Message latency between the controller and a presentation should be minimized
to permit interactive use. For example, it should be comfortable to type in
a form in the controller and have the text appear in the presentation in real
time. Real-time latency for gaming or mouse use is ideal, but not a
requirement.
11. The controlling user agent initiating a presentation should communicate its
preferred locale to the receiver, so it can render the presentation content
in that locale.
12. It should be possible to extend the control protocol (above the discovery and
transport levels) with optional features not defined explicitly by the
specification, to facilitate experimentation and enhancement of the base
APIs.
Discovery with mDNS {#discovery}
===============================
Agents must discover one another using [[RFC6763|DNS-SD]] over [[RFC6762|mDNS]].
To do so, agents must use the [=Service Name=] `_openscreen._udp.local`.
Issue(107): Define suspend and resume behavior for discovery protocol.
An <dfn noexport>advertising agent</dfn> is one that responds to mDNS queries
for `_openscreen._udp.local`. Such an agent should have a <dfn noexport>display
name</dfn> (a non-empty string) that is a human readable description of the
presentation display, e.g. "Living Room TV."
A <dfn noexport>listening agent</dfn> is one that sends mDNS queries for
`_openscreen._udp.local`. Listening agents may have a display name.
Advertising agents must use a DNS-SD [=Instance Name=] that is a prefix of the
agent's display name. If the Instance Name is not the complete display name, it
must be terminated by a null (`\000`) character, so that a listening agent knows
it has been truncated.
Advertising agents must follow the mDNS [=conflict resolution=] procedure, to
prevent multiple advertising agents from using the same DNS-SD Instance Name.
Agents should be careful when displaying Instance Names to users; see
[[#instance-names]] for guidelines on Instance Name display.
Advertising agents must include DNS TXT records with the following
keys and values:
: fp
:: The certificate fingerprint 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".
Issue: Include cross references to the specs for these hash functions.
: mv
:: 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.
: at
:: An alphanumeric, unguessable token consisting of characters from the set
`[A-Za-z0-9+/]`.
Note: `at` prevents off-LAN parties from attempting authentication; see
[[#remote-active-mitigations]]. `at` should have at least 32 bits of true
entropy to make brute force attacks impractical.
Issue: Add examples of sample mDNS records.
Future extensions to this QUIC-based protocol can use the same metadata
discovery process to indicate support for those extensions, through a
capabilities mechanism to be determined. If a future version of the Open Screen
Protocol uses mDNS but breaks compatibility with the metadata discovery process,
it should change the DNS-SD service name to a new value, indicating a new
mechanism for metadata discovery.
Transport and metadata discovery with QUIC {#transport}
=======================================================
If an agent wants to connect to or learn further metadata about another agent,
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 unauthenticated agent is unverified).
The connection IDs used both by the [[QUIC]] client and server should
be zero length. If zero length connection IDs are chosen, agents are
restricted from changing IP or port without establishing a new QUIC
connection. In such cases, clients and servers must establish a new
QUIC connection in order to change IP or port.
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=].
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 properties:
: 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)
:: 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 media types it supports.
: 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
:: The agent can generally receive audio for the control protocols it
supports. Each control protocol can have more specific capability
mechanisms, such as support for specific URLs in the presentation
protocol.
: receive-video
:: The agent can generally receive video for the control protocols it
supports. Each control protocol can have more specific capability
mechanisms, such as support for specific URLs in the presentation
protocol.
: receive-presentation
:: The agent can receive presentations using the presentation protocol.
: control-presentation
:: The agent can control presentations using the presentation protocol.
: receive-remote-playback
:: The agent can receive remote playback using the remote playback
protocol.
: control-remote-playback
:: The agent can control remote playback using the remote playback
protocol.
: receive-streaming
:: The agent can receiving streaming using the streaming protocol.
: send-streaming
:: The agent can send streaming using the streaming protocol.
Note: See the
[Capabilities Registry](https://webscreens.github.io/openscreenprotocol/capabilities.md)
for a list of all known capabilities (both defined by this specification, and
through [[#protocol-extensions]]).
Listening agents act as QUIC clients. Advertising agents act as QUIC servers.
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 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.
Issue(108): Define suspend and resume behavior for connection protocol.
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]].
Messages delivery using CBOR and QUIC streams {#messages}
========================================================
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)
2. The message encoded as CBOR.
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 404 and should include the unknown type key in the reason phrase
(see [[QUIC#section-19.4|QUIC transport section 19.4]]).
Variable-length integers are encoded in the same format as defined by
[[QUIC#section-16| QUIC transport section 16]].
Many messages are requests and responses, so a common format is defined for
those. A request and a response includes a request ID which is an unsigned
integer chosen by the requester. Responses must include the request ID of the
request they are associated with.
Issue(139): Clarify scoping/uniqueness of request IDs.
Authentication {#authentication}
================================
Each supported authentication method is implemeted via authentication messages
specific to that method. The authentication method is explicitly specified by
the message itself. The authentication status message is common for all authentication
methods. Any new authentication method added must define new authentication messages.
Open Screen Agents must implement [[#authentication-with-spake2]] with pre-shared keys.
Prior to authentication, agents exchange [=auth-capabilities=] messages specifying
pre-shared key (PSK) ease of input for the user and supported PSK input methods.
The agent with the lowest PSK ease of input presents a PSK to the user when the agent
either sends or receives an authentication request. In case both agents have the same
PSK ease of input value, the server presents the PSK to the user. The same pre-shared key
is used by both agents. The agent presenting the PSK to the user is the PSK presenter,
the agent requiring the user to input the PSK is the PSK consumer.
PSK ease of input is an integer in the range from 0 to 100 inclusive, where 0 means
it is not possible for the user to input PSK on this device and 100 means
that it's easy for the user to input PSK on the device. Supported PSK input methods
are numeric and scanning a QR-code. Devices with non-zero PSK ease of input must
support the numeric PSK input method.
Any authentication method may require an [=auth-initiation-token=] before
showing a PSK to the user or requesting PSK input from the user. For an
[=advertising agent=], the `at` field in its mDNS TXT record must be used as the
`auth-initation-token` in the the first authentication message sent to or from
that agent. Agents should discard any authentication message whose
`auth-initation-token` is set and does not match the `at` provided by the
advertising agent.
Authentication with SPAKE2 {#authentication-with-spake2}
--------------------------
For all messages and objects defined in this section, see Appendix A for
the full CDDL definitions.
The default authentication method is
\[SPAKE2](https://tools.ietf.org/html/draft-irtf-cfrg-spake2-08) with
the following cipher suite:
1. Elliptic curve is [Curve25519](https://tools.ietf.org/html/rfc7748#page-4).
2. Hash function is \[SHA-512](https://tools.ietf.org/html/rfc6234).
3. Key derivation function is \[HKDF](https://tools.ietf.org/html/rfc5869).
4. Message authentication code is \[HMAC](https://tools.ietf.org/html/rfc2104).
5. Password hash function is SHA-512.
Open Screen Protocol does not use a memory-hard hash function to hash PSKs
with SPAKE2 and uses SHA-512 instead as the PSK is one-time use and
is not stored in any form.
SPAKE2 provides explicit mutual authentication.
This authentication method assumes the agents share a low-entropy secret,
such as a number or a short password that could be entered by a user on a
phone, a keyboard or a TV remote control.
SPAKE2 is not symmetric and has two roles, Alice (A) and Bob (B).
The client acts as Alice, the server acts as Bob.
The messages used in this authentication method are: [=auth-spake2-need-psk=],
[=auth-spake2-message=], [=auth-spake2-confirmation=] and [=auth-status=].
SPAKE2 describes in detail how [=auth-spake2-message=] and [=auth-spake2-confirmation=]
are computed.
If the PSK presenter wants to authenticate, the PSK presenter starts the
authentication process by presenting the PSK to the user and sending a
[=auth-spake2-message=] message. When the PSK consumer receives the
[=auth-spake2-message=] message, the PSK consumer prompts the user for the PSK input
if it has not done so yet.
If the PSK consumer wants to authenticate, the PSK consumer sends a
[=auth-spake2-need-psk=] message to the PSK presenter to start the authentication
process and prompts the user to input the PSK. If the PSK presenter receives a
[=auth-spake2-need-psk=] message after starting authentication from their side, the
PSK presenter ignores the [=auth-spake2-need-psk=] message.
After the user inputs the PSK into the PSK consumer, the PSK consumer computes
and sends a [=auth-spake2-message=].
When either agent both knows the PSK and has received a [=auth-spake2-message=]
message, the agent computes and sends a [=auth-spake2-confirmation=] message.
When either agent has received both [=auth-spake2-message=] and
[=auth-spake2-confirmation=] messages, the agent validates the confirmation message
and sends the [=auth-status=] authenticated message.
Presentation Protocol {#presentation-protocol}
=====================
This section defines the use of the Open Screen Protocol for starting,
terminating, and controlling presentations as defined by
[[PRESENTATION-API|Presentation API]]. [[#presentation-api]]
defines how APIs in [[PRESENTATION-API|Presentation API]] map to the
protocol messages defined in this section.
Issue(123): Add a capability that indicates support for the presentation protocol.
Issue(160): Refinements to Presentation API protocol.
To learn which receivers are [=available presentation displays=] for a
particular URL or set of URLs, the controller may send a
[=presentation-url-availability-request=] message with the following values:
: urls
:: A list of presentation URLs. Must not be empty.
: watch-duration
:: The period of time that the controller is interested in receiving updates
about their URLs, should the availability change.
: watch-id
:: An identifier the receiver must use when sending updates about URL
availability so that the controller knows which URLs the receiver is referring
to.
In response, the receiver should send one [=presentation-url-availability-response=]
message with the following values:
: url-availabilities
:: A list of URL availability states. Each state must correspond to the matching URL
from the request by list index.
While the watch is valid (the watch-duration has not expired), the receivers
should send [=presentation-url-availability-event=] messages when URL
availabilities change. Such events contain the following values:
: watch-id
:: The watch-id given in the [=presentation-url-availability-response=],
used to refer to the presentation URLs whose availability has changed.
: url-availabilities
:: A list of URL availability states. Each state must correspond to the URLs from the
request referred to by the watch-id.
Note that these messages are not broadcasted to all controllers. They are sent
individually to controllers that have requested availability for the URLs that
have changed in availability state within the watch duration of the original
availability request.
To save power, the controller may disconnect the QUIC connection and
later reconnect to send availability requests and receive availability
responses and updates. The QUIC connection ID may or may not be the same
when reconnecting.
To start a presentation, the controller may send a
[=presentation-start-request=] message to the receiver with the following
values:
: presentation-id
:: The presentation identifier
: url
:: The selected presentation URL
: headers
:: headers that the receiver should use to fetch the presentation URL. For example,
[[PRESENTATION-API#establishing-a-presentation-connection|section 6.6.1]] of
the Presentation API says that the Accept-Language header should be
provided.
The presentation ID must follow the restrictions defined by
[[PRESENTATION-API#common-idioms|section 6.1]] of the Presentation API, in that
it must consist of at least 16 ASCII characters.
When the receiver receives the [=presentation-start-request=], it should send back a
[=presentation-start-response=] message after either the presentation URL has been
fetched and loaded, or the receiver has failed to do so. If it has failed, it
must respond with the appropriate result (such as invalid-url or timeout). If
it has succeeded, it must reply with a success result.
Additionally, the response must include the following:
: connection-id
:: An ID that both agents can use to send connection messages
to each other. It is chosen by the receiver for ease of implementation: if
the message receiver chooses the connection-id, it may keep the ID unique
across connections, thus making message demuxing/routing easier.
To send a presentation message, the controller or receiver may send a
[=presentation-connection-message=] with the following values:
: connection-id
:: The ID from the [=presentation-start-response=] or
[=presentation-connection-open-response=] messages.
: message
:: The presentation message data.
To terminate a presentation, the controller may send a
[=presentation-termination-request=] message with the following values:
: presentation-id
:: The ID of the presentation to terminate.
: reason
:: The reason the presentation is being terminated.
When a [=receiver=] receives a [=presentation-termination-request=], it should
send back a [=presentation-termination-response=] message to the requesting
controller. It should also notify other controllers about the termination by sending
a [=presentation-termination-event=] message. And it can send the same message if
it terminates a presentation without a request from a controller to do so. This
message contains the following values:
: presentation-id
:: The ID of the presentation that was terminated.
: reason
:: The reason the presentation was terminated.
To accept incoming connection requests from controller, a receiver must receive
and process the [=presentation-connection-open-request=] message which contains the
following values:
: presentation-id
:: The ID of the presentation to connect to.
: url
:: The URL of the presentation to connect to.
The receiver should, upon receipt of a
[=presentation-connection-open-request=] message, send back a
[=presentation-connection-open-response=] message which contains the
following values:
: result
:: a code indicating success or failure, and the reason for the failure
: connection-id
:: An ID that both agents can use to send connection messages
to each other. It is chosen by the receiver for ease of implementation (if
the message receiver chooses the connection-id, it may keep the ID unique
across connections, thus making message demuxing/routing easier).
: connection-count
:: The new number of open connections to the presentation that received
the incoming connection request.
If the [=presentation-connection-open-response=] message indicates success, the
receiver should also send a [=presentation-change-event=] to all other endpoints
that have an active presentation connection to that presentation with the
values:
: presentation-id
:: The ID of the presentation that just received a new presentation connection.
: connection-count
:: The new total number of open connections to that presentation.
A controller may close a connection without terminating the presentation by
sending a [=presentation-connection-close-event=] message to the receiver with the
following values:
: connection-id
:: The ID of the connection that was closed.
: reason
:: Set to `close-method-called` or `connection-object-discarded`.
The receiver may also close a connection without terminating a presentation. If
it does so, it should send a [=presentation-connection-close-event=] message to the
controller with the following values:
: connection-id
:: The ID of the connection that was closed.
: reason
:: Set to `close-method-called` or `connection-object-discarded`.
: connection-count
:: The number of open presentation connections that remain.
If a receiver closes a presentation connection (for any reason), it should send
a [=presentation-change-event=] to all other controllers with an open connection
to that presentation with the values:
: presentation-id
:: The ID of the presentation that just closed a connection.
: connection-count
:: The number of open presentation connections that remain.
Note: When an agent closes a presentation connection, it is always successful,
so request and response messages are not needed. A request to terminate a
presentation may succeed or fail, so a response message is required.
Presentation API {#presentation-api}
---------------------------------------------
This section defines how the [[PRESENTATION-API|Presentation API]] uses the
[[#presentation-protocol]].
When [[PRESENTATION-API#the-list-of-available-presentation-displays|section
6.4.2]] says "This list of presentation displays ... is populated based on an
implementation specific discovery mechanism", the [=controlling user agent=] may
use the mDNS, QUIC, [=agent-info-request=], and
[=presentation-url-availability-request=] messages defined previously in this spec
to discover receivers.
When [[PRESENTATION-API#the-list-of-available-presentation-displays|section
6.4.2]] says "To further save power, ... implementation specific discovery of
presentation displays can be resumed or suspended.", the [=controlling user
agent=] may use the power saving mechanism defined in the previous section.
When [[PRESENTATION-API#starting-a-presentation-connection|section 6.3.4]] says
"Using an implementation specific mechanism, tell U to create a receiving
browsing context with D, presentationUrl, and I as parameters.", U (the
[=controlling user agent=]) may send a [=presentation-start-request=] message to D
(the receiver), with I for the presentation identifier and presentationUrl for
the selected presentation URL.
Issue: Once the Presentation API has text about reconnecting via an
implementation specific mechanism, quote that here and map it to a message.
When [[PRESENTATION-API#sending-a-message-through-presentationconnection|section
6.5.2]] says "Using an implementation specific mechanism, transmit the contents
of messageOrData as the presentation message data and messageType as the
presentation message type to the destination browsing context", the
[=controlling user agent=] may send a [=presentation-connection-message=] with
messageOrData for the presentation message data. Note that the messageType is
embedded in the encoded CBOR type and does not need an additional value in the
message.
When [[PRESENTATION-API#closing-a-presentationconnection|section 6.5.5]] says
"Start to signal to the destination browsing context the intention to close the
corresponding PresentationConnection", the [=user agent=] may send a
[=presentation-connection-close-event=] message to the user agent with the
destination browsing context and a [=presentation-change-event=] when required.
When
[[PRESENTATION-API#terminating-a-presentation-in-a-controlling-browsing-context|section
6.5.6]] says "Send a termination request for the presentation to its receiving
user agent using an implementation specific mechanism", the [=controlling user
agent=] may send a [=presentation-termination-request=] message.
When [[PRESENTATION-API#monitoring-incoming-presentation-connections|section
6.7.1]]
says "it MUST listen to and accept incoming connection requests from a
controlling browsing context using an implementation specific
mechanism", the [=receiving user agent=] must receive and process the
[=presentation-connection-open-request=].
When [[PRESENTATION-API#monitoring-incoming-presentation-connections|section
6.7.1]] says "Establish the connection between the controlling and receiving
browsing contexts using an implementation specific mechanism.", the [=receiving
user agent=], must send a [=presentation-connection-open-response=] message and
[=presentation-change-event=] messages when required.
Remote Playback Protocol {#remote-playback-protocol}
========================
This section defines the use of the Open Screen Protocol for starting, terminating,
and controlling remote playback of media as defined by the
[[REMOTE-PLAYBACK|Remote Playback API]]. [[#remote-playback-api]] defines how
APIs in [[REMOTE-PLAYBACK|Remote Playback API]] map to the protocol messages
defined in this section.
For all messages defined in this section, see Appendix A for the full
CDDL definitions.
Issue(123): Add a capability that indicates support for the remote playback protocol.
Issue(148): Make a required/default remote playback state table.
Issue(159): Refinements to Remote Playback protocol.
To learn which receivers are [=compatible remote playback device=]s (also called
available [=remote playback devices=]) for a particular URL or set of URLs, the
controller may send a [=remote-playback-availability-request=] message with the
following values:
: urls
:: A list of [=media resources=]. Must not be empty.
Issue(146): Remote Playback HTTP headers.
: headers
:: headers that the receiver should use to fetch the
urls. For example,
[[REMOTE-PLAYBACK#establishing-a-connection-with-a-remote-playback-device|section 6.2.4 of
the Remote Playback API]] says that the Accept-Language header should be
provided.
: watch-duration
:: The period of time that the controller is interested in receiving updates
about their URLs, should the availability change.
: watch-id
:: An identifier the receiver must use when sending updates about URL
availability so that the controller knows which URLs the receiver is referring
to.
In response, the receiver should send a [=remote-playback-availability-response=]
message with the following values:
: url-availabilities
:: A list of URL availability states. Each state must correspond to the matching URL
from the request by list index.
The receivers should later (up to the current time plus request
watch-duration) send [=remote-playback-availability-event=] messages if
URL availabilities change. Such events contain the following values:
: watch-id
:: The watch-id given in the remote-playback-url-availability-response,
used to refer to the remote playback URLs whose availability has changed.
: url-availabilities
:: A list of URL availability states. Each state must correspond to the URLs from the
request referred to by the watch-id.
Note that these messages are not broadcasted to all controllers. They are sent
individually to controllers that have requested availability for the URLs that
have changed in availability state within the watch duration of the original
availability request.
To save power, the controller may disconnect the QUIC connection and
later reconnect to send availability requests and receive availability
responses and updates. The QUIC connection ID may or may not be the same
when reconnecting.
To start remote playback, the controller may send a
[=remote-playback-start-request=] message to the receiver with the following
values:
: remote-playback-id
:: An identifier for this remote playback. It should be universally unique
among all remote playbacks.
Note: A version 4 (pseudorandom) [=UUID=] is recommended as it meets the
requirements for a remote-playback-id.
: urls
:: The [=media resources=] that the controller has selected for playback on the
receiver.
: text-track-urls
:: URLs of text tracks associated with the [=media resources=].
: controls
:: Initial controls for modifying the initial state of the remote playback, as
defined in [[#remote-playback-state-and-controls]]. The controller may send
controls that are optional for the receiver to support before it knows the
receiver supports them. If the receiver does not support them, it will
ignore them and the controller will learn that it does not support them from
the [=remote-playback-start-response=] message.
When the receiver receives a [=remote-playback-start-request=] message, it should
send back a [=remote-playback-start-response=] message. It should do so quickly,
usually before the [=media resource=] has been loaded and instead give updates
of the progress of loading with [=remote-playback-state-event=] messages, unless
the receiver decides to not attempt to load the resource at all. If it chooses
not to, it must respond with the appropriate failure result (such as timeout or
invalid-url). Additionally, the response must include the following:
: state
:: The initial state of the remote playback, as defined in
[[#remote-playback-state-and-controls]].
If the controller wishes to modify the state of the remote playback (for
example, to pause, resume, skip, etc), it may send a
[=remote-playback-modify-request=] message with the following values:
: remote-playback-id
:: The ID of the remote playback to be modified.
: controls
:: Updated controls as defined in {#remote-playback-state-and-controls}
When a receiver receives a [=remote-playback-modify-request=] it should send a
[=remote-playback-modify-response=] message in reply with the following values:
: state
:: The updated state of the remote playback as defined in
[[#remote-playback-state-and-controls]].
When the state of remote playback changes without request for modification from
the controller (such as when the skips or pauses due to user user interaction on
the receiver), the receiver may send a [=remote-playback-state-event=] to the
controller.
: remote-playback-id
:: The ID of the remote playback whose state has changed.
: state
:: The updated state of the remote playback, as defined in
[[#remote-playback-state-and-controls]].