MozillaWiki

Firefox OS/Remote Control: Difference between revisions

Page Discussion

Firefox OS/Remote Control (view source)

Revision as of 03:39, 24 May 2016

1,550 bytes removed ,  24 May 2016
→‎Architecture Designs: add disconnect and reconnection description
(Re-authentication)
(→‎Architecture Designs: add disconnect and reconnection description)
 
(12 intermediate revisions by the same user not shown)
Line 22: Line 22:
# Peer authentication
# Peer authentication
# Control event processing
# Control event processing
Any error occurs will close connection between server and client, reconnection is required. Server side error will sends message back to client to let user know what happen on Fennec.


=== Peer authentication ===
=== Peer authentication ===
Line 33: Line 35:
# Client computes J-PAKE round 1 and sends the result to server.
# Client computes J-PAKE round 1 and sends the result to server.
# Server generates PIN code and show on screen, computes J-PAKE round 1 and sends the result to client.
# Server generates PIN code and show on screen, computes J-PAKE round 1 and sends the result to client.
# Server computes J-PAKE round 2 with PIN code attached first 12 characters as weak secret.
# User enter PIN code, client computs J-PAKE round 2 with PIN code attached first 12 characters of server's TLS certificate fingerprint as weak secret.
# User enter PIN code, client computs J-PAKE round 2 with PIN code attached first 12 characters as weak secret.
# Client sends round 2 result to server.
# Client sends round 2 result to server.
# Server computes J-PAKE round 2 with PIN code attached first 12 characters of server's TLS certificate fingerprint as weak secret.
# Server dismisses PIN code notification on screen, sends round 2 result to client.
# Server dismisses PIN code notification on screen, sends round 2 result to client.
# Both client and server compute J-PAKE final round, gets AES and HMAC key.
# Both client and server compute J-PAKE final round, gets AES and HMAC key.
Line 54: Line 56:
# Client computes J-PAKE round 1 and sends the result to server.
# Client computes J-PAKE round 1 and sends the result to server.
# Server computes J-PAKE round 1 and sends the result to client.
# Server computes J-PAKE round 1 and sends the result to client.
# Client and server computes J-PAKE round 2 with previous AES key value as weak secret.
# Client and server computes J-PAKE round 2 with first 4 characters of previous AES key value attached first 12 characters of server's TLS certificate fingerprint as weak secret.
# Client sends round 2 result to server.
# Client sends round 2 result to server.
# Server sends round 2 result to client.
# Server sends round 2 result to client.
Line 67: Line 69:


=== Control event processing ===
=== Control event processing ===
Control page provides: 1) a virtual touchpad, 2) a virtual vertical scrollbar, 3) 3 function keys. Every touch, swipe or click will be generated to an event in JSON format, encrypted and send to TV. Following describes how control event is sent and processed:
Control page provides: 1) a virtual touchpad, 2) a virtual vertical scrollbar, 3) 3 function keys. Every touch, swipe or click will be generated to an event in JSON format then send to TV. Following describes how control event is sent and processed:


[[File:RemoteControl ControlEventProcessing.png]]
[[File:RemoteControl ControlEventProcessing.png]]


# User opens the URL.
# Client requests page with UUID can access control page.
# Server returns client.html as requested page for remote control.
# User operates control page.
# User operates control page.
# Client generates an event and encrypts the event using symmetric key. [https://github.com/luke-chang/gaia/blob/1228262_tv_remote_control_secure/tv_apps/remote-control-client/js/client.js#L33 source]
# Client generates and sends the event in JSON format.
# Client sends encrypted event.
# Server parses the event to JSON object, dispatch to client.sjs.
# Client.sjs responses with latest event result.
# Client.sjs decrypts event with symmetric key received in establish secure connection. [https://github.com/MDTsai/gecko-dev/blob/Bug_1235013_new_httpserver/b2g/remotecontrol/client.sjs#L474 source]
# Client.sjs parses event and dispatch to Gecko or Gaia system app.
# Client.sjs parses event and dispatch to Gecko or Gaia system app.


=== Data encryption/decryption ===
=== Data used in JPAKE authentication ===
There are three kinds of data are encrypted while tranmission:
==== Singer ID for JPAKE round 1 & 2: ====
# Client polls '''UUID''' in establish secure connection stage
* TV: server
# Client sends '''PIN code''' in pin code pairing
* Fennec addon: client
# Client sends '''event''' in control event processing
 
==== Weak secret: ====
* TV: concatenate PIN and first 12 characters of TLS server cert SHA 256 fingerprint
* Fennec addon: concatenate user input PIN and first 12 characters connected TLS server cert SHA 256 fingerprint
 
==== HMAC Input for JAPKE final: ====
We use "AES_256_CBC-HMAC256", as aHkdfInfo, includes the full crypto spec, should be the same in both TV and fennec addon
 
==== Key confirmation: ====


As data are encrypted by symmetric key, AES-GCM, there are two things need noticed:
Double hash of AES key:
# AES-GCM need initialization vector(IV) to encrypt/decrypt. Currently, IV is random value for each data, length is 12 bytes. Encrypted data is appended after IV. Receiver needs to slice first 12 bytes as IV to decrypt.
## TV converts AES key to array buffer
# Each message type is string, use [https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder/encode TextEncoder.encode()] to encode as an UInt8Array, then encrypt to ArrayBuffer. Vice versa.
## Sign AES key array buffer, get signature 1 (array buffer)
# Data encryption/decryption is asynchronous but HTTP request need response immediately. For UUID and PIN code case, remote control uses a ticket number to get status after decryption. But for event, we reduce polling result but use latest event's result instead.
## Sign signature 1, get signature 2
## Convert signature 2 to base 64, send to Fennec addon
## Fennec addon do the same as TV from step 1 to 4
## Compare received base 64 string of self and TV's signature 2


=== Ajax Protocol ===
Single hash of AES key:
==== RSA public key exchange ====
## Fennec addon converts AES key to array buffer
Request
## Sign AES key array buffer, get signature 1 (array buffer)
  {
## Convert signature 1 to base 64, send to TV
    action: 'require-public-key'
## TV use HMAC key, received signature, AES key array buffer to verify if the signature is valid.
  }
Response
  {
    publicKey: <RSA-OEAP SPKI in base64>
  }
  {
    error: <reason>
  }


==== Send symmetric key ====
=== Authentication and Event Protocol ===
==== Request handshake ====
Request
Request
   {
   {
     action: 'send-symmetric-key',
    type: 'auth'
     wrappedSymmetricKey: <AES-GCM wrapped by RSA-OEAP in base64>
     action: 'request_handshake'
     detail: {
      id: <id assigned by server, optional>
    }
   }
   }
Response
Response
   {
   {
     ticket: <ticket>
     type: 'auth'
  }
    action: 'response_handshake'
  {
     detail: 1 or 2, 1 for 1st handshake, 2 for 2nd handshake
     error: <reason>
   }
   }


==== Poll UUID ====
==== J-PAKE key exchange ====
Request
Client send round 1
   {
   {
     action: 'poll-uuid'
    type: 'auth'
     ticket: <ticket>
     action: 'jpake_client_1',
     detail: {
      gx1: gx1.value,
      gx2: gx2.value,
      zkp_x1: { gr: gv1.value, b: r1.value, id: 'client' },
      zkp_x2: { gr: gv2.value, b: r2.value, id: 'client' }
    }
   }
   }
Response
Server reply round 1
   {
   {
     done: true,
     type: 'auth'
     encryptedUUID: <IV + UUID encrypted by AES-GCM, in base64>,
    action: 'jpake_server_1',
     detail: {
      gx1: gx1.value,
      gx2: gx2.value,
      zkp_x1: { gr: gv1.value, b: r1.value, id: 'server' },
      zkp_x2: { gr: gv2.value, b: r2.value, id: 'server' }
    }
   }
   }
Client send round 2
   {
   {
     done: true,
     type: 'auth'
     error: <reason>
    action: 'jpake_client_2',
     detail: {
      A: A.value,
      zkp_A: { gr: gvA.value, b: rA.value, id: 'client' }
    }
   }
   }
Server reply round 2
   {
   {
     done: false // Symmetic key unwrapping or encrypting UUID
     type: 'auth'
    action: 'jpake_server_2',
    detail: {
      A: A.value,
      zkp_A: { gr: gvA.value, b: rA.value, id: 'server' }
    }
   }
   }


==== Pair PIN code ====
==== Key confirmation ====
Request
Server key confirmation
   {
   {
     action: 'pair-pincode'
    type: 'auth'
     encryptedPIN: <IV + PIN encrypted by AES-GCM in base64>
     action: 'server_key_confirm'
     detail: {
      signature: <double signature of AES key by HMAC key, in base64>
    }
   }
   }
Response
Client key confirmation
   {
   {
     ticket: <ticket>
     type: 'auth'
  }
     action: 'client_key_confirmation'
 
     detail: {
==== Poll pair result ====
      signature: <signature of AES key by HMAC key, in base64>
Request
    }
  {
     action: 'poll-pair-result'
     ticket: <ticket>
   }
   }
Response
Server finish handshake
   {
   {
     done: true
     type: 'auth'
     verified: <boolean>
     action: 'finish_handshake'
     reason: <reason>
     detail: {
  }
      id: <id assigned by server, optional>
  {
     }
    done: false
  }
==== Encrypted control events ====
Client sends encrypted event in query string as:
  <IP_Address>:<Port>?message=<IV + encrypted event by AES-GCM in base64>
 
Response
  {
     verified: <boolean>
   }
   }
After decrypted, following are control events:


==== Touch Events ====
==== Touch Events ====


   {
   {
     type: 'touchstart',
     type: 'command'
    action: 'touchstart',
     detail: {
     detail: {
       width: <touch panel width, integer, in pixels>,
       width: <touch panel width, integer, in pixels>,
Line 187: Line 204:


   {
   {
     type: 'touchmove',
     type: 'command'
    action: 'touchmove',
     detail: {
     detail: {
       dx: <dx between current point and starting point, integer, in pixels>,
       dx: <dx between current point and starting point, integer, in pixels>,
Line 197: Line 215:


   {
   {
     type: 'touchend',
     type: 'command'
    action: 'touchend',
     detail: {
     detail: {
       dx: <same as "touchmove">,
       dx: <same as "touchmove">,
Line 214: Line 233:


   {
   {
     type: 'keypress',
     type: 'command'
    action: 'keypress',
     detail: <KeyEvent constant, string, sush as "DOM_VK_RETURN">
     detail: <KeyEvent constant, string, sush as "DOM_VK_RETURN">
   }
   }
Line 221: Line 241:


   {
   {
     type: 'textinput',
     type: 'command'
    action: 'textinput',
     detail: {
     detail: {
       clear: <whether to clear the entire string in the current focused input field, boolean>,
       clear: <whether to clear the entire string in the current focused input field, boolean>,
Line 229: Line 250:
   }
   }


==== Custom Events ====
==== Server reply error ====


   {
   {
     type: 'custom',
     type: common, or the event type sent from client
     detail: {
     error: <error message of exception or root cause>
      action: <custom action name, string>,
      ...
    }
   }
   }
=== Pairing (Full version, without secure connection) ===
Meta Bug: {{Bug|1207996}}
==== Flowchart ====
First Time Connection (deprecated in secure connection)
[[File: RemoteControl FirstConnect.png]]
Enter PIN Code (deprecated in secure connection)
[[File:RemoteControl EnterPIN.png]]
Resume Connection (deprecated in secure connection)
[[File:RemoteControl ResumeConnection.png]]
Dismiss Pairing
[[File:RemoteControl DismissPairing.png]]
==== Protocol ====
from client to server via AJAX (deprecated in secure connection)
  {
    pincode: <pincode>
  }
response when success (deprecated in secure connection)
  {
    verified: true,
    uuid: <uuid>
  }
reponse when error
  {
    verified: false,
    reason: 'expired' / 'invalid'
  }
internal events at server side
  {
    type: 'mozChromeRemoteControlEvent',
    detail: {
      action: 'pin-created',
      pincode: <pincode>
    }
  }
  {
    type: 'mozChromeRemoteControlEvent',
    detail: {
      action: 'pin-destroyed'
    }
  }
  {
    type: 'mozContentEvent',
    detail: {
      type: 'remote-control-pin-dismissed',
      detail: {
        reason: 'timeout' / 'manually'
      }
    }
  }
=== Secure Connection (deprecated) ===
To protect private data between user and TV, we provide a secure connection which refers to SSL and [http://www.jcryption.org/ jCryption]. Here is the concept:
# Client requests RSA public key from TV.
# Client sends symmetric key and PIN code (if any) to TV, encrypted with public key.
# TV decrypts symmetric key with private key
# TV generates an UUID, encrypts with symmetric key then sends 2 UUIDs to client, one is encrypted the other is not.
# Client decrypts UUID with symmetric key, confirm UUID
# Begin remote control with symmetric key.
Goal of Remote Control is to create an easy to use way for every device, we hide public key exchange at the background. User doesn't need to input a long URL with public key nor scan QRCode. Everything is done automatically without interrupting user experience.
[[File: Remote_Security.png]]


== Bug Status ==
== Bug Status ==
Eric Tsai
133

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/1128024...1133983"