Skip to content

Latest commit

 

History

History
50 lines (36 loc) · 2.17 KB

totp-pairing-flow.md

File metadata and controls

50 lines (36 loc) · 2.17 KB
Raw

TOTP Pairing Flow

Diagram

Here is a simple flow chart using mermaid:

sequenceDiagram
 autonumber
    actor User
    participant MME as MetaMask-Extension (MME)
    participant MMD as MetaMask-Desktop (MMD)
    User->>MME: "Enable Desktop App" button clicked
        MME->>MMD: start a limited connection
        activate MMD
        Note over MME,MMD: - Create WebSocket<br/>- Encrypt Stream<br/>- Perform Handshake
        MMD->>MME: return connection established
        deactivate MMD
        Note over MME: Generates TOTP
    MME->>User: display Pairing Page to the user
    User->>MMD: submit TOTP (6 digits) displayed in the MME
    Note over MME: - Validate TOTP<br/>- Create Pairing Key
    Note over MME: - Save the pairing key hash<br/>- Enable desktop app
    MME->>MMD: send pairing key
    MMD->>MMD: save pairing key<br>enable desktop
    MME->>MMD: transfer/sync state
    Note over MME: Restart to run the background<br> process in the MMD
Loading

Overview

All starts on the MetaMask extension side whenever a user clicks Enable Desktop App in Settings>Experimental.

The MetaMask extension connects with MetaMask Desktop via a WebSocket. Once the streams are created and the handshake is completed, a 6 digit TOTP is displayed.

The SHA1 based TOTP is refreshed every 30 seconds and is generated by OTPAuth.

Every 5 TOTP attempts the secret is renewed.

After the user enters the 6 digits and the TOTP is validated by the MetaMask extension:

  • A pairing key is generated and sent to MetaMask Desktop.
  • Desktop mode is enabled in the extension.
  • The hash of the pairing key is saved in the extension state.

Once the pairing is completed, whenever a new connection occurs, the extension waits for the desktop pairing key, hashes it, and checks if it matches the stored hash before establishing the authorised connection and transferring the current MetaMask state.

Once the authorised connection is active, the state is continuously synchronised between MetaMask Desktop and the MetaMask extension whenever the persisted state is updated.