Merge pull request #159 from pusher/e2e-encryption

E2e encryption

Author: Callum Oakley

.travis.yml

@@ -1,3 +1,6 @@
+before_install:
+  - sudo apt-get -y install libsodium18
+
 language: ruby
 sudo: false
 rvm:

CHANGELOG.md

@@ -1,3 +1,8 @@
+HEAD  / 2020-09-29
+==================
+
+  * Support for end-to-end encryption.
+
 1.3.3 / 2019-07-02
 ==================
 

README.md

@@ -248,5 +248,51 @@ else
 end
 ```
 
+### End-to-end encryption
+
+This library supports [end-to-end encrypted channels](https://pusher.com/docs/channels/using_channels/encrypted-channels). This means that only you and your connected clients will be able to read your messages. Pusher cannot decrypt them. You can enable this feature by following these steps:
+
+1. Install [Libsodium](https://github.com/jedisct1/libsodium), which we rely on to do the heavy lifting. [Follow the installation instructions for your platform.](https://github.com/RubyCrypto/rbnacl/wiki/Installing-libsodium)
+
+2. Encrypted channel subscriptions must be authenticated in the exact same way as private channels. You should therefore [create an authentication endpoint on your server](https://pusher.com/docs/authenticating_users).
+
+3. Next, generate your 32 byte master encryption key, encode it as base64 and pass it to the Pusher constructor.
+
+   This is secret and you should never share this with anyone.
+   Not even Pusher.
+
+   ```bash
+   openssl rand -base64 32
+   ```
+
+   ```rb
+   pusher = new Pusher::Client.new({
+     app_id: 'your-app-id',
+     key: 'your-app-key',
+     secret: 'your-app-secret',
+     cluster: 'your-app-cluster',
+     use_tls: true
+     encryption_master_key_base64: '<KEY GENERATED BY PREVIOUS COMMAND>',
+   });
+   ```
+
+4. Channels where you wish to use end-to-end encryption should be prefixed with `private-encrypted-`.
+
+5. Subscribe to these channels in your client, and you're done! You can verify it is working by checking out the debug console on the [https://dashboard.pusher.com/](dashboard) and seeing the scrambled ciphertext.
+
+**Important note: This will __not__ encrypt messages on channels that are not prefixed by `private-encrypted-`.**
+
+**Limitation**: you cannot trigger a single event on multiple channels in a call to `trigger`, e.g.
+
+```rb
+pusher.trigger(
+  ['channel-1', 'private-encrypted-channel-2'],
+  'test_event',
+  { message: 'hello world' },
+)
+```
+
+Rationale: the methods in this library map directly to individual Channels HTTP API requests. If we allowed triggering a single event on multiple channels (some encrypted, some unencrypted), then it would require two API requests: one where the event is encrypted to the encrypted channels, and one where the event is unencrypted for unencrypted channels.
+
 ## Supported Ruby versions
 2.4+

lib/pusher/client.rb

@@ -1,8 +1,10 @@
+require 'base64'
+
 require 'pusher-signature'
 
 module Pusher
   class Client
-    attr_accessor :scheme, :host, :port, :app_id, :key, :secret, :notification_host, :notification_scheme
+    attr_accessor :scheme, :host, :port, :app_id, :key, :secret, :notification_host, :notification_scheme, :encryption_master_key
     attr_reader :http_proxy, :proxy
     attr_writer :connect_timeout, :send_timeout, :receive_timeout,
                 :keep_alive_timeout
@@ -55,6 +57,11 @@ def initialize(options = {})
           :scheme, :host, :port, :app_id, :key, :secret, :notification_host, :notification_scheme
         )
 
+      if options.has_key?(:encryption_master_key_base64)
+        @encryption_master_key =
+          Base64.decode64(options[:encryption_master_key_base64])
+      end
+
       @http_proxy = nil
       self.http_proxy = options[:http_proxy] if options[:http_proxy]
 
@@ -138,6 +145,12 @@ def timeout=(value)
       @connect_timeout, @send_timeout, @receive_timeout = value, value, value
     end
 
+    # Set an encryption_master_key to use with private-encrypted channels from
+    # a base64 encoded string.
+    def encryption_master_key_base64=(s)
+      @encryption_master_key = s ? Base64.decode64(s) : nil
+    end
+
     ## INTERACT WITH THE API ##
 
     def resource(path)
@@ -413,18 +426,29 @@ def trigger_params(channels, event_name, data, params)
       channels = Array(channels).map(&:to_s)
       raise Pusher::Error, "Too many channels (#{channels.length}), max 10" if channels.length > 10
 
+      encoded_data = if channels.any?{ |c| c.match(/^private-encrypted-/) } then
+        raise Pusher::Error, "Cannot trigger to multiple channels if any are encrypted" if channels.length > 1
+        encrypt(channels[0], encode_data(data))
+      else
+        encode_data(data)
+      end
+
       params.merge({
         name: event_name,
         channels: channels,
-        data: encode_data(data),
+        data: encoded_data,
       })
     end
 
     def trigger_batch_params(events)
       {
         batch: events.map do |event|
           event.dup.tap do |e|
-            e[:data] = encode_data(e[:data])
+            e[:data] = if e[:channel].match(/^private-encrypted-/) then
+              encrypt(e[:channel], encode_data(e[:data]))
+            else
+              encode_data(e[:data])
+            end
           end
         end
       }
@@ -436,6 +460,28 @@ def encode_data(data)
       MultiJson.encode(data)
     end
 
+    # Encrypts a message with a key derived from the master key and channel
+    # name
+    def encrypt(channel, encoded_data)
+      raise ConfigurationError, :encryption_master_key unless @encryption_master_key
+
+      # Only now load rbnacl, so that people that aren't using it don't need to
+      # install libsodium
+      require 'rbnacl'
+
+      secret_box = RbNaCl::SecretBox.new(
+        RbNaCl::Hash.sha256(channel + @encryption_master_key)
+      )
+
+      nonce = RbNaCl::Random.random_bytes(secret_box.nonce_bytes)
+      ciphertext = secret_box.encrypt(nonce, encoded_data)
+
+      MultiJson.encode({
+        "nonce" => Base64::encode64(nonce),
+        "ciphertext" => Base64::encode64(ciphertext),
+      })
+    end
+
     def configured?
       host && scheme && key && secret && app_id
     end

pusher.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'pusher-signature', "~> 0.1.8"
   s.add_dependency "httpclient", "~> 2.8"
   s.add_dependency "jruby-openssl" if defined?(JRUBY_VERSION)
+  s.add_dependency "rbnacl", "~> 7.1"
 
   s.add_development_dependency "rspec", "~> 3.9"
   s.add_development_dependency "webmock", "~> 3.9"

spec/client_spec.rb

@@ -1,7 +1,12 @@
-require 'spec_helper'
+require 'base64'
 
+require 'rbnacl'
 require 'em-http'
 
+require 'spec_helper'
+
+encryption_master_key = RbNaCl::Random.random_bytes(32)
+
 describe Pusher do
   # The behaviour should be the same when using the Client object, or the
   # 'global' client delegated through the Pusher class
@@ -171,11 +176,22 @@
       end
     end
 
+    describe 'can set encryption_master_key_base64' do
+      it "sets encryption_master_key" do
+        @client.encryption_master_key_base64 =
+          Base64.encode64(encryption_master_key)
+
+        expect(@client.encryption_master_key).to eq(encryption_master_key)
+      end
+    end
+
     describe 'when configured' do
       before :each do
         @client.app_id = '20'
         @client.key    = '12345678900000001'
         @client.secret = '12345678900000001'
+        @client.encryption_master_key_base64 =
+          Base64.encode64(encryption_master_key)
       end
 
       describe '#[]' do
@@ -321,6 +337,46 @@
             }
           end
         end
+
+        it "should fail to publish to encrypted channels when missing key" do
+          @client.encryption_master_key_base64 = nil
+          expect {
+            @client.trigger('private-encrypted-channel', 'event', {'some' => 'data'})
+          }.to raise_error(Pusher::ConfigurationError)
+          expect(WebMock).not_to have_requested(:post, @api_path)
+        end
+
+        it "should fail to publish to multiple channels if one is encrypted" do
+          expect {
+            @client.trigger(
+              ['private-encrypted-channel', 'some-other-channel'],
+              'event',
+              {'some' => 'data'},
+            )
+          }.to raise_error(Pusher::Error)
+          expect(WebMock).not_to have_requested(:post, @api_path)
+        end
+
+        it "should encrypt publishes to encrypted channels" do
+          @client.trigger(
+            'private-encrypted-channel',
+            'event',
+            {'some' => 'data'},
+          )
+
+          expect(WebMock).to have_requested(:post, @api_path).with { |req|
+            data = MultiJson.decode(MultiJson.decode(req.body)["data"])
+
+            key = RbNaCl::Hash.sha256(
+              'private-encrypted-channel' + encryption_master_key
+            )
+
+            expect(MultiJson.decode(RbNaCl::SecretBox.new(key).decrypt(
+              Base64.decode64(data["nonce"]),
+              Base64.decode64(data["ciphertext"]),
+            ))).to eq({ 'some' => 'data' })
+          }
+        end
       end
 
       describe '#trigger_batch' do
@@ -352,6 +408,55 @@
             )
           }
         end
+
+        it "should fail to publish to encrypted channels when missing key" do
+          @client.encryption_master_key_base64 = nil
+          expect {
+            @client.trigger_batch(
+              {
+                channel: 'private-encrypted-channel',
+                name: 'event',
+                data: {'some' => 'data'},
+              },
+              {channel: 'mychannel', name: 'event', data: 'already encoded'},
+            )
+          }.to raise_error(Pusher::ConfigurationError)
+          expect(WebMock).not_to have_requested(:post, @api_path)
+        end
+
+        it "should encrypt publishes to encrypted channels" do
+          @client.trigger_batch(
+            {
+              channel: 'private-encrypted-channel',
+              name: 'event',
+              data: {'some' => 'data'},
+            },
+            {channel: 'mychannel', name: 'event', data: 'already encoded'},
+          )
+
+          expect(WebMock).to have_requested(:post, @api_path).with { |req|
+            batch = MultiJson.decode(req.body)["batch"]
+            expect(batch.length).to eq(2)
+
+            expect(batch[0]["channel"]).to eq("private-encrypted-channel")
+            expect(batch[0]["name"]).to eq("event")
+
+            data = MultiJson.decode(batch[0]["data"])
+
+            key = RbNaCl::Hash.sha256(
+              'private-encrypted-channel' + encryption_master_key
+            )
+
+            expect(MultiJson.decode(RbNaCl::SecretBox.new(key).decrypt(
+              Base64.decode64(data["nonce"]),
+              Base64.decode64(data["ciphertext"]),
+            ))).to eq({ 'some' => 'data' })
+
+            expect(batch[1]["channel"]).to eq("mychannel")
+            expect(batch[1]["name"]).to eq("event")
+            expect(batch[1]["data"]).to eq("already encoded")
+          }
+        end
       end
 
       describe '#trigger_async' do