README and CHANGELOG

Author: callum-oakley

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 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. 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. You should first set up Private channels. This involves [creating 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+