NOTE: Historical document. Doesn't correspond to actual implementation of Push Notifications as of October 26, 2017. Originally wrritten by Victor Spring 2017 (ish). — oskarth

Overview

It is crucial to understand what is Whisper Notification Service is designed for:

• to augment Whisper/5 functionality, by allowing clients to subscribe to arbitrary node that has service enabled
• once subscribed, client receives randomly generated symmetric key (SubscriptionKey), which is used to control subscription (say, querying for server id or generating chat keys).
• using SubscriptionKey, new chat sessions can be initiated (yielding yet another SymKey - ChatKey). By sharing that key with others, you will have a common secret that can be used to trigger notifications.
• everywhere possible, Whisper protocol itself was used. For example, discovery mechanism is nothing more but Whisper message exchanges between parties. The same goes for notification sending. The aim was to keep the Service as slim as possible.

High-Level Overview of the process

The crux here is how to allow DeviceB to trigger notifications on DeviceA, all this w/o knowing much of which wnode is used, or details of DeviceA. And Chat SymKey solves this issue elegantly (the beauty is that it works for both one-on-one and group chats, all you need to ensure is share a secret, namely Chat SymKey, so that newcomers can add their devices to subscribers list).

Important Notes:

• Device A starts the protocol by sending encrypted message using Discovery Protocol PubKey (Status test cluster will have a single PubKey installed on all the nodes, allowing any of them to respond on discovery requests).
• While discovery happens using asymmetric cryptography, once you obtain Subscription SymKey and Chat SymKey you rely on symmetric encryption.
• It is important to understand that notification request messages go along the normal communication i.e.
  • on DeviceA you send encrypted message to DeviceB (so, only DeviceB can open envelope)
  • once done, you need to send a broadcast message encrypting it with Chat SymKey
  • some node over there, will be able to decrypt your broadcast (the only one that has Chat SymKey)
  • once decrypted, wnode will go over list of device IDs previously registered for this Chat, and send notifications requests to FCM using those IDs (only 1 request for one-on-one chats, n-1 requests for group of n chats - that's we do not notify ourselves)
• So, messages are never exposed, and they are routed in parallel. Notifications are also encrypted (by Chat SymKey), so are not exposed to eavesdropper either. This means we are not compromising on darkness. The following info gets exposed though:
  • by registering device ID with a given chat session we expose it to wnode
  • we expose our PubKeys (wnodes need message to be signed, so that you PubKey can be filtered out, and notification by you towards yourself is avoided)
  • we may expose some critical information in body of notification message (highly not advised!).

Communication Protocol

⭐️ ⭐️ ⭐️ The code below is outdated (it was written for Geth 1.5.9, and with Geth 1.6.0 Whisper API changed drastically). It is still advised to skim over the code and comments, to get better understanding of the idea. And at the end of this document, we include full-fledged test suite (to be run with Mocha).

Suppose, you started service node(s) using statusd --datadir wnode1 wnode --notify --identity ./wnodekey --firebaseauth ./firebaseuathkey, where wnodekey and firebaseauthkey files contain node's private key and FCM authorization key respectively. Now, your server is ready to receive requests encrypted with its PubKey, which for our cluster is 0x040edb0d71a3dbe928e154fcb696ffbda359b153a90efc2b46f0043ce9f5dbe55b77b9328fd841a1db5273758624afadd5b39638d4c35b36b3a96e1a586c1b4c2a.

On client side, we need to use protocol PubKey and pre-defined topic:

var protocolKey = '0x040edb0d71a3dbe928e154fcb696ffbda359b153a90efc2b46f0043ce9f5dbe55b77b9328fd841a1db5273758624afadd5b39638d4c35b36b3a96e1a586c1b4c2a';
var sendDiscoveryRequest = function (identity) {
    // notification server discovery request is a signed (sent from us),
    // encrypted with Notification Protocol Asymmetric (Public) Key
    var err = web3.shh.post({
        from: identity,
        to: protocolKey,
        topics: [discoverServerTopic],
        ttl: 20
    });
    if (err !== null) {
        console.log("message NOT sent")
    } else {
        console.log("message sent OK")
    }
};