WebAPI/PresentationAPI:Protocol Draft: Difference between revisions

→‎Requirement: add data integrity
m (→‎Requirement: add protocol version)
(→‎Requirement: add data integrity)
 
(30 intermediate revisions by the same user not shown)
Line 3: Line 3:
== Requirement ==
== Requirement ==
* Device Discovery
* Device Discovery
** Device information: unique name, user-friendly name,  
** Device information: unique name, user-friendly name, address for ctrl server
** Device capability: resolution, supported media type, supported apps
** Device capability: resolution, supported media type, supported apps, supported IO capability
** Protocol information: protocol version
** Protocol information: protocol version
* Service Launching
* Service Launching
** Service information: app/page URL
** Service information: app/page URL
** Session information: session Id
** Session information: session Id, bootstrap info for communication
** Controlling message: launch, reconnect, terminate
** Controlling message: connect, disconnect, launch, close, reconnect, terminate
** User settings: preferred locale
** User settings: preferred locale
* Communication
* Communication
** establish dedicate transportation channel
** establish dedicate transportation channel
* Security
* Security
** device challenge
** device authentication: passcode verification + j-PAKE procedure
** data encryption
** data encryption: TLS for ctrl channel, DTLS for communication channel
** data integrity: provide HMAC for each ctrl message (except for query)


== Architecture ==
== Architecture ==
Here is the high-level architecture overview of 2-UAs protocol
[[File:2UAs_Protocol_Architecture_overview.png|thumb|650px|Architecture overview of 2-UAs Protocol]]


=== Controlling Page ===
* request a presentation session via PresentationRequest
* interact with Presented Content via PresentationConnection
=== Presented Content ===
* page loaded by Receiving User Agent for a presentation session
* interact with Controlling Page via PresentationConnection
=== Controlling User Agent ===
* display controlling page
* display pairing information and provide UI to resolve device challenge
=== Receiving User Agent ===
* display presented content
* generate challenge for pairing procedure
* display pairing information
=== PresentationControlClient ===
* query for available PresentationControlServer
* query device capability for device filtering
* initiate connection to server
* trigger session creation / reconnection / termination
* reply to device challenge during pairing procedure
=== PresentationControlServer ===
* register as an service profile on mDNS
* handle session creation / reconnection / termination
* generate auth token / cryptography key for pairing procedure
=== mDNS Query ===
* mDNS stack that supports service query over mDNS protocol
=== mDNS Registration ===
* mDNS stack that supports service registration over mDNS protocol
=== WebRTC ===
* WebRTC stack that provides Data Channel implementation
* Generate SDP for exchanging offer/answer over presentation control protocol


== Protocol Details ==
== Protocol Details ==
=== Launch ===
=== Service Discovery ===
* STEP 1: find device
* STEP 1: server registers itself as a mDNS service with service type = "_presentation-ctrl._tcp"
** STEP 1a: query device capability
* STEP 2: client starts a mDNS query for service type "_presentation-ctrl._tcp"
* STEP 2: setup control channel to remote device
* STEP 3: mDNS notifies a service instance is found with service profile provided
** STEP 2a: device challenge / device pairing
* STEP 4: establish control channel to server
* STEP 3: launch app / page
* STEP 5: send query command to server
* STEP 4: setup communication channel
* STEP 6: server sends query-reply command back to client, carrying detailed device capability
* STEP 5: close control channel
* STEP 7: client updates device profile to controlling user agent and closes control channel
 
[[File:Draft Protocol Service Discovery.png]]
 
=== Device Pairing ===
* STEP 1: server display a passcode and send challenge command to client, after receiving connect command
* STEP 2: client display passcode input and wait for user typing the same passcode
* STEP 3: client and server use the passcode to initiate J-PAKE procedure
** STEP 3a: client and server exchange the round 1 information
** STEP 3b: client and server exchange the round 2 information, and compute session key
* STEP 4: client send verify command with H(H(key)) to server
* STEP 5: server verify the H(H(key)) and send H(key) to client
* STEP 6: client and server can use key to encrypt following control message and provide H(key) as auth token.
[[File:Draft Protocol Device Pairing.png]]
 
=== Establish Control Channel ===
* server generates a self-signed certificate
* client establishes a TLS socket to the service port received during service discovery.
 
=== Close Control Channel ===
* STEP 1: send disconnect command with reason to remote device
* STEP 2: close TCP socket
[[File:Draft Protocol Close Control Channel.png]]
 
=== Start Presentation  ===
* STEP 1: controlling page initiate presentation via request.start()
* STEP 1a: controlling user agent initiate device selection
* STEP 2: setup control channel to server
* STEP 3: send connect command with device name, protocol version, supported challenge method
** STEP 3a: server initiate device challenge / device pairing procedure
* STEP 3: client send launch command with url, presentation Id (launch command should be encrypted and carried by encrypted-ctrl-msg)
* STEP 4: server launch corresponding presented content and send launch-ack command
* STEP 5: client setup communication channel via data channel establishment procedure
* STEP 6: client close control channel
[[File:Draft Protocol Start Presentation.png]]
 
=== Establish Data Channel ===
* STEP 1: client creates data channel and generates SDP as offer
* STEP 2: establish control channel to server
* STEP 3: send send-offer command with offer to server (send-offer command should be encrypted and carried by encrypted-ctrl-msg)
* STEP 4: server creates data channel, assigns the received SDP as remote description, and generates SDP as answer
* STEP 5: send send-answer command with answer to client (send-answer command should be encrypted and carried by encrypted-ctrl-msg)
* STEP 6: client assigns the received SDP as remote description
** STEP 6': client and server might generate more ICE candidate and exchange it via update-ice-candidate command (update-ice-candidate command should be encrypted and carried by encrypted-ctrl-msg)
* STEP 7: data channel is created via JSEP procedure
[[File:Draft Protocol Establish Data Channel.png]]
 
=== Terminate Presentation ===
* STEP 1: controlling page initiate presentation termination via connection.terminate()
* STEP 2: setup control channel to server
* STEP 3: send terminate command with presentation Id (terminate command should be encrypted and carried in encrypted-ctrl-msg command)
* STEP 4: receiving user agent close the presented content and close data channel
* STEP 5: server send terminate-ack to client (terminate-ack command should be encrypted and carried in encrypted-ctrl-msg command)
* STEP 6: client close control channel and notify onterminate event to controlling page
[[File:Draft Protocol Terminate Presentation.png]]


=== Terminate ===
=== Close Connection ===
* STEP 1: setup control channel to remote device
* STEP 1: controlling page initiate connection.close()
** STEP 1a: complete challenge with stored information
* STEP 2: sending close command to server, with closeReason = "closed"
* STEP 2: terminate app / page via session Id
* STEP 3: close data channel while receiving close command (close command should be encrypted and carry in encrypted-ctrl-msg command)
* STEP 3: close control channel
* STEP 4: notify onclose event to both controlling page and presented content
[[File:Draft Protocol Close Connection.png]]


=== Reconnect ===
=== Resume Connection ===
* STEP 1: setup control channel to remote device
* STEP 1: controlling page initiate connection resumption via request.reconnect();
** STEP 1a: complete challenge with stored information
* STEP 2: setup control channel to server
* STEP 2: reconnect app / page via session Id
* STEP 3: send reconnect command with presentation Id (reconnect command should be encrypted and carried in encrypted-ctrl-msg)
* STEP 3: setup communication channel
* STEP 4: setup communication channel following the Data Channel establish procedure
* STEP 4: close control channel
* STEP 5: close control channel
[[File:Draft Protocol Resume Connection.png]]


== References ==
== References ==
[https://github.com/mfoltzgoogle/freeplay/blob/master/architecture.md]
* [https://github.com/w3c/presentation-api/blob/gh-pages/interoperability.md Protocol suggestion by Second Screen WG]
[https://github.com/w3c/presentation-api/blob/gh-pages/interoperability.md]
* [https://github.com/mfoltzgoogle/freeplay/blob/master/architecture.md Architecture proposed by Google]
Confirmed users
216

edits