Specification

Joachim Neumann edited this page Jul 16, 2018 · 10 revisions

Bisq Remote

Introduction

Bisq users with an open trade need to keep Bisq running on their computer, but might be afk. This Bisq proposal aims at providing a iOS and Android App that can receive notifications from the Bisq desktop app. In the first version, the mobile iOS and Android Apps only receive notifications. In a later version the mobile apps might also remotely control the users' Bisq desktop app. The first version uses push notifications that do not require that the mobile is running.

Architecture

# Note: Version 1 only supports iOS and Android Push Notification Service. The architecture needs to be revised for version 2 (notifications over Tor). architecture

Figure 1: Data flow for the Bisq remote App In phase 1, using the Apple or Google push notification service. The notifications are sent from the Bisq desktop app to a Bisq notification node that acts as proxy to the Apple/Google Push Notification Service.(modify image)

Signal flow - Registering the phone

The registration of the phone should be as easy as possible. An encryption key and a notification token need to be exchanged. The only possibility to do this in one step is if the phone created the encryption ken and then transfers it together with the token which the phone gets from Apple or Google to the Bisq desktop app: setup

Figure 2: signal from during setup(modify image)

Steps:

  1. The mobile App registers with the Apple or Google notification service and receives a notification token. This happens in the background without any user interaction. At this moment, the mobile app also creates the encryption key.
  2. The App instructs the user to start the Bisq desktop app and open the the menu item “Bisq remote” (This is currently not implemented in the Bisq desktop app).
  3. The user registers the phone with the Bisq desktop app by transferring the key and the token.
    • Method 1: A QR code with the Pairing token is created on the phone and scanned by the camera of the computer
    • Method 2: The user sends an email with the Pairing token from his phone to himself. On the computer he copies the Pairing token into the Bisq desktop app.
      When the Pairing token is valid in the Bisq desktop app, a confirmation notification is automatically sent to the phone. No further user interaction is needed for the setup / registration
  4. Bisq should allow the user to
    • Add a new phone.
    • Remove phones that should no longer receive Bisq notifications.

Pairing token

The Pairing token consists of four parts which are separated by the "|" character:

  1. A Magic, currently one of iOS, iOSDev or android
  2. A Phone descriptor, e.g., iPhone6
  3. A 32 byte cryptographic key for symmetric encryption. This key is generated by the phone and used in the Bisq desktop app to encrypt the content of the notification.
  4. A Notification token, either from Apple or from Google.

Example:

BisqPhoneAndroid|
iPhone6|
f89e5160b3634ee6b51995e06af3e33e|
cEcb7vlj_SE:APA91bFYGqp_wsNv1OLHE3AeqUySkdUiNeuPv5yF
mgGuOWqEMVycQrwPom8oq1iFNPbp7raLbPxC4cxW99yFmhH8fiey
M2kXCyQxAG_y73hBha-TgtwR9r3MpQ852fljTVjw6zlOLD8t6Ufh
Qkx81lvhyaSLe2Q

Signal flow - Notification

notification

Figure 3: Signal flow during usage: a notification is sent from the desktop app to the phone (modify image)

Steps:

  1. The Bisq desktop app sends a notification to the Bisq notification node. The notification consists of the notification token and the encrypted message. (Tor)
  2. The Bisq notification node forwards the encrypted message to the Apple or Google Push Notification Service using the Notification token. (HTTP)
  3. The Apple/Google Push Notification service sends the notification to the iOS/Android device. (HTTP)
  4. The phone notifies the user of a new Bisq message without displaying the content of the message.
  5. When the user opens the mobile Bisq remote App, it displays the decrypted notification payload.

Apple Push Notification Service

The Apple Push Notification Service has the advantage that the notifications reach the iOS device even if the Bisq remote App is not currently running. This convenience comes at the price that Apple knows when Bisq related notification are sent to the Bisq user. However, since the notifications are encrypted, Apple does not know the content of the message. The maximum notification payload size is 4 kilobytes (HTTP/2 API).

The pairing token contains a magic that allows distinguished between the production and development server:

iOS    --> api.push.apple.com  
iOSDev --> api.development.push.apple.com  

Google Push Notification Service

We use firebase.google.com

Bisq notification node

The Bisq notification node acts as a proxy. This has the benefit that the Apple/Google certificate which is required to forward notifications to the Push Notification Service is not public. This makes it difficult to spam the Bisq notification node with the aim to have Apple or Google block Bisq notifications.
The Bisq notification node will be based on three components

  1. A Server for the Apple or Google Push Notification service.
  2. A P2P network layer that allows to communicate to the Bisq nodes over Tor.
  3. An Apple or Google Certificate. Both are linked to a paid developer account.

Cryptography

We use the 128 bit AES/CBC/PKCS5Padding symmetric encryption algorithm. A fresh 16-character Initialization Vector is created for each notification. This Initialization Vector is be attached to the notification.

Notification Payload

The notification payload contains an encrypted JSON string the describes the following object (in pseudo-code):

class BisqNotificationObject {  
    String timestampEvent  
    String transactionID  
    String title  
    String message  
    String notificationType  
    String actionRequired  
    int version  
}

Specifically, the payload has three parts:

  1. A magic (BisqMessageiOS or BisqMessageAndroid)
  2. The 16-character Initialization Vector used in the encryption
  3. the encrypted message

Example:

BisqMessageiOS|
906aabd2d32f40d0|
0msuhNaWOSpIxL4/64kS8qjTc+tqmZ1wH9HLtfAUc4xNOZRVFAPX
JQ9gNoSfyZHN4oGbaefnjj6ym730d8hxkKXQB9F9vfmbtZk91Qr8
R+Qgu4AwzXMD39APacIIUXbsLnej0B461DQLcFnJA7kIhitEZov9
91Mhjo4CEnuA6VZOfcj/VvcGy0+mzxpTlsh8gy73+uyciNXq26Ew
7IlLo5GFpbTU3ku1yxmhM4SJNvEbJ0qt3L/smCNv3GgihNUz

Notification parameter

The Bisq Desktop allows to configure if the notifications sound an alarm when a notification arrived while the mobile app is in background.

Badge

The red badge on the app icon -- e.g., (1) -- is a bit complicated. The correct design is to send the badge number with the notification. However, this requires the Bisq notification server to count and manage the number of unread notifications. Instead the mobile app sets the badge number. As a side-effect the badge number is not increased by iOS when the mobile app receives a notification while being in background.

List of valid values for the field notificationType:

Type example message What happens in the phone
TRADE Your offer has been accepted / trade completed, etc. normal notification
DISPUTE Your bank transfer did not arrive Warning notification
FINANCIAL An offer over x $ has been made financial notification
SETUP_CONFIRMATION (no message) setup terminated
ERASE (no message) erases all settings and and all notifications

Open Source and replicating the functionality

The two mobile Apps and the Bisq notification node are open source, using the AGPL license. A user that wants to compile and run the mobile Apps himself and receive notifications, would need to set up hos own Bisq notification node, because he needs the certifications files from Apple / Google.

Specification of mobile Apps

Screens

flow setup

Picture 1: Screens of the mobile iOS and Android App, here: the iOS Storyboard

The App has three screens:

  1. A list of notifications
  2. A Notification Detail View
  3. A Settings Screen

Registration

flow

Picture 1: Registration Screens of the mobile iOS and Android App, here: the iOS Storyboard

The registration screens only need to be executed once:

  1. Welcome screen
  2. Instructions for registration
  3. Registration with QR code or email

Roadmap

Version 1

  • Simple Notifications using the Push notifications
  • Encrypted notification payload
  • Android and iOS Apps
  • Iterations on User Experience and Graphic Design
  • Testing

Version 2

  • Support for Tor data exchange
  • Notifications from the mobile App to Bisq (“the fiat money has arrived on my account, the trade can be finalised”)
  • Price alerts for attractive offers
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.