Services/KeyExchange

Overview

Explore using J-PAKE to securely pass credentials to another device.

Tracking bug is bug 601644.

Engineers Involved

• Tarek (server)
• Philipp (FxSync)
• Stefan (FxHome)

User Requirements

• Setting up a new mobile device should only involve entering a short code on the desktop device
• Secondary request, not a hard requirement, is that if the user has a mobile device, and is setting up a desktop device, that the flow is similar and still involves entering the key on the desktop

Desired User Flow

1. User chooses "quick setup" on new device
2. Device displays a setup key that contains both the initial secret and a channel ID
3. On a device that is authenticated, user chooses "add another device" and is prompted for that key
4. The two devices exchange messages to build the secure tunnel
5. The already-authenticated device passes all credentials (username/password/passphrase) to the new device
6. New device completes setup and starts syncing

Implementation (draft)

Terminology

• Desktop: Client that has Fx Sync already set up
• Mobile: Client that needs to be set up (of course this could be another desktop computer, too)
• PIN: code that is displayed on Mobile and entered on Desktop
• Secret: weak secret that is used to start the J-PAKE algorithm
• Key: strong secret that both clients derive through J-PAKE

Flow

1. Mobile asks server for new channel ID (3 characters a-z0-9)

   C: GET /new_channel HTTP/1.1
   S: "a7i"

2. Mobile generates PIN from channel ID + random weak secret (3 characters a-z0-9), computes and uploads J-PAKE msg 1

   C: PUT /a7i HTTP/1.1
   C: 
   C: {"type": "client1-msg1", XXX}
   
   S: HTTP/1.1 200 OK
   S: ETag: "444b424cbc84805b40bcd35c8ebe4524"
   

3. Desktop asks user for the PIN, extracts channel ID and weak secret, fetches Mobile's msg 1

   C: GET /a7i HTTP/1.1
   
   S: HTTP/1.1 200 OK
   ...
   

4. Desktop computes and uploads msg 1

   C: PUT /a7i HTTP/1.1
   C: 
   C: {"type": "client2-msg1", XXX}
   
   S: HTTP/1.1 200 OK
   S: Etag: "209a424cbc8480465abcd35c8ebe4524"
   

5. Mobile polls for Desktop's msg 1

   C: GET /a7i HTTP/1.1
   C: If-None-Match: "444b424cbc84805b40bcd35c8ebe4524"
   
   S: HTTP/1.1 304 Not Modified
   

   Mobile tries again after 1s

   C: GET /a7i HTTP/1.1
   C: If-None-Match: "444b424cbc84805b40bcd35c8ebe4524"
   
   S: HTTP/1.1 200 OK
   ...
   

   Mobile computes and uploads msg 2

   C: PUT /a7i HTTP/1.1
   C: 
   C: {"type": "client1-msg2", XXX}
   
   S: HTTP/1.1 200 OK
   S: ETag: "111a424cbc8480465abcd35c8ebe4524"
   

6. Desktop polls for and eventually retrieves Mobile's msg 2

   C: GET /a7i HTTP/1.1
   C: If-None-Match: "209a424cbc8480465abcd35c8ebe4524"
   
   S: HTTP/1.1 200 OK
   ...
   

   computes key, computes and uploads msg 2

   C: PUT /a7i HTTP/1.1
   C: 
   C: {"type": "client2-msg2", XXX}
   

7. Mobile retrieves Desktop's msg 2

   C: GET /a7i HTTP/1.1
   C: 
   
   S: HTTP/1.1 200 OK
   ...
   

   computes key, uploads hash of key to prove its knowledge (msg 3)

   C: PUT /a7i HTTP/1.1
   C: 
   C: {"type": "client1-msg3", XXX}
   

8. Desktop retrieves Mobile's msg 3 (hashed key)

   C: GET /a7i HTTP/1.1
   C: 
   
   S: HTTP/1.1 200 OK
   ...
   

   verifies it against its own version. If the hash matches, it encrypts and uploads Sync credentials.

   C: PUT /a7i HTTP/1.1
   C: 
   C: {"type": "client2-msg3", XXX}
   

9. Mobile retrieves encrypted credentials

   C: GET /a7i HTTP/1.1
   C: If-None-Match: "111a424cbc8480465abcd35c8ebe4524"
   
   S: HTTP/1.1 200 OK
   ... 
   

   decrypts Sync credentials and verifies HMAC.

10. Mobile deletes the session [OPTIONAL]

    C: DELETE /a7i HTTP/1.1
    
    S: HTTP/1.1 200 OK
    ... 
    

Security Considerations

Discuss potential design and implementation threats & mitigations here.