End-to-end Encryption

* add end-to-end encryption feature
* add end-to-end encryption tests

Author: damdo

README.md

@@ -24,6 +24,7 @@ In order to use this library, you need to have a free account on <http://pusher.
   - [Getting Information For A Specific Channel](#getting-information-for-a-specific-channel)
   - [Getting User Information For A Presence Channel](#getting-user-information-for-a-presence-channel)
 - [Authenticating Channel Subscription](#authenticating-channel-subscription)
+- [End-to-end Encryption (Beta)](#end-to-end-encryption-beta)
 - [Receiving Webhooks](#receiving-webhooks)
 - [Request Library Configuration](#request-library-configuration)
   - [Google App Engine](#google-app-engine)
@@ -55,22 +56,22 @@ constructor arguments which identify your Pusher app. You can find them by
 going to "API Keys" on your app at <https://app.pusher.com>.
 
 ```python
-from pusher import Pusher
-pusher = Pusher(app_id=u'4', key=u'key', secret=u'secret', cluster=u'cluster')
+import pusher
+pusher_client = pusher.Pusher(app_id=u'4', key=u'key', secret=u'secret', cluster=u'cluster')
 ```
 
 You can then trigger events to channels. Channel and event names may only
 contain alphanumeric characters, `-` and `_`:
 
 ```python
-pusher.trigger(u'a_channel', u'an_event', {u'some': u'data'})
+pusher_client.trigger(u'a_channel', u'an_event', {u'some': u'data'})
 ```
 
 ## Configuration
 
 ```python
-from pusher import Pusher
-pusher = Pusher(app_id, key, secret, cluster=u'cluster')
+import pusher
+pusher_client = pusher.Pusher(app_id, key, secret, cluster=u'cluster')
 ```
 
 |Argument   |Description   |
@@ -82,6 +83,7 @@ pusher = Pusher(app_id, key, secret, cluster=u'cluster')
 |host `String`    | **Default:`None`** <br> The host to connect to |
 |port `int`       | **Default:`None`** <br>Which port to connect to |
 |ssl `bool`       | **Default:`True`** <br> Use HTTPS |
+|encryption_master_key `String`       | **Default:`None`** <br> The encryption master key for End-to-end Encryption |
 |backend `Object` | an object that responds to the `send_request(request)` method. If none is provided, a `pusher.requests.RequestsBackend` instance is created. |
 |json_encoder `Object` | **Default: `None`**<br> Custom JSON encoder. |
 |json_decoder `Object` | **Default: `None`**<br> Custom JSON decoder.
@@ -91,8 +93,8 @@ The constructor will throw a `TypeError` if it is called with parameters that do
 ##### Example
 
 ```py
-from pusher import Pusher
-pusher = Pusher(app_id=u'4', key=u'key', secret=u'secret', ssl=True, cluster=u'cluster')
+import pusher
+pusher_client = pusher.Pusher(app_id=u'4', key=u'key', secret=u'secret', ssl=True, cluster=u'cluster')
 ```
 
 ## Triggering Events
@@ -119,7 +121,7 @@ To trigger an event on one or more channels, use the `trigger` method on the `Pu
 This call will trigger to `'a_channel'` and `'another_channel'`, and exclude the recipient with socket_id `"1234.12"`.
 
 ```python
-pusher.trigger([u'a_channel', u'another_channel'], u'an_event', {u'some': u'data'}, "1234.12")
+pusher_client.trigger([u'a_channel', u'another_channel'], u'an_event', {u'some': u'data'}, "1234.12")
 ```
 
 #### `Pusher::trigger_batch`
@@ -150,7 +152,7 @@ Events are a `Dict` with keys:
 ##### Example
 
 ```python
-pusher.trigger_batch([
+pusher_client.trigger_batch([
   { u'channel': u'a_channel', u'name': u'an_event', u'data': {u'some': u'data'}, u'socket_id': '1234.12'},
   { u'channel': u'a_channel', u'name': u'an_event', u'data': {u'some': u'other data'}}
 ])
@@ -177,7 +179,7 @@ pusher.trigger_batch([
 ##### Example
 
 ```python
-channels = pusher.channels_info(u"presence-", [u'user_count'])
+channels = pusher_client.channels_info(u"presence-", [u'user_count'])
 
 #=> {u'channels': {u'presence-chatroom': {u'user_count': 2}, u'presence-notifications': {u'user_count': 1}}}
 ```
@@ -200,7 +202,7 @@ channels = pusher.channels_info(u"presence-", [u'user_count'])
 ##### Example
 
 ```python
-channel = pusher.channel_info(u'presence-chatroom', [u"user_count"])
+channel = pusher_client.channel_info(u'presence-chatroom', [u"user_count"])
 #=> {u'user_count': 42, u'occupied': True}
 ```
 
@@ -221,7 +223,7 @@ channel = pusher.channel_info(u'presence-chatroom', [u"user_count"])
 ##### Example
 
 ```python
-pusher.users_info(u'presence-chatroom')
+pusher_client.users_info(u'presence-chatroom')
 #=> {u'users': [{u'id': u'1035'}, {u'id': u'4821'}]}
 ```
 
@@ -252,7 +254,7 @@ Using your `Pusher` instance, with which you initialized `Pusher`, you can gener
 ###### Private Channels
 
 ```python
-auth = pusher.authenticate(
+auth = pusher_client.authenticate(
 
   channel=u"private-channel",
 
@@ -264,7 +266,7 @@ auth = pusher.authenticate(
 ###### Presence Channels
 
 ```python
-auth = pusher.authenticate(
+auth = pusher_client.authenticate(
 
   channel=u"presence-channel",
 
@@ -280,6 +282,39 @@ auth = pusher.authenticate(
 # return `auth` as a response
 ```
 
+## End to End Encryption (Beta)
+
+This library supports end to end encryption of your private 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. You should first set up Private channels. This involves [creating an authentication endpoint on your server](https://pusher.com/docs/authenticating_users).
+
+2. Next, Specify your 32 character `encryption_master_key`. This is secret and you should never share this with anyone. Not even Pusher.
+
+```python
+
+import pusher
+
+pusher_client = pusher.Pusher(
+  app_id='yourappid',
+  key='yourkey',
+  secret='yoursecret',
+  encryption_master_key='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
+  cluster='yourclustername',
+  ssl=True
+)
+
+pusher_client.trigger('private-encrypted-my-channel', 'my-event', {
+  'message': 'hello world'
+})
+```
+3. Channels where you wish to use end to end encryption must be prefixed with `private-encrypted-`.
+
+4. 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/ and seeing the scrambled ciphertext.
+
+**Important note: This will not encrypt messages on channels that are not prefixed by private-encrypted-.**
+
+More info on End-to-end Encrypted Channels [here](https://pusher.com/docs/client_api_guide/client_encrypted_channels).
+
 ## Receiving Webhooks
 
 If you have webhooks set up to POST a payload to a specified endpoint, you may wish to validate that these are actually from Pusher. The `Pusher` object achieves this by checking the authentication signature in the request body using your application credentials.
@@ -301,7 +336,7 @@ If you have webhooks set up to POST a payload to a specified endpoint, you may w
 ##### Example
 
 ```python
-webhook = pusher.validate_webhook(
+webhook = pusher_client.validate_webhook(
 
   key="key_sent_in_header",
 
@@ -341,11 +376,12 @@ Get the list of channels in an application | *&#10004;*
 Get the state of a single channel          | *&#10004;*
 Get a list of users in a presence channel  | *&#10004;*
 WebHook validation                         | *&#10004;*
-Heroku add-on support                           | *&#10004;*
+Heroku add-on support                      | *&#10004;*
 Debugging & Logging                        | *&#10004;*
 Cluster configuration                      | *&#10004;*
 Timeouts                                   | *&#10004;*
 HTTPS                                      | *&#10004;*
+End-to-end Encryption                      | *&#10004;*
 HTTP Proxy configuration                   | *&#10008;*
 HTTP KeepAlive                             | *&#10008;*
 

pusher/authentication_client.py

@@ -13,25 +13,28 @@
 import re
 import six
 import time
+import base64
 
 from pusher.util import (
     ensure_text,
     validate_channel,
     validate_socket_id,
-    channel_name_re)
+    channel_name_re
+    )
 
 from pusher.client import Client
 from pusher.http import GET, POST, Request, request_method
 from pusher.signature import sign, verify
+from pusher.crypto import *
 
 
 class AuthenticationClient(Client):
     def __init__(
             self, app_id, key, secret, ssl=True, host=None, port=None,
-            timeout=5, cluster=None, json_encoder=None, json_decoder=None,
+            timeout=5, cluster=None, encryption_master_key=None, json_encoder=None, json_decoder=None,
             backend=None, **backend_options):
         super(AuthenticationClient, self).__init__(
-            app_id, key, secret, ssl, host, port, timeout, cluster,
+            app_id, key, secret, ssl, host, port, timeout, cluster, encryption_master_key,
             json_encoder, json_decoder, backend, **backend_options)
 
         if host:
@@ -70,12 +73,17 @@ def authenticate(self, channel, socket_id, custom_data=None):
         signature = sign(self.secret, string_to_sign)
 
         auth = "%s:%s" % (self.key, signature)
-        result = {'auth': auth}
+        response_payload = { "auth": auth }
+
+        if is_encrypted_channel(channel):
+            shared_secret = generate_shared_secret(channel, self._encryption_master_key)
+            shared_secret_b64 = base64.b64encode(shared_secret)
+            response_payload["shared_secret"] = shared_secret_b64
 
         if custom_data:
-            result['channel_data'] = custom_data
+            response_payload['channel_data'] = custom_data
 
-        return result
+        return response_payload
 
 
     def validate_webhook(self, key, signature, body):

pusher/client.py

@@ -8,13 +8,13 @@
 
 import six
 
-from pusher.util import ensure_text, app_id_re
+from pusher.util import ensure_text, ensure_binary, app_id_re
 
 
 class Client(object):
     def __init__(
             self, app_id, key, secret, ssl=True, host=None, port=None,
-            timeout=5, cluster=None, json_encoder=None, json_decoder=None,
+            timeout=5, cluster=None, encryption_master_key=None, json_encoder=None, json_decoder=None,
             backend=None, **backend_options):
         if backend is None:
               from .requests import RequestsBackend
@@ -44,6 +44,12 @@ def __init__(
         self._json_encoder = json_encoder
         self._json_decoder = json_decoder
 
+
+        if encryption_master_key is not None:
+            encryption_master_key = ensure_binary(encryption_master_key, "encryption_master_key")
+
+        self._encryption_master_key = encryption_master_key
+
         self.http = backend(self, **backend_options)
 
     @property

pusher/crypto.py

@@ -0,0 +1,80 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import (
+    print_function,
+    unicode_literals,
+    absolute_import,
+    division)
+
+import hashlib
+import nacl
+import base64
+
+from pusher.util import (
+    ensure_text,
+    ensure_binary,
+    data_to_string)
+
+import nacl.secret
+import nacl.utils
+
+# The prefix any e2e channel must have
+ENCRYPTED_PREFIX = 'private-encrypted-'
+
+def is_encrypted_channel(channel):
+    """
+    is_encrypted_channel() checks if the channel is encrypted by verifying the prefix
+    """
+    if channel.startswith(ENCRYPTED_PREFIX):
+        return True
+    return False
+
+def is_encryption_master_key_valid(encryption_master_key):
+    """
+    is_encryption_master_key_valid() checks if the provided encryption_master_key is valid by checking its length
+    the key is assumed to be a six.binary_type (python2 str or python3 bytes)
+    """
+    if encryption_master_key is not None and len(encryption_master_key) == 32:
+        return True
+
+    return False
+
+def generate_shared_secret(channel, encryption_master_key):
+    """
+    generate_shared_secret() takes a six.binary_type (python2 str or python3 bytes) channel name and encryption_master_key
+    and returns the sha256 hash in six.binary_type format
+    """
+    if is_encryption_master_key_valid(encryption_master_key):
+        # the key has to be 32 bytes long
+        hashable = channel + encryption_master_key
+        return hashlib.sha256(hashable).digest()
+
+    raise ValueError("Provided encryption_master_key is not 32 char long")
+
+def encrypt(channel, data, encryption_master_key, nonce=None):
+    """
+    encrypt() encrypts the provided payload specified in the 'data' parameter
+    """
+    channel = ensure_binary(channel, "channel")
+    shared_secret = generate_shared_secret(channel, encryption_master_key)
+    # the box setup to seal/unseal data payload
+    box = nacl.secret.SecretBox(shared_secret)
+
+    if nonce is None:
+        nonce = nacl.utils.random(nacl.secret.SecretBox.NONCE_SIZE)
+    else:
+        nonce = ensure_binary(nonce, "nonce")
+
+    # convert nonce to base64
+    nonce_b64 = base64.b64encode(nonce)
+
+    # encrypt the data payload with nacl
+    encrypted = box.encrypt(data.encode("utf-8"), nonce)
+
+    # obtain the ciphertext
+    cipher_text = encrypted.ciphertext
+    # encode cipertext to base64
+    cipher_text_b64 = base64.b64encode(cipher_text)
+
+    # format output
+    return { "nonce" : nonce_b64.decode("utf-8"), "ciphertext": cipher_text_b64.decode("utf-8") }

pusher/pusher.py

@@ -36,6 +36,8 @@ class Pusher(object):
     :param host:    Used for custom host destination
     :param port:    Used for custom port destination
     :param timeout: Request timeout (in seconds)
+    :param encryption_master_key: Used to derive a shared secret between
+      server and the clients for payload encryption/decryption
     :param cluster: Convention for other clusters than the main Pusher-one.
       Eg: 'eu' will resolve to the api-eu.pusherapp.com host
     :param backend: an http adapter class (AsyncIOBackend, RequestsBackend,
@@ -44,15 +46,14 @@ class Pusher(object):
     """
     def __init__(
             self, app_id, key, secret, ssl=True, host=None, port=None,
-            timeout=5, cluster=None, json_encoder=None, json_decoder=None,
-            backend=None, notification_host=None, notification_ssl=True,
-            **backend_options):
+            timeout=5, cluster=None, encryption_master_key=None, json_encoder=None, json_decoder=None,
+            backend=None, notification_host=None, notification_ssl=True, **backend_options):
         self._pusher_client = PusherClient(
-            app_id, key, secret, ssl, host, port, timeout, cluster,
+            app_id, key, secret, ssl, host, port, timeout, cluster, encryption_master_key,
             json_encoder, json_decoder, backend, **backend_options)
 
         self._authentication_client = AuthenticationClient(
-            app_id, key, secret, ssl, host, port, timeout, cluster,
+            app_id, key, secret, ssl, host, port, timeout, cluster, encryption_master_key,
             json_encoder, json_decoder, backend, **backend_options)
 
         self._notification_client = NotificationClient(