Client: Allow explicitely specifying a publicKey

This is to support SSH certificates. As before the privateKey will
be used for the publicKey (i.e. the derived publicKey) if nothing
is given.

The given publicKey is checked to match the given privateKey.

Author: TimWolla

README.md

@@ -8,37 +8,39 @@ Development/testing is done against OpenSSH (7.6 currently).
 
 # Table of Contents
 
-* [Requirements](#requirements)
-* [Installation](#installation)
-* [Client Examples](#client-examples)
-  * [Execute `uptime` on a server](#execute-uptime-on-a-server)
-  * [Start an interactive shell session](#start-an-interactive-shell-session)
-  * [Send a raw HTTP request to port 80 on the server](#send-a-raw-http-request-to-port-80-on-the-server)
-  * [Forward local connections to port 8000 on the server to us](#forward-local-connections-to-port-8000-on-the-server-to-us)
-  * [Get a directory listing via SFTP](#get-a-directory-listing-via-sftp)
-  * [Connection hopping](#connection-hopping)
-  * [Forward remote X11 connections](#forward-remote-x11-connections)
-  * [Dynamic (1:1) port forwarding using a SOCKSv5 proxy (using `socksv5`)](#dynamic-11-port-forwarding-using-a-socksv5-proxy-using-socksv5)
-  * [Make HTTP(S) connections easily using a custom http(s).Agent](#make-https-connections-easily-using-a-custom-httpsagent)
-  * [Invoke an arbitrary subsystem (e.g. netconf)](#invoke-an-arbitrary-subsystem)
-* [Server Examples](#server-examples)
-  * [Password and public key authentication and non-interactive (exec) command execution](#password-and-public-key-authentication-and-non-interactive-exec-command-execution)
-  * [SFTP-only server](#sftp-only-server)
-* [API](#api)
-  * [Client](#client)
-      * [Client events](#client-events)
-      * [Client methods](#client-methods)
-  * [Server](#server)
-      * [Server events](#server-events)
-      * [Server methods](#server-methods)
-      * [Connection events](#connection-events)
-      * [Connection methods](#connection-methods)
-      * [Session events](#session-events)
-  * [Channel](#channel)
-  * [Pseudo-TTY settings](#pseudo-tty-settings)
-  * [Terminal modes](#terminal-modes)
-  * [HTTPAgent](#httpagent)
-      * [HTTPAgent methods](#httpagent-methods)
+- [Description](#Description)
+- [Table of Contents](#Table-of-Contents)
+  - [Requirements](#Requirements)
+  - [Installation](#Installation)
+  - [Client Examples](#Client-Examples)
+    - [Execute `uptime` on a server](#Execute-uptime-on-a-server)
+    - [Start an interactive shell session](#Start-an-interactive-shell-session)
+    - [Send a raw HTTP request to port 80 on the server](#Send-a-raw-HTTP-request-to-port-80-on-the-server)
+    - [Forward local connections to port 8000 on the server to us](#Forward-local-connections-to-port-8000-on-the-server-to-us)
+    - [Get a directory listing via SFTP](#Get-a-directory-listing-via-SFTP)
+    - [Connection hopping](#Connection-hopping)
+    - [Forward remote X11 connections](#Forward-remote-X11-connections)
+    - [Dynamic (1:1) port forwarding using a SOCKSv5 proxy (using socksv5)](#Dynamic-11-port-forwarding-using-a-SOCKSv5-proxy-using-socksv5)
+    - [Make HTTP(S) connections easily using a custom http(s).Agent](#Make-HTTPS-connections-easily-using-a-custom-httpsAgent)
+    - [Invoke an arbitrary subsystem](#Invoke-an-arbitrary-subsystem)
+  - [Server Examples](#Server-Examples)
+    - [Password and public key authentication and non-interactive (exec) command execution](#Password-and-public-key-authentication-and-non-interactive-exec-command-execution)
+    - [SFTP-only server](#SFTP-only-server)
+  - [API](#API)
+    - [Client](#Client)
+      - [Client events](#Client-events)
+      - [Client methods](#Client-methods)
+    - [Server](#Server)
+      - [Server events](#Server-events)
+      - [Server methods](#Server-methods)
+      - [Connection events](#Connection-events)
+      - [Connection methods](#Connection-methods)
+      - [Session events](#Session-events)
+    - [Channel](#Channel)
+    - [Pseudo-TTY settings](#Pseudo-TTY-settings)
+    - [Terminal modes](#Terminal-modes)
+    - [HTTPAgent](#HTTPAgent)
+      - [HTTPAgent methods](#HTTPAgent-methods)
 
 ## Requirements
 
@@ -716,6 +718,8 @@ You can find more examples in the `examples` directory of this repository.
 
     * **privateKey** - _mixed_ - _Buffer_ or _string_ that contains a private key for either key-based or hostbased user authentication (OpenSSH format). **Default:** (none)
 
+    * **publicKey** - _mixed_ - _Buffer_ or _string_ that contains a public key or SSH certificate for either key-based or hostbased user authentication (OpenSSH format). **Default:** (derived from private key)
+
     * **passphrase** - _string_ - For an encrypted private key, this is the passphrase used to decrypt it. **Default:** (none)
 
     * **localHostname** - _string_ - Along with **localUsername** and **privateKey**, set this to a non-empty string for hostbased user authentication. **Default:** (none)

lib/client.js

@@ -44,6 +44,7 @@ function Client() {
     username: undefined,
     password: undefined,
     privateKey: undefined,
+    publicKey: undefined,
     tryKeyboard: undefined,
     agent: undefined,
     allowAgentFwd: undefined,
@@ -198,6 +199,10 @@ Client.prototype.connect = function(cfg) {
                             || Buffer.isBuffer(cfg.privateKey)
                             ? cfg.privateKey
                             : undefined);
+  this.config.publicKey = (typeof cfg.publicKey === 'string'
+                           || Buffer.isBuffer(cfg.publicKey)
+                           ? cfg.publicKey
+                           : undefined);
   this.config.localHostname = (typeof cfg.localHostname === 'string'
                                && cfg.localHostname.length
                                ? cfg.localHostname
@@ -235,7 +240,7 @@ Client.prototype.connect = function(cfg) {
   this._agentFwdEnabled = false;
   this._curChan = -1;
   this._remoteVer = undefined;
-  var privateKey;
+  var privateKey, publicKey;
 
   if (this.config.privateKey) {
     privateKey = parseKey(this.config.privateKey, cfg.passphrase);
@@ -245,6 +250,22 @@ Client.prototype.connect = function(cfg) {
       privateKey = privateKey[0]; // OpenSSH's newer format only stores 1 key for now
     if (privateKey.getPrivatePEM() === null)
       throw new Error('privateKey value does not contain a (valid) private key');
+
+    if (this.config.publicKey) {
+      publicKey = parseKey(this.config.publicKey);
+      if (publicKey instanceof Error)
+        throw new Error('Cannot parse publicKey: ' + publicKey.message);
+      if (Array.isArray(publicKey))
+        publicKey = publicKey[0]; // OpenSSH's newer format only stores 1 key for now
+      if (publicKey.getPublicSSH() === null)
+        throw new Error('publicKey value does not contain a (valid) public key');
+      if (publicKey.getPublicPEM() !== privateKey.getPublicPEM()) {
+        throw new Error('publicKey does not belong to the private key');
+      }
+    }
+    else {
+      publicKey = privateKey;
+    }
   }
 
   var stream = this._sshstream = new SSH2Stream({
@@ -383,7 +404,7 @@ Client.prototype.connect = function(cfg) {
   var authsAllowed = ['none'];
   if (this.config.password !== undefined)
     authsAllowed.push('password');
-  if (privateKey !== undefined)
+  if (privateKey !== undefined && publicKey !== undefined)
     authsAllowed.push('publickey');
   if (this.config.agent !== undefined)
     authsAllowed.push('agent');
@@ -425,7 +446,7 @@ Client.prototype.connect = function(cfg) {
         stream.authPassword(self.config.username, self.config.password);
       break;
       case 'publickey':
-        stream.authPK(self.config.username, privateKey);
+        stream.authPK(self.config.username, publicKey);
         stream.once('USERAUTH_PK_OK', onUSERAUTH_PK_OK);
       break;
       case 'hostbased':
@@ -442,7 +463,7 @@ Client.prototype.connect = function(cfg) {
           cb(signature);
         }
         stream.authHostbased(self.config.username,
-                             privateKey,
+                             publicKey,
                              self.config.localHostname,
                              self.config.localUsername,
                              hostbasedCb);
@@ -569,7 +590,7 @@ Client.prototype.connect = function(cfg) {
         });
       });
     } else if (curAuth === 'publickey') {
-      stream.authPK(self.config.username, privateKey, function(buf, cb) {
+      stream.authPK(self.config.username, publicKey, function(buf, cb) {
         var signature = privateKey.sign(buf);
         if (signature instanceof Error) {
           signature.message = 'Error while signing data with privateKey: '