WebAPI/PresentationAPI:Protocol Draft

From MozillaWiki
Jump to: navigation, search

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

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

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.

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

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

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

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

Draft Protocol Terminate Presentation.png

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

Draft Protocol Close Connection.png

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

Draft Protocol Resume Connection.png

References