feat!: add support for binary passwords (as Buffers)

Author: mikuso

README.md

@@ -307,7 +307,7 @@ The callback function is called with the following three arguments:
 * `handshake` {Object} - A handshake object
   * `protocols` {Set} - A set of subprotocols purportedly supported by the client.
   * `identity` {String} - The identity portion of the connection URL, decoded.
-  * `password` {String} - If HTTP Basic auth was used in the connection, and the username correctly matches the identity, this field will contain the password (otherwise `undefined`). Read [Security Profile 1](#security-profile-1) for more details of how this works.
+  * `password` {Buffer} - If HTTP Basic auth was used in the connection, and the username correctly matches the identity, this field will contain the password (otherwise `undefined`). Typically this password would be a string, but the OCPP specs allow for this to be binary, so it is provided as a `Buffer` for you to interpret as you wish. Read [Security Profile 1](#security-profile-1) for more details of how this works.
   * `endpoint` {String} - The endpoint path portion of the connection URL. This is the part of the path before the identity.
   * `query` {URLSearchParams} - The query string parsed as [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams).
   * `remoteAddress` {String} - The remote IP address of the socket.
@@ -384,7 +384,7 @@ Returns a `Promise` which resolves when the server has completed closing.
   - `endpoint` {String} - The RPC server's endpoint (a websocket URL). **Required**.
   - `identity` {String} - The RPC client's identity. Will be automatically encoded. **Required**.
   - `protocols` {Array<String>} - Array of subprotocols supported by this client. Defaults to `[]`.
-  - `password` {String} - Optional password to use in [HTTP Basic auth](#security-profile-1). (The username will always be the identity).
+  - `password` {String|Buffer} - Optional password to use in [HTTP Basic auth](#security-profile-1). This can be a Buffer to allow for binary auth keys as recommended in the OCPP security whitepaper. If provided as a string, it will be encoded as UTF-8. (The corresponding username will always be the identity).
   - `headers` {Object} - Additional HTTP headers to send along with the websocket upgrade request. Defaults to `{}`.
   - `query` {Object|String} - An optional query string or object to append as the query string of the connection URL. Defaults to `''`.
   - `callTimeoutMs` {Number} - Milliseconds to wait before unanswered outbound calls are rejected automatically. Defaults to `60000`.
@@ -675,7 +675,7 @@ The RPCServerClient is a subclass of RPCClient. This represents an RPCClient fro
 * {Object}
   * `protocols` {Set} - A set of subprotocols purportedly supported by the client.
   * `identity` {String} - The identity portion of the connection URL, decoded.
-  * `password` {String} - If HTTP Basic auth was used in the connection, and the username correctly matches the identity, this field will contain the password (otherwise `undefined`). Read [Security Profile 1](#security-profile-1) for more details of how this works.
+  * `password` {Buffer} - If HTTP Basic auth was used in the connection, and the username correctly matches the identity, this field will contain the password (otherwise `undefined`). Typically this password would be a string, but the OCPP specs allow for this to be binary, so it is provided as a `Buffer` for you to interpret as you wish. Read [Security Profile 1](#security-profile-1) for more details of how this works.
   * `endpoint` {String} - The endpoint path portion of the connection URL. This is the part of the path before the identity.
   * `query` {URLSearchParams} - The query string parsed as [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams).
   * `remoteAddress` {String} - The remote IP address of the socket.
@@ -855,7 +855,7 @@ const cli = new RPCClient({
 
 const server = new RPCServer();
 server.auth((accept, reject, handshake) => {
-    if (handshake.identity === "AzureDiamond" && handshake.password === "hunter2") {
+    if (handshake.identity === "AzureDiamond" && handshake.password.toString('utf8') === "hunter2") {
         accept();
     } else {
         reject(401);
@@ -876,6 +876,8 @@ In practice, it's not uncommon to see violations of RFC7617 in the wild. All maj
 
 However, in OCPP, since we have the luxury of knowing that the username must always be equal to the client's identity, it is no longer necessary to rely upon a colon to delineate the username from the password. This module makes use of this guarantee to enable identities and passwords to contain as many or as few colons as you wish.
 
+Additionally, the OCPP security whitepaper recommends passwords consist purely of random bytes (for maximum entropy), although this violates the Basic Auth RFC which requires all passwords to be TEXT (US-ASCII compatible with no control characters). For this reason, this library will not make any presumptions about the character encoding (or otherwise) of the password provided, and present the password as a `Buffer`.
+
 ```js
 const { RPCClient, RPCServer } = require('ocpp-rpc');
 
@@ -886,8 +888,8 @@ const cli = new RPCClient({
 
 const server = new RPCServer();
 server.auth((accept, reject, handshake) => {
-    console.log(handshake.identity); // "this:is:ok"
-    console.log(handshake.password); // "as:is:this"
+    console.log(handshake.identity);                  // "this:is:ok"
+    console.log(handshake.password.toString('utf8')); // "as:is:this"
     accept();
 });
 
@@ -910,8 +912,8 @@ const server = new RPCServer();
 server.auth((accept, reject, handshake) => {
     const cred = auth.parse(handshake.headers.authorization);
 
-    console.log(cred.name); // "this"
-    console.log(cred.pass); // "is:broken:as:is:this"
+    console.log(cred.name);                  // "this"
+    console.log(cred.pass.toString('utf8')); // "is:broken:as:is:this"
     accept();
 });
 

lib/client.js

@@ -492,8 +492,13 @@ class RPCClient extends EventEmitter {
             Object.assign(wsOpts.headers, this._options.headers);
 
             if (this._options.password != null) {
-                const userPass = [this._identity, this._options.password].join(':');
-                const b64 = Buffer.from(userPass).toString('base64');
+                const usernameBuffer = Buffer.from(this._identity + ':');
+                let passwordBuffer = this._options.password;
+                if (typeof passwordBuffer === 'string') {
+                    passwordBuffer = Buffer.from(passwordBuffer, 'utf8');
+                }
+
+                const b64 = Buffer.concat([usernameBuffer, passwordBuffer]).toString('base64');
                 wsOpts.headers.authorization = 'Basic ' + b64;
             }
 

lib/server.js

@@ -144,12 +144,18 @@ class RPCServer extends EventEmitter {
                          * However, this shouldn't cause any confusion as we have a
                          * guarantee from OCPP that the username will always be equal to
                          * the identity.
+                         * It also supports binary passwords, which is also a spec violation
+                         * but is necessary for allowing truly random binary keys as
+                         * recommended by the OCPP security whitepaper.
                          */
                         const b64up = headers.authorization.match(/^ *(?:[Bb][Aa][Ss][Ii][Cc]) +([A-Za-z0-9._~+/-]+=*) *$/)[1];
-                        const userPass = Buffer.from(b64up, 'base64').toString('utf8');
-                        if (userPass.substring(0, identity.length + 1) === (identity + ':')) {
-                            // identity matches!
-                            password = userPass.substring(identity.length + 1);
+                        const userPassBuffer = Buffer.from(b64up, 'base64');
+
+                        const clientIdentityUserBuffer = Buffer.from(identity + ':');
+
+                        if (clientIdentityUserBuffer.compare(userPassBuffer, 0, clientIdentityUserBuffer.length) === 0) {
+                            // first part of buffer matches `${identity}:`
+                            password = userPassBuffer.subarray(clientIdentityUserBuffer.length);
                         }
                     } catch (err) {
                         // failing to parse authorization header is no big deal.

test/client.js

@@ -835,7 +835,7 @@ describe('RPCClient', function(){
             }
         });
 
-        it('should authenticate with password', async () => {
+        it('should authenticate with string passwords', async () => {
 
             const password = 'hunter2';
             let recPass;
@@ -854,7 +854,39 @@ describe('RPCClient', function(){
 
             try {
                 await cli.connect();
-                assert.equal(password, recPass);
+                assert.equal(password, recPass.toString('utf8'));
+
+            } finally {
+                cli.close();
+                close();
+            }
+        });
+
+        it('should authenticate with binary passwords', async () => {
+            
+            const password = Buffer.from([
+                0,1,2,3,4,5,6,7,8,9,
+                65,66,67,68,69,
+                251,252,253,254,255,
+            ]);
+            let recPass;
+
+            const {endpoint, close, server} = await createServer();
+            server.auth((accept, reject, handshake) => {
+                recPass = handshake.password;
+                accept();
+            });
+
+            const cli = new RPCClient({
+                endpoint,
+                identity: 'X',
+                password,
+            });
+
+            try {
+                await cli.connect();
+                // console.log(Buffer.from(recPass, 'ascii'));
+                assert.equal(password.toString('hex'), recPass.toString('hex'));
 
             } finally {
                 cli.close();

test/server.js

@@ -427,7 +427,7 @@ describe('RPCServer', function(){
             }});
 
             server.auth((accept, reject, handshake) => {
-                accept({pwd: handshake.password});
+                accept({pwd: handshake.password.toString('utf8')});
             });
 
             const cli = new RPCClient({
@@ -470,7 +470,7 @@ describe('RPCServer', function(){
 
             try {
                 await cli.connect();
-                assert.equal(password, recPass);
+                assert.equal(password, recPass.toString('utf8'));
                 assert.equal(identity, recIdent);
 
             } finally {
@@ -498,7 +498,7 @@ describe('RPCServer', function(){
 
             try {
                 await cli.connect();
-                assert.equal(password, recPass);
+                assert.equal(password, recPass.toString('utf8'));
 
             } finally {
                 cli.close();
@@ -586,6 +586,41 @@ describe('RPCServer', function(){
                 close();
             }
         });
+        
+        it('should recognise binary passwords', async () => {
+            
+            const password = Buffer.from([
+                0,1,2,3,4,5,6,7,8,9,
+                65,66,67,68,69,
+                251,252,253,254,255,
+            ]);
+
+            const {endpoint, close, server} = await createServer({}, {withClient: cli => {
+                cli.handle('GetPassword', () => {
+                    return cli.session.pwd;
+                });
+            }});
+
+            server.auth((accept, reject, handshake) => {
+                accept({pwd: handshake.password.toString('hex')});
+            });
+
+            const cli = new RPCClient({
+                endpoint,
+                identity: 'X',
+                password,
+            });
+
+            try {
+                await cli.connect();
+                const pass = await cli.call('GetPassword');
+                assert.equal(password.toString('hex'), pass);
+
+            } finally {
+                cli.close();
+                close();
+            }
+        });
 
     });