Merge pull request #118 from pusher/base64-master-key

Accept master enc key as base64

Author: mdpye

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 [UPGRADED] development dependencies
 
+[ADDED] encryptionMasterKeyBase64 constructor parameter to make it easier to use the full range of 32 byte binary values in encryption key
+[DEPRECATED] encryptionMasterKey constructor parameter - use encryptionMasterKeyBase64
+
 ## 3.0.0 (2019-09-26)
 
 [REMOVED] Support for Node versions < 8

README.md

@@ -67,7 +67,7 @@ var pusher = new Pusher({
   cluster: 'CLUSTER', // if `host` is present, it will override the `cluster` option.
   host: 'HOST', // optional, defaults to api.pusherapp.com
   port: PORT, // optional, defaults to 80 for non-TLS connections and 443 for TLS connections
-  encryptionMasterKey: ENCRYPTION_MASTER_KEY, // a 32 character long key used to derive secrets for end to end encryption (see below!)
+  encryptionMasterKeyBase64: ENCRYPTION_MASTER_KEY, // a base64 string which encodes 32 bytes, used to derive the per-channel encryption keys (see below!)
 });
 ```
 
@@ -82,7 +82,7 @@ var pusher = Pusher.forCluster("CLUSTER", {
   secret: 'SECRET_KEY',
   useTLS: USE_TLS, // optional, defaults to false
   port: PORT, // optional, defaults to 80 for non-TLS connections and 443 for TLS connections
-  encryptionMasterKey: ENCRYPTION_MASTER_KEY, // a 32 character long key used to derive secrets for end to end encryption (see below!)
+  encryptionMasterKeyBase64: ENCRYPTION_MASTER_KEY, // a base64 string which encodes 32 bytes, used to derive the per-channel encryption keys (see below!)
 });
 ```
 
@@ -188,15 +188,22 @@ This library supports end-to-end encryption of your private channels. This means
 
 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.
+2. 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
+   ```
 
    ```javascript
    var pusher = new Pusher({
      appId: 'APP_ID',
      key: 'APP_KEY',
      secret: 'SECRET_KEY',
      useTLS: true,
-     encryptionMasterKey: 'abcdefghijklmnopqrstuvwxyzabcdef',
+     encryptionMasterKeyBase64: '<KEY GENERATED BY PREVIOUS COMMAND>',
    });
    ```
 
@@ -230,11 +237,11 @@ Using presence channels is similar to private channels, but you can specify extr
 
 ```javascript
 var channelData = {
-	user_id: 'unique_user_id',
-	user_info: {
-	  name: 'Phil Leggetter'
-	  twitter_id: '@leggetter'
-	}
+  user_id: 'unique_user_id',
+  user_info: {
+    name: 'Phil Leggetter'
+    twitter_id: '@leggetter'
+  }
 };
 var auth = pusher.authenticate(socketId, channel, channelData);
 ```
@@ -263,10 +270,10 @@ Params can't include following keys:
 The following example provides the signature of the callback and an example of parsing the result:
 ```javascript
 pusher.get({ path: '/channels', params: {} }, function(error, request, response) {
-	if (response.statusCode === 200) {
-		var result = JSON.parse(response.body);
-		var channelsInfo = result.channels;
-	}
+  if (response.statusCode === 200) {
+    var result = JSON.parse(response.body);
+    var channelsInfo = result.channels;
+  }
 });
 ```
 

lib/config.js

@@ -1,4 +1,5 @@
 var Token = require('./token');
+var isBase64 = require('is-base64')
 
 function Config(options) {
   options = options || {};
@@ -23,15 +24,41 @@ function Config(options) {
   this.timeout = options.timeout;
   this.keepAlive = options.keepAlive;
 
+  // Handle deprecated raw 32 byte string as key
   if (options.encryptionMasterKey !== undefined) {
+    if (options.encryptionMasterKeyBase64 !== undefined) {
+      throw new Error("Do not specify both encryptionMasterKey and encryptionMasterKeyBase64. " +
+        "encryptionMasterKey is deprecated, please specify only encryptionMasterKeyBase64.");
+    }
+    console.warn("`encryptionMasterKey` option is deprecated in favor of `encryptionMasterKeyBase64`");
     if (typeof(options.encryptionMasterKey) !== 'string') {
       throw new Error("encryptionMasterKey must be a string");
     }
     if (options.encryptionMasterKey.length !== 32) {
-      throw new Error("encryptionMasterKey must be 32 characters long, but the string '" + options.encryptionMasterKey + "' is " + options.encryptionMasterKey.length + " characters long");
+      throw new Error("encryptionMasterKey must be 32 bytes long, but the string '" +
+        options.encryptionMasterKey + "' is " + options.encryptionMasterKey.length + " bytes long");
     }
+
     this.encryptionMasterKey = options.encryptionMasterKey;
   }
+
+  // Handle base64 encoded 32 byte key to encourage use of the full range of byte values
+  if (options.encryptionMasterKeyBase64 !== undefined) {
+    if (typeof(options.encryptionMasterKeyBase64) !== 'string') {
+      throw new Error("encryptionMasterKeyBase64 must be a string");
+    }
+    if (!isBase64(options.encryptionMasterKeyBase64)) {
+      throw new Error("encryptionMasterKeyBase64 must be valid base64");
+    }
+
+    var decodedKey = Buffer.from(options.encryptionMasterKeyBase64, "base64").toString("binary");
+    if (decodedKey.length !== 32) {
+      throw new Error("encryptionMasterKeyBase64 must decode to 32 bytes, but the string " +
+        options.encryptionMasterKeyBase64 + "' decodes to " + decodedKey.length + " bytes");
+    }
+
+    this.encryptionMasterKey = decodedKey;
+  }
 }
 
 Config.prototype.prefixPath = function(subPath) {

package-lock.json

@@ -25,7 +25,8 @@
     "@types/request": "^2.47.1",
     "request": "2.88.0",
     "tweetnacl": "^1.0.0",
-    "tweetnacl-util": "^0.15.0"
+    "tweetnacl-util": "^0.15.0",
+    "is-base64": "^1.1.0"
   },
   "devDependencies": {
     "expect.js": "=0.3.1",

package.json

@@ -91,5 +91,55 @@ describe("Pusher", function() {
       var pusher = new Pusher({ timeout: 1001 });
       expect(pusher.config.timeout).to.equal(1001);
     });
+
+    it("should support `encryptionMasterKey` of 32 bytes", function() {
+      var key = "01234567890123456789012345678901"
+      var pusher = new Pusher({ encryptionMasterKey: key });
+      expect(pusher.config.encryptionMasterKey).to.equal(key);
+    });
+
+    it("should reject `encryptionMasterKey` of 31 bytes", function() {
+      var key = "0123456789012345678901234567890"
+      expect(function () {
+        var pusher = new Pusher({ encryptionMasterKey: key });
+      }).to.throwException(/31 bytes/);
+    });
+
+    it("should reject `encryptionMasterKey` of 33 bytes", function() {
+      var key = "012345678901234567890123456789012"
+      expect(function () {
+        var pusher = new Pusher({ encryptionMasterKey: key });
+      }).to.throwException(/33 bytes/);
+    });
+
+    it("should support `encryptionMasterKeyBase64` which decodes to 32 bytes", function() {
+      var key = "01234567890123456789012345678901"
+      var keyBase64 = Buffer.from(key, "binary").toString("base64");
+      var pusher = new Pusher({ encryptionMasterKeyBase64: keyBase64 });
+      expect(pusher.config.encryptionMasterKey).to.equal(key);
+    });
+
+    it("should reject `encryptionMasterKeyBase64` which decodes to 31 bytes", function() {
+      var key = "0123456789012345678901234567890"
+      var keyBase64 = Buffer.from(key, "binary").toString("base64");
+      expect(function () {
+        var pusher = new Pusher({ encryptionMasterKeyBase64: keyBase64 });
+      }).to.throwException(/31 bytes/);
+    });
+
+    it("should reject `encryptionMasterKeyBase64` which decodes to 33 bytes", function() {
+      var key = "012345678901234567890123456789012"
+      var keyBase64 = Buffer.from(key, "binary").toString("base64");
+      expect(function () {
+        var pusher = new Pusher({ encryptionMasterKeyBase64: keyBase64 });
+      }).to.throwException(/33 bytes/);
+    });
+
+    it("should reject `encryptionMasterKeyBase64` which is invalid base64", function() {
+      var keyBase64 = "aGkgd(GhlcmUK"
+      expect(function () {
+        var pusher = new Pusher({ encryptionMasterKeyBase64: keyBase64 });
+      }).to.throwException(/valid base64/);
+    });
   });
 });

tests/integration/pusher/constructor.js

@@ -360,10 +360,15 @@ describe("Pusher", function() {
 describe("Pusher with encryptionMasterKey", function() {
   var pusher;
 
-  var testMasterKey = "01234567890123456789012345678901";
+  var testMasterKey = Buffer.from("01234567890123456789012345678901", "binary").toString("base64");
 
   beforeEach(function() {
-    pusher = new Pusher({ appId: 1234, key: "f00d", secret: "beef", encryptionMasterKey: testMasterKey });
+    pusher = new Pusher({
+      appId: 1234,
+      key: "f00d",
+      secret: "beef",
+      encryptionMasterKeyBase64: testMasterKey
+    });
     nock.disableNetConnect();
   });
 
@@ -388,7 +393,7 @@ describe("Pusher with encryptionMasterKey", function() {
 
       pusher.trigger("one", "my_event", { some: "data "}, done);
     });
-    
+
     it("should encrypt the body of an event triggered on a private-encrypted- channel", function(done) {
       var sentPlaintext = "Hello!";