WebAPI/PresentationAPI:Protocol Draft
From MozillaWiki
< WebAPI
This is a draft of protocol proposal for 2-UAs Presentation Scenario
Requirement
- Device Discovery
- Device information: unique name, user-friendly name, address for ctrl server
- Device capability: resolution, supported media type, supported apps, supported IO capability
- Protocol information: protocol version
- Service Launching
- Service information: app/page URL
- Session information: session Id, bootstrap info for communication
- Controlling message: connect, disconnect, launch, close, reconnect, terminate
- User settings: preferred locale
- Communication
- establish dedicate transportation channel
- Security
- device authentication: passcode verification + j-PAKE procedure
- data encryption: TLS for ctrl channel, DTLS for communication channel
- data integrity: provide HMAC for each ctrl message (except for query)
Architecture
Here is the high-level 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
Service Discovery
- STEP 1: server registers itself as a mDNS service with service type = "_presentation-ctrl._tcp"
- STEP 2: client starts a mDNS query for service type "_presentation-ctrl._tcp"
- STEP 3: mDNS notifies a service instance is found with service profile provided
- STEP 4: establish control channel to server
- STEP 5: send query command to server
- STEP 6: server sends query-reply command back to client, carrying detailed device capability
- STEP 7: client updates device profile to controlling user agent and closes control channel
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.
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
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
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
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
Close Connection
- STEP 1: controlling page initiate connection.close()
- STEP 2: sending close command to server, with closeReason = "closed"
- STEP 3: close data channel while receiving close command (close command should be encrypted and carry in encrypted-ctrl-msg command)
- STEP 4: notify onclose event to both controlling page and presented content
Resume Connection
- STEP 1: controlling page initiate connection resumption via request.reconnect();
- STEP 2: setup control channel to server
- STEP 3: send reconnect command with presentation Id (reconnect command should be encrypted and carried in encrypted-ctrl-msg)
- STEP 4: setup communication channel following the Data Channel establish procedure
- STEP 5: close control channel
