Description

SSH2 client and server modules written in pure JavaScript for node.js.

Development/testing is done against OpenSSH (8.7 currently).

Changes (breaking or otherwise) in v1.0.0 can be found here.

Table of Contents

• Requirements
• Installation
• Client Examples
  • Execute 'uptime' on a server
  • Start an interactive shell session
  • Send a raw HTTP request to port 80 on the server
  • Forward local connections to port 8000 on the server to us
  • Get a directory listing via SFTP
  • Connection hopping
  • Forward remote X11 connections
  • Dynamic (1:1) port forwarding using a SOCKSv5 proxy (using

    socksv5

    )
  • Make HTTP(S) connections easily using a custom http(s).Agent
  • Invoke an arbitrary subsystem (e.g. netconf)
• Server Examples
  • Password and public key authentication and non-interactive (exec) command execution
  • SFTP-only server
• API
  • Client
    • Client events
    • Client methods
  • Server
    • Server events
    • Server methods
    • Connection events
    • Connection methods
    • Session events
  • Channel
  • Pseudo-TTY settings
  • Terminal modes
  • HTTPAgent
    • HTTPAgent methods
  • HTTPSAgent
    • HTTPSAgent methods
  • Utilities

Requirements

• node.js -- v10.16.0 or newer
  • node v12.0.0 or newer for Ed25519 key support
• (Optional)

  cpu-features

  is set as an optional package dependency (you do not need to install it explicitly/separately from

  ssh2

  ) that will be automatically built and used if possible. See the project's documentation for its own requirements.
  • This addon is currently used to help generate an optimal default cipher list

Installation

npm install ssh2

Client Examples

Execute 'uptime' on a server

const { readFileSync } = require('fs');

const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
  console.log('Client :: ready');
  conn.exec('uptime', (err, stream) => {
    if (err) throw err;
    stream.on('close', (code, signal) => {
      console.log('Stream :: close :: code: ' + code + ', signal: ' + signal);
      conn.end();
    }).on('data', (data) => {
      console.log('STDOUT: ' + data);
    }).stderr.on('data', (data) => {
      console.log('STDERR: ' + data);
    });
  });
}).connect({
  host: '192.168.100.100',
  port: 22,
  username: 'frylock',
  privateKey: readFileSync('/path/to/my/key')
});
// example output:
// Client :: ready
// STDOUT:  17:41:15 up 22 days, 18:09,  1 user,  load average: 0.00, 0.01, 0.05
//
// Stream :: exit :: code: 0, signal: undefined
// Stream :: close

Start an interactive shell session

const { readFileSync } = require('fs');

const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
  console.log('Client :: ready');
  conn.shell((err, stream) => {
    if (err) throw err;
    stream.on('close', () => {
      console.log('Stream :: close');
      conn.end();
    }).on('data', (data) => {
      console.log('OUTPUT: ' + data);
    });
    stream.end('ls -l\nexit\n');
  });
}).connect({
  host: '192.168.100.100',
  port: 22,
  username: 'frylock',
  privateKey: readFileSync('/path/to/my/key')
});
// example output:
// Client :: ready
// STDOUT: Last login: Sun Jun 15 09:37:21 2014 from 192.168.100.100
//
// STDOUT: ls -l
// exit
//
// STDOUT: [email protected]:$ ls -l
//
// STDOUT: total 8
//
// STDOUT: drwxr-xr-x 2 frylock frylock 4096 Nov 18  2012 mydir
//
// STDOUT: -rw-r--r-- 1 frylock frylock   25 Apr 11  2013 test.txt
//
// STDOUT: [email protected]:$ exit
//
// STDOUT: logout
//
// Stream :: close

Send a raw HTTP request to port 80 on the server

const { Client } = require('ssh2');

const conn = new Client();
conn.on('ready', () => {
  console.log('Client :: ready');
  conn.forwardOut('192.168.100.102', 8000, '127.0.0.1', 80, (err, stream) => {
    if (err) throw err;
    stream.on('close', () => {
      console.log('TCP :: CLOSED');
      conn.end();
    }).on('data', (data) => {
      console.log('TCP :: DATA: ' + data);
    }).end([
      'HEAD / HTTP/1.1',
      'User-Agent: curl/7.27.0',
      'Host: 127.0.0.1',
      'Accept: /',
      'Connection: close',
      '',
      ''
    ].join('\r\n'));
  });
}).connect({
  host: '192.168.100.100',
  port: 22,
  username: 'frylock',
  password: 'nodejsrules'
});
// example output:
// Client :: ready
// TCP :: DATA: HTTP/1.1 200 OK
// Date: Thu, 15 Nov 2012 13:52:58 GMT
// Server: Apache/2.2.22 (Ubuntu)
// X-Powered-By: PHP/5.4.6-1ubuntu1
// Last-Modified: Thu, 01 Jan 1970 00:00:00 GMT
// Content-Encoding: gzip
// Vary: Accept-Encoding
// Connection: close
// Content-Type: text/html; charset=UTF-8
//
//
// TCP :: CLOSED

Forward local connections to port 8000 on the server to us

const { Client } = require('ssh2');

const conn = new Client();
conn.on('ready', () => {
  console.log('Client :: ready');
  conn.forwardIn('127.0.0.1', 8000, (err) => {
    if (err) throw err;
    console.log('Listening for connections on server on port 8000!');
  });
}).on('tcp connection', (info, accept, reject) => {
  console.log('TCP :: INCOMING CONNECTION:');
  console.dir(info);
  accept().on('close', () => {
    console.log('TCP :: CLOSED');
  }).on('data', (data) => {
    console.log('TCP :: DATA: ' + data);
  }).end([
    'HTTP/1.1 404 Not Found',
    'Date: Thu, 15 Nov 2012 02:07:58 GMT',
    'Server: ForwardedConnection',
    'Content-Length: 0',
    'Connection: close',
    '',
    ''
  ].join('\r\n'));
}).connect({
  host: '192.168.100.100',
  port: 22,
  username: 'frylock',
  password: 'nodejsrules'
});
// example output:
// Client :: ready
// Listening for connections on server on port 8000!
//  (.... then from another terminal on the server: curl -I http://127.0.0.1:8000)
// TCP :: INCOMING CONNECTION: { destIP: '127.0.0.1',
//  destPort: 8000,
//  srcIP: '127.0.0.1',
//  srcPort: 41969 }
// TCP DATA: HEAD / HTTP/1.1
// User-Agent: curl/7.27.0
// Host: 127.0.0.1:8000
// Accept: /
//
//
// TCP :: CLOSED

Get a directory listing via SFTP

const { Client } = require('ssh2');

const conn = new Client();
conn.on('ready', () => {
  console.log('Client :: ready');
  conn.sftp((err, sftp) => {
    if (err) throw err;
    sftp.readdir('foo', (err, list) => {
      if (err) throw err;
      console.dir(list);
      conn.end();
    });
  });
}).connect({
  host: '192.168.100.100',
  port: 22,
  username: 'frylock',
  password: 'nodejsrules'
});
// example output:
// Client :: ready
// [ { filename: 'test.txt',
//     longname: '-rw-r--r--    1 frylock   frylock         12 Nov 18 11:05 test.txt',
//     attrs:
//      { size: 12,
//        uid: 1000,
//        gid: 1000,
//        mode: 33188,
//        atime: 1353254750,
//        mtime: 1353254744 } },
//   { filename: 'mydir',
//     longname: 'drwxr-xr-x    2 frylock   frylock       4096 Nov 18 15:03 mydir',
//     attrs:
//      { size: 1048576,
//        uid: 1000,
//        gid: 1000,
//        mode: 16877,
//        atime: 1353269007,
//        mtime: 1353269007 } } ]

Connection hopping

const { Client } = require('ssh2');

const conn1 = new Client();
const conn2 = new Client();
// Checks uptime on 10.1.1.40 via 192.168.1.1
conn1.on('ready', () => {
  console.log('FIRST :: connection ready');
  // Alternatively, you could use something like netcat or socat with exec()
  // instead of forwardOut(), depending on what the server allows
  conn1.forwardOut('127.0.0.1', 12345, '10.1.1.40', 22, (err, stream) => {
    if (err) {
      console.log('FIRST :: forwardOut error: ' + err);
      return conn1.end();
    }
    conn2.connect({
      sock: stream,
      username: 'user2',
      password: 'password2',
    });
  });
}).connect({
  host: '192.168.1.1',
  username: 'user1',
  password: 'password1',
});
conn2.on('ready', () => {
  // This connection is the one to 10.1.1.40
  console.log('SECOND :: connection ready');
  conn2.exec('uptime', (err, stream) => {
    if (err) {
      console.log('SECOND :: exec error: ' + err);
      return conn1.end();
    }
    stream.on('close', () => {
      conn1.end(); // close parent (and this) connection
    }).on('data', (data) => {
      console.log(data.toString());
    });
  });
});

Forward remote X11 connections

const { Socket } = require('net');

const { Client } = require('ssh2');
const conn = new Client();
conn.on('x11', (info, accept, reject) => {
  const xserversock = new net.Socket();
  xserversock.on('connect', () => {
    const xclientsock = accept();
    xclientsock.pipe(xserversock).pipe(xclientsock);
  });
  // connects to localhost:0.0
  xserversock.connect(6000, 'localhost');
});
conn.on('ready', () => {
  conn.exec('xeyes', { x11: true }, (err, stream) => {
    if (err) throw err;
    let code = 0;
    stream.on('close', () => {
      if (code !== 0)
        console.log('Do you have X11 forwarding enabled on your SSH server?');
      conn.end();
    }).on('exit', (exitcode) => {
      code = exitcode;
    });
  });
}).connect({
  host: '192.168.1.1',
  username: 'foo',
  password: 'bar'
});

Dynamic (1:1) port forwarding using a SOCKSv5 proxy (using socksv5)

const socks = require('socksv5');
const { Client } = require('ssh2');

const sshConfig = {
  host: '192.168.100.1',
  port: 22,
  username: 'nodejs',
  password: 'rules'
};
socks.createServer((info, accept, deny) => {
  // NOTE: you could just use one ssh2 client connection for all forwards, but
  // you could run into server-imposed limits if you have too many forwards open
  // at any given time
  const conn = new Client();
  conn.on('ready', () => {
    conn.forwardOut(info.srcAddr,
                    info.srcPort,
                    info.dstAddr,
                    info.dstPort,
                    (err, stream) => {
      if (err) {
        conn.end();
        return deny();
      }
  const clientSocket = accept(true);
  if (clientSocket) {
    stream.pipe(clientSocket).pipe(stream).on('close', () => {
      conn.end();
    });
  } else {
    conn.end();
  }
});
  }).on('error', (err) => {
    deny();
  }).connect(sshConfig);
}).listen(1080, 'localhost', () => {
  console.log('SOCKSv5 proxy server started on port 1080');
}).useAuth(socks.auth.None());
// test with cURL:
//   curl -i --socks5 localhost:1080 google.com

Make HTTP(S) connections easily using a custom http(s).Agent

const http = require('http');

const { Client, HTTPAgent, HTTPSAgent } = require('ssh2');
const sshConfig = {
  host: '192.168.100.1',
  port: 22,
  username: 'nodejs',
  password: 'rules'
};
// Use HTTPSAgent instead for an HTTPS request
const agent = new HTTPAgent(sshConfig);
http.get({
  host: '192.168.200.1',
  agent,
  headers: { Connection: 'close' }
}, (res) => {
  console.log(res.statusCode);
  console.dir(res.headers);
  res.resume();
});

Invoke an arbitrary subsystem

const { Client } = require('ssh2');

const xmlhello =    <?xml version="1.0" encoding="UTF-8"?>   <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">     <capabilities>       <capability>urn:ietf:params:netconf:base:1.0</capability>     </capabilities>   </hello>]]&gt;]]&gt;;
const conn = new Client();
conn.on('ready', () => {
  console.log('Client :: ready');
  conn.subsys('netconf', (err, stream) => {
    if (err) throw err;
    stream.on('data', (data) => {
      console.log(data);
    }).write(xmlhello);
  });
}).connect({
  host: '1.2.3.4',
  port: 22,
  username: 'blargh',
  password: 'honk'
});

Server Examples

Password and public key authentication and non-interactive (exec) command execution

const { timingSafeEqual } = require('crypto');
const { readFileSync } = require('fs');
const { inspect } = require('util');

const { utils: { parseKey }, Server } = require('ssh2');
const allowedUser = Buffer.from('foo');
const allowedPassword = Buffer.from('bar');
const allowedPubKey = parseKey(readFileSync('foo.pub'));
function checkValue(input, allowed) {
  const autoReject = (input.length !== allowed.length);
  if (autoReject) {
    // Prevent leaking length information by always making a comparison with the
    // same input when lengths don't match what we expect ...
    allowed = input;
  }
  const isMatch = timingSafeEqual(input, allowed);
  return (!autoReject && isMatch);
}
new Server({
  hostKeys: [readFileSync('host.key')]
}, (client) => {
  console.log('Client connected!');
  client.on('authentication', (ctx) => {
    let allowed = true;
    if (!checkValue(Buffer.from(ctx.username), allowedUser))
      allowed = false;
switch (ctx.method) {
  case 'password':
    if (!checkValue(Buffer.from(ctx.password), allowedPassword))
      return ctx.reject();
    break;
  case 'publickey':
    if (ctx.key.algo !== allowedPubKey.type
        || !checkValue(ctx.key.data, allowedPubKey.getPublicSSH())
        || (ctx.signature && allowedPubKey.verify(ctx.blob, ctx.signature) !== true)) {
      return ctx.reject();
    }
    break;
  default:
    return ctx.reject();
}

if (allowed)
  ctx.accept();
else
  ctx.reject();
  }).on('ready', () => {
    console.log('Client authenticated!');
client.on('session', (accept, reject) => {
  const session = accept();
  session.once('exec', (accept, reject, info) => {
    console.log('Client wants to execute: ' + inspect(info.command));
    const stream = accept();
    stream.stderr.write('Oh no, the dreaded errors!\n');
    stream.write('Just kidding about the errors!\n');
    stream.exit(0);
    stream.end();
  });
});
  }).on('close', () => {
    console.log('Client disconnected');
  });
}).listen(0, '127.0.0.1', function() {
  console.log('Listening on port ' + this.address().port);
});

SFTP-only server

const { timingSafeEqual } = require('crypto');
const { readFileSync } = require('fs');
const { inspect } = require('util');

const {
  Server,
  sftp: {
    OPEN_MODE,
    STATUS_CODE,
  },
} = require('ssh2');
const allowedUser = Buffer.from('foo');
const allowedPassword = Buffer.from('bar');
function checkValue(input, allowed) {
  const autoReject = (input.length !== allowed.length);
  if (autoReject) {
    // Prevent leaking length information by always making a comparison with the
    // same input when lengths don't match what we expect ...
    allowed = input;
  }
  const isMatch = timingSafeEqual(input, allowed);
  return (!autoReject && isMatch);
}
// This simple SFTP server implements file uploading where the contents get
// ignored ...
new ssh2.Server({
  hostKeys: [readFileSync('host.key')]
}, (client) => {
  console.log('Client connected!');
  client.on('authentication', (ctx) => {
    let allowed = true;
    if (!checkValue(Buffer.from(ctx.username), allowedUser))
      allowed = false;
switch (ctx.method) {
  case 'password':
    if (!checkValue(Buffer.from(ctx.password), allowedPassword))
      return ctx.reject();
    break;
  default:
    return ctx.reject();
}

if (allowed)
  ctx.accept();
else
  ctx.reject();
  }).on('ready', () => {
    console.log('Client authenticated!');
client.on('session', (accept, reject) => {
  const session = accept();
  session.on('sftp', (accept, reject) => {
    console.log('Client SFTP session');
    const openFiles = new Map();
    let handleCount = 0;
    const sftp = accept();
    sftp.on('OPEN', (reqid, filename, flags, attrs) => {
      // Only allow opening /tmp/foo.txt for writing
      if (filename !== '/tmp/foo.txt' || !(flags & OPEN_MODE.WRITE))
        return sftp.status(reqid, STATUS_CODE.FAILURE);

      // Create a fake handle to return to the client, this could easily
      // be a real file descriptor number for example if actually opening
      // a file on disk
      const handle = Buffer.alloc(4);
      openFiles.set(handleCount, true);
      handle.writeUInt32BE(handleCount++, 0);

      console.log('Opening file for write')
      sftp.handle(reqid, handle);
    }).on('WRITE', (reqid, handle, offset, data) => {
      if (handle.length !== 4
          || !openFiles.has(handle.readUInt32BE(0))) {
        return sftp.status(reqid, STATUS_CODE.FAILURE);
      }

      // Fake the write operation
      sftp.status(reqid, STATUS_CODE.OK);

      console.log('Write to file at offset ${offset}: ${inspect(data)}');
    }).on('CLOSE', (reqid, handle) => {
      let fnum;
      if (handle.length !== 4
          || !openFiles.has(fnum = handle.readUInt32BE(0))) {
        return sftp.status(reqid, STATUS_CODE.FAILURE);
      }

      console.log('Closing file');
      openFiles.delete(fnum);

      sftp.status(reqid, STATUS_CODE.OK);
    });
  });
});
  }).on('close', () => {
    console.log('Client disconnected');
  });
}).listen(0, '127.0.0.1', function() {
  console.log('Listening on port ' + this.address().port);
});

You can find more examples in the

examples

API

require('ssh2').Client

require('ssh2').Server

require('ssh2').utils

require('ssh2').HTTPAgent

http.Agent

require('ssh2').HTTPSAgent

https.Agent

HTTPAgent

Agent-related

require('ssh2').AgentProtocol

require('ssh2').BaseAgent

require('ssh2').createAgent

agent

PageantAgent

CygwinAgent

OpenSSHAgent

require('ssh2').CygwinAgent

require('ssh2').OpenSSHAgent

require('ssh2').PageantAgent

Client

Client events

• banner(< string >message, < string >language) - A notice was sent by the server upon connection.

• change password(< string >prompt, < function >done) - If using password-based user authentication, the server has requested that the user's password be changed. Call

  done

  with the new password.

• close() - The socket was closed.

• end() - The socket was disconnected.

• error(< Error >err) - An error occurred. A 'level' property indicates 'client-socket' for socket-level errors and 'client-ssh' for SSH disconnection messages. In the case of 'client-ssh' messages, there may be a 'description' property that provides more detail.

• handshake(< object >negotiated) - Emitted when a handshake has completed (either initial or rekey).

  negotiated

  contains the negotiated details of the handshake and is of the form:

    // In this particular case `mac` is empty because there is no separate MAC
    // because it's integrated into AES in GCM mode
    { kex: 'ecdh-sha2-nistp256',
      srvHostKey: 'rsa-sha2-512',
      cs: { // Client to server algorithms
        cipher: 'aes128-gcm',
        mac: '',
        compress: 'none',
        lang: ''
      },
      sc: { // Server to client algorithms
        cipher: 'aes128-gcm',
        mac: '',
        compress: 'none',
        lang: ''
      }
    }

• hostkeys(< array >keys) - Emitted when the server announces its available host keys.

  keys

  is the list of parsed (using

  parseKey()

  ) host public keys.

• keyboard-interactive(< string >name, < string >instructions, < string >instructionsLang, < array >prompts, < function >finish) - The server is asking for replies to the given

  prompts

  for keyboard-interactive user authentication.

  name

  is generally what you'd use as a window title (for GUI apps).

  prompts

  is an array of

  { prompt: 'Password: ', echo: false }

  style objects (here

  echo

  indicates whether user input should be displayed on the screen). The answers for all prompts must be provided as an array of strings and passed to

  finish

  when you are ready to continue. Note: It's possible for the server to come back and ask more questions.

• ready() - Authentication was successful.

• rekey() - Emitted when a rekeying operation has completed (either client or server-initiated).

• tcp connection(< object >details, < function >accept, < function >reject) - An incoming forwarded TCP connection is being requested. Calling

  accept

  accepts the connection and returns a

  Channel

  object. Calling

  reject

  rejects the connection and no further action is needed.

  details

  contains:
  • destIP - string - The remote IP the connection was received on (given in earlier call to

    forwardIn()

    ).
  • destPort - integer - The remote port the connection was received on (given in earlier call to

    forwardIn()

    ).
  • srcIP - string - The originating IP of the connection.
  • srcPort - integer - The originating port of the connection.

• unix connection(< object >details, < function >accept, < function >reject) - An incoming forwarded UNIX socket connection is being requested. Calling

  accept

  accepts the connection and returns a

  Channel

  object. Calling

  reject

  rejects the connection and no further action is needed.

  details

  contains:
  • socketPath - string - The originating UNIX socket path of the connection.

• x11(< object >details, < function >accept, < function >reject) - An incoming X11 connection is being requested. Calling

  accept

  accepts the connection and returns a

  Channel

  object. Calling

  reject

  rejects the connection and no further action is needed.

  details

  contains:
  • srcIP - string - The originating IP of the connection.
  • srcPort - integer - The originating port of the connection.

Client methods

• (constructor)() - Creates and returns a new Client instance.

• connect(< object >config) - (void) - Attempts a connection to a server using the information given in

  config

  :
  • agent - string - Path to ssh-agent's UNIX socket for ssh-agent-based user authentication. Windows users: set to 'pageant' for authenticating with Pageant or (actual) path to a cygwin "UNIX socket." Default: (none)
  • agentForward - boolean - Set to

    true

    to use OpenSSH agent forwarding (

    [email protected]

    ) for the life of the connection.

    agent

    must also be set to use this feature. Default:

    false

  • algorithms - object - This option allows you to explicitly override the default transport layer algorithms used for the connection. The value for each category must either be an array of valid algorithm names to set an exact list (with the most preferable first) or an object containing

    append

    ,

    prepend

    , and/or

    remove

    properties that each contain an array of algorithm names or RegExps to match to adjust default lists for each category. Valid keys:
    • cipher - mixed - Ciphers.
      • Default list (in order from most to least preferable):

        • [email protected]

          (priority of chacha20-poly1305 may vary depending upon CPU and/or optional binding availability)

        • aes128-gcm

        • [email protected]

        • aes256-gcm

        • [email protected]

        • aes128-ctr

        • aes192-ctr

        • aes256-ctr

      • Other supported names:

        • 3des-cbc

        • aes256-cbc

        • aes192-cbc

        • aes128-cbc

        • arcfour256

        • arcfour128

        • arcfour

        • blowfish-cbc

        • cast128-cbc

    • compress - mixed - Compression algorithms.
      • Default list (in order from most to least preferable):

        • none

        • [email protected]

        • zlib

      • Other supported names:
    • hmac - mixed - (H)MAC algorithms.
      • Default list (in order from most to least preferable):

        • [email protected]

        • [email protected]

        • [email protected]

        • hmac-sha2-256

        • hmac-sha2-512

        • hmac-sha1

      • Other supported names:

        • hmac-md5

        • hmac-sha2-256-96

        • hmac-sha2-512-96

        • hmac-ripemd160

        • hmac-sha1-96

        • hmac-md5-96

    • kex - mixed - Key exchange algorithms.
      • Default list (in order from most to least preferable):

        • curve25519-sha256

          (node v14.0.0+)

        • [email protected]

          (node v14.0.0+)

        • ecdh-sha2-nistp256

        • ecdh-sha2-nistp384

        • ecdh-sha2-nistp521

        • diffie-hellman-group-exchange-sha256

        • diffie-hellman-group14-sha256

        • diffie-hellman-group15-sha512

        • diffie-hellman-group16-sha512

        • diffie-hellman-group17-sha512

        • diffie-hellman-group18-sha512

      • Other supported names:

        • diffie-hellman-group-exchange-sha1

        • diffie-hellman-group14-sha1

        • diffie-hellman-group1-sha1

    • serverHostKey - mixed - Server host key formats.
      • Default list (in order from most to least preferable):

        • ssh-ed25519

          (node v12.0.0+)

        • ecdsa-sha2-nistp256

        • ecdsa-sha2-nistp384

        • ecdsa-sha2-nistp521

        • rsa-sha2-512

        • rsa-sha2-256

        • ssh-rsa

      • Other supported names:

        • ssh-dss

  • authHandler - mixed - Either an array of objects as described below or a function with parameters

    (methodsLeft, partialSuccess, callback)

    where

    methodsLeft

    and

    partialSuccess

    are

    null

    on the first authentication attempt, otherwise are an array and boolean respectively. Return or call

    callback()

    with either the name of the authentication method or an object containing the method name along with method-specific details to try next (return/pass

    false

    to signal no more methods to try). Valid method names are:

    'none', 'password', 'publickey', 'agent', 'keyboard-interactive', 'hostbased'

    . Default: function that follows a set method order: None -> Password -> Private Key -> Agent (-> keyboard-interactive if

    tryKeyboard

    is

    true

    ) -> Hostbased

    • When returning or calling

      callback()

      with an object, it can take one of the following forms:

      {
        type: 'none',
        username: 'foo',
      }
      

      {
        type: 'password'
        username: 'foo',
        password: 'bar',
      }
      

      {
        type: 'publickey'
        username: 'foo',
        // Can be a string, Buffer, or parsed key containing a private key
        key: ...,
        // `passphrase` only required for encrypted keys
        passphrase: ...,
      }
      

      {
        type: 'hostbased'
        username: 'foo',
        localHostname: 'baz',
        localUsername: 'quux',
        // Can be a string, Buffer, or parsed key containing a private key
        key: ...,
        // `passphrase` only required for encrypted keys
        passphrase: ...,
      }
      

      {
        type: 'agent'
        username: 'foo',
        // Can be a string that is interpreted exactly like the `agent`
        // connection config option or can be a custom agent
        // object/instance that extends and implements `BaseAgent`
        agent: ...,
      }
      

      {
        type: 'keyboard-interactive'
        username: 'foo',
        // This works exactly the same way as a 'keyboard-interactive'
        // Client event handler
        prompt: (name, instructions, instructionsLang, prompts, finish) => {
          // ...
        },
      }
      

  • debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)

  • forceIPv4 - boolean - Only connect via resolved IPv4 address for

    host

    . Default:

    false

  • forceIPv6 - boolean - Only connect via resolved IPv6 address for

    host

    . Default:

    false

  • host - string - Hostname or IP address of the server. Default:

    'localhost'

  • hostHash - string - Any valid hash algorithm supported by node. The host's key is hashed using this algorithm and passed to the hostVerifier function as a hex string. Default: (none)

  • hostVerifier - function - Function with parameters

    (hashedKey[, callback])

    where

    hashedKey

    is a string hex hash of the host's key for verification purposes. Return

    true

    to continue with the handshake or

    false

    to reject and disconnect, or call

    callback()

    with

    true

    or

    false

    if you need to perform asynchronous verification. Default: (auto-accept if

    hostVerifier

    is not set)

  • keepaliveCountMax - integer - How many consecutive, unanswered SSH-level keepalive packets that can be sent to the server before disconnection (similar to OpenSSH's ServerAliveCountMax config option). Default:

    3

  • keepaliveInterval - integer - How often (in milliseconds) to send SSH-level keepalive packets to the server (in a similar way as OpenSSH's ServerAliveInterval config option). Set to 0 to disable. Default:

    0

  • localAddress - string - IP address of the network interface to use to connect to the server. Default: (none -- determined by OS)

  • localHostname - string - Along with localUsername and privateKey, set this to a non-empty string for hostbased user authentication. Default: (none)

  • localPort - string - The local port number to connect from. Default: (none -- determined by OS)

  • localUsername - string - Along with localHostname and privateKey, set this to a non-empty string for hostbased user authentication. Default: (none)

  • passphrase - string - For an encrypted

    privateKey

    , this is the passphrase used to decrypt it. Default: (none)

  • password - string - Password for password-based user authentication. Default: (none)

  • port - integer - Port number of the server. Default:

    22

  • privateKey - mixed - Buffer or string that contains a private key for either key-based or hostbased user authentication (OpenSSH format). Default: (none)

  • readyTimeout - integer - How long (in milliseconds) to wait for the SSH handshake to complete. Default:

    20000

  • sock - ReadableStream - A ReadableStream to use for communicating with the server instead of creating and using a new TCP connection (useful for connection hopping).

  • strictVendor - boolean - Performs a strict server vendor check before sending vendor-specific requests, etc. (e.g. check for OpenSSH server when using

    openssh_noMoreSessions()

    ) Default:

    true

  • tryKeyboard - boolean - Try keyboard-interactive user authentication if primary user authentication method fails. If you set this to

    true

    , you need to handle the

    keyboard-interactive

    event. Default:

    false

  • username - string - Username for authentication. Default: (none)

• end() - (void) - Disconnects the socket.

• exec(< string >command[, < object >options], < function >callback) - (void) - Executes

  command

  on the server.

  callback

  has 2 parameters: < Error >err, < Channel >stream. Valid

  options

  properties are:
  • env - object - An environment to use for the execution of the command.
  • pty - mixed - Set to

    true

    to allocate a pseudo-tty with defaults, or an object containing specific pseudo-tty settings (see 'Pseudo-TTY settings'). Setting up a pseudo-tty can be useful when working with remote processes that expect input from an actual terminal (e.g. sudo's password prompt).

  • x11 - mixed - Set to

    true

    to use defaults below, set to a number to specify a specific screen number, or an object with the following valid properties:
    • cookie - mixed - The authentication cookie. Can be a hex string or a Buffer containing the raw cookie value (which will be converted to a hex string). Default: (random 16 byte value)
    • protocol - string - The authentication protocol name. Default:

      'MIT-MAGIC-COOKIE-1'

    • screen - number - Screen number to use Default:

      0

    • single - boolean - Allow just a single connection? Default:

      false

• forwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Bind to

  remoteAddr

  on

  remotePort

  on the server and forward incoming TCP connections.

  callback

  has 2 parameters: < Error >err, < integer >port (

  port

  is the assigned port number if

  remotePort

  was 0). Here are some special values for

  remoteAddr

  and their associated binding behaviors:
  • '' - Connections are to be accepted on all protocol families supported by the server.
  • '0.0.0.0' - Listen on all IPv4 addresses.
  • '::' - Listen on all IPv6 addresses.
  • 'localhost' - Listen on all protocol families supported by the server on loopback addresses only.
  • '127.0.0.1' and '::1' - Listen on the loopback interfaces for IPv4 and IPv6, respectively.

• forwardOut(< string >srcIP, < integer >srcPort, < string >dstIP, < integer >dstPort, < function >callback) - (void) - Open a connection with

  srcIP

  and

  srcPort

  as the originating address and port and

  dstIP

  and

  dstPort

  as the remote destination address and port.

  callback

  has 2 parameters: < Error >err, < Channel >stream.

• openssh_forwardInStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that binds to a UNIX domain socket at

  socketPath

  on the server and forwards incoming connections.

  callback

  has 1 parameter: < Error >err.

• openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that opens a connection to a UNIX domain socket at

  socketPath

  on the server.

  callback

  has 2 parameters: < Error >err, < Channel >stream.

• openssh_noMoreSessions(< function >callback) - (void) - OpenSSH extension that sends a request to reject any new sessions (e.g. exec, shell, sftp, subsys) for this connection.

  callback

  has 1 parameter: < Error >err.

• openssh_unforwardInStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that unbinds from a UNIX domain socket at

  socketPath

  on the server and stops forwarding incoming connections.

  callback

  has 1 parameter: < Error >err.

• rekey([< function >callback]) - (void) - Initiates a rekey with the server. If

  callback

  is supplied, it is added as a one-time handler for the

  rekey

  event.

• sftp(< function >callback) - (void) - Starts an SFTP session.

  callback

  has 2 parameters: < Error >err, < SFTP >sftp. For methods available on

  sftp

  , see the

  SFTP

  client documentation.

• shell([[< mixed >window,] < object >options]< function >callback) - (void) - Starts an interactive shell session on the server, with an optional

  window

  object containing pseudo-tty settings (see 'Pseudo-TTY settings'). If

  window === false

  , then no pseudo-tty is allocated.

  options

  supports the

  x11

  and

  env

  options as described in

  exec()

  .

  callback

  has 2 parameters: < Error >err, < Channel >stream.

• subsys(< string >subsystem, < function >callback) - (void) - Invokes

  subsystem

  on the server.

  callback

  has 2 parameters: < Error >err, < Channel >stream.

• unforwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Unbind from

  remoteAddr

  on

  remotePort

  on the server and stop forwarding incoming TCP connections. Until

  callback

  is called, more connections may still come in.

  callback

  has 1 parameter: < Error >err.

Server

Server events

• connection(< Connection >client, < object >info) - A new client has connected.

  info

  contains the following properties:
  • family - string - The

    remoteFamily

    of the connection.

  • header - object - Information about the client's header:

    • identRaw - string - The raw client identification string.

    • versions - object - Various version information:

      • protocol - string - The SSH protocol version (always

        1.99

        or

        2.0

        ).
      • software - string - The software name and version of the client.

    • comments - string - Any text that comes after the software name/version.

  Example: the identification string

  SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2

  would be parsed as:

        { identRaw: 'SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2',
          version: {
            protocol: '2.0',
            software: 'OpenSSH_6.6.1p1'
          },
          comments: 'Ubuntu-2ubuntu2' }

* **ip** - _string_ - The `remoteAddress` of the connection.


port - integer - The remotePort of the connection.

Server methods

• (constructor)(< object >config[, < function >connectionListener]) - Creates and returns a new Server instance. Server instances also have the same methods/properties/events as

  net.Server

  .

  connectionListener

  if supplied, is added as a

  connection

  listener. Valid

  config

  properties:

  • algorithms - object - This option allows you to explicitly override the default transport layer algorithms used for incoming client connections. Each value must be an array of valid algorithms for that category. The order of the algorithms in the arrays are important, with the most favorable being first. For a list of valid and default algorithm names, please review the documentation for the version of

    ssh2

    used by this module. Valid keys:
    • cipher - array - Ciphers.
    • compress - array - Compression algorithms.
    • hmac - array - (H)MAC algorithms.
    • kex - array - Key exchange algorithms.
    • serverHostKey - array - Server host key formats.

  • banner - string - A message that is sent to clients once, right before authentication begins. Default: (none)

  • debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)

  • greeting - string - A message that is sent to clients immediately upon connection, before handshaking begins. Note: Most clients usually ignore this. Default: (none)

  • highWaterMark - integer - This is the

    highWaterMark

    to use for the parser stream. Default:

    32 * 1024

  • hostKeys - array - An array of either Buffers/strings that contain host private keys or objects in the format of

    { key: , passphrase:  }

    for encrypted private keys. (Required) Default: (none)

  • ident - string - A custom server software name/version identifier. Default:

    'ssh2js' + moduleVersion + 'srv'

• injectSocket(< DuplexStream >socket) - Injects a bidirectional stream as though it were a TCP socket connection. Additionally,

  socket

  should include

  net.Socket

  -like properties to ensure the best compatibility (e.g.

  socket.remoteAddress

  ,

  socket.remotePort

  ,

  socket.remoteFamily

  ).

Connection events

• authentication(< AuthContext >ctx) - The client has requested authentication.

  ctx.username

  contains the client username,

  ctx.method

  contains the requested authentication method, and

  ctx.accept()

  and

  ctx.reject([< Array >authMethodsLeft[, < Boolean >isPartialSuccess]])

  are used to accept or reject the authentication request respectively.

  abort

  is emitted if the client aborts the authentication request. Other properties/methods available on

  ctx

  depends on the

  ctx.method

  of authentication the client has requested:

  • hostbased

    :
    • blob - Buffer - This contains the data to be verified that is passed to (along with the signature)

      key.verify()

      where

      key

      is a public key parsed with

      parseKey()

      .

    • key - object - Contains information about the public key sent by the client:

      • algo - string - The name of the key algorithm (e.g.

        ssh-rsa

        ).
      • data - Buffer - The actual key data.

    • localHostname - string - The local hostname provided by the client.

    • localUsername - string - The local username provided by the client.

    • signature - Buffer - This contains a signature to be verified that is passed to (along with the blob)

      key.verify()

      where

      key

      is a public key parsed with

      parseKey()

      .

  • keyboard-interactive

    :
    • prompt(< array >prompts[, < string >title[, < string >instructions]], < function >callback) - (void) - Send prompts to the client.

      prompts

      is an array of

      { prompt: 'Prompt text', echo: true }

      objects (

      prompt

      being the prompt text and

      echo

      indicating whether the client's response to the prompt should be echoed to their display).

      callback

      is called with

      (responses)

      , where

      responses

      is an array of string responses matching up to the

      prompts

      .
    • submethods - array - A list of preferred authentication "sub-methods" sent by the client. This may be used to determine what (if any) prompts to send to the client.

  • password

    :
    • password - string - This is the password sent by the client.
    • requestChange(< string >prompt, < function >callback) - (void) - Sends a password change request to the client.

      callback

      is called with

      (newPassword)

      , where

      newPassword

      is the new password supplied by the client. You may accept, reject, or prompt for another password change after

      callback

      is called.

  • publickey

    :
    • blob - mixed - If the value is

      undefined

      , the client is only checking the validity of the

      key

      . If the value is a Buffer, then this contains the data to be verified that is passed to (along with the signature)

      key.verify()

      where

      key

      is a public key parsed with

      parseKey()

      .

    • key - object - Contains information about the public key sent by the client:

      • algo - string - The name of the key algorithm (e.g.

        ssh-rsa

        ).
      • data - Buffer - The actual key data.

    • signature - mixed - If the value is

      undefined

      , the client is only checking the validity of the

      key

      . If the value is a Buffer, then this contains a signature to be verified that is passed to (along with the blob)

      key.verify()

      where

      key

      is a public key parsed with

      parseKey()

      .

• close() - The client socket was closed.

• end() - The client socket disconnected.

• error(< Error >err) - An error occurred.

• handshake(< object >negotiated) - Emitted when a handshake has completed (either initial or rekey).

  negotiated

  contains the negotiated details of the handshake and is of the form:

    // In this particular case `mac` is empty because there is no separate MAC
    // because it's integrated into AES in GCM mode
    { kex: 'ecdh-sha2-nistp256',
      srvHostKey: 'rsa-sha2-512',
      cs: { // Client to server algorithms
        cipher: 'aes128-gcm',
        mac: '',
        compress: 'none',
        lang: ''
      },
      sc: { // Server to client algorithms
        cipher: 'aes128-gcm',
        mac: '',
        compress: 'none',
        lang: ''
      }
    }

• openssh.streamlocal(< function >accept, < function >reject, < object >info) - Emitted when the client has requested a connection to a UNIX domain socket.

  accept()

  returns a new Channel instance representing the connection.

  info

  contains:
  • socketPath - string - Destination socket path of outgoing connection.

• ready() - Emitted when the client has been successfully authenticated.

• rekey() - Emitted when a rekeying operation has completed (either client or server-initiated).

• request(< mixed >accept, < mixed >reject, < string >name, < object >info) - Emitted when the client has sent a global request for

  name

  (e.g.

  tcpip-forward

  or

  cancel-tcpip-forward

  ).

  accept

  and

  reject

  are functions if the client requested a response. If

  bindPort === 0

  , you should pass the chosen port to

  accept()

  so that the client will know what port was bound.

  info

  contains additional details about the request:

  • cancel-tcpip-forward

    and

    tcpip-forward

    :
    • bindAddr - string - The IP address to start/stop binding to.
    • bindPort - integer - The port to start/stop binding to.

  • [email protected]

    and

    [email protected]

    :
    • socketPath - string - The socket path to start/stop binding to.

• session(< function >accept, < function >reject) - Emitted when the client has requested a new session. Sessions are used to start interactive shells, execute commands, request X11 forwarding, etc.

  accept()

  returns a new Session instance.

• tcpip(< function >accept, < function >reject, < object >info) - Emitted when the client has requested an outbound (TCP) connection.

  accept()

  returns a new Channel instance representing the connection.

  info

  contains:
  • destIP - string - Destination IP address of outgoing connection.
  • destPort - string - Destination port of outgoing connection.
  • srcIP - string - Source IP address of outgoing connection.
  • srcPort - string - Source port of outgoing connection.

Connection methods

• end() - (void) - Closes the client connection.

• forwardOut(< string >boundAddr, < integer >boundPort, < string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Alert the client of an incoming TCP connection on

  boundAddr

  on port

  boundPort

  from

  remoteAddr

  on port

  remotePort

  .

  callback

  has 2 parameters: < Error >err, < Channel >stream.

• openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - (void) - Alert the client of an incoming UNIX domain socket connection on

  socketPath

  .

  callback

  has 2 parameters: < Error >err, < Channel >stream.

• rekey([< function >callback]) - (void) - Initiates a rekey with the client. If

  callback

  is supplied, it is added as a one-time handler for the

  rekey

  event.

• x11(< string >originAddr, < integer >originPort, < function >callback) - (void) - Alert the client of an incoming X11 client connection from

  originAddr

  on port

  originPort

  .

  callback

  has 2 parameters: < Error >err, < Channel >stream.

Session events

• auth-agent(< mixed >accept, < mixed >reject) - The client has requested incoming ssh-agent requests be forwarded to them.

  accept

  and

  reject

  are functions if the client requested a response.

• close() - The session was closed.

• env(< mixed >accept, < mixed >reject, < object >info) - The client requested an environment variable to be set for this session.

  accept

  and

  reject

  are functions if the client requested a response.

  info

  has these properties:
  • key - string - The environment variable's name.
  • value - string - The environment variable's value.

• exec(< mixed >accept, < mixed >reject, < object >info) - The client has requested execution of a command string.

  accept

  and

  reject

  are functions if the client requested a response.

  accept()

  returns a Channel for the command execution.

  info

  has these properties:
  • command - string - The command line to be executed.

• pty(< mixed >accept, < mixed >reject, < object >info) - The client requested allocation of a pseudo-TTY for this session.

  accept

  and

  reject

  are functions if the client requested a response.

  info

  has these properties:
  • cols - integer - The number of columns for the pseudo-TTY.
  • height - integer - The height of the pseudo-TTY in pixels.
  • modes - object - Contains the requested terminal modes of the pseudo-TTY keyed on the mode name with the value being the mode argument. (See the table at the end for valid names).
  • rows - integer - The number of rows for the pseudo-TTY.
  • width - integer - The width of the pseudo-TTY in pixels.

• sftp(< mixed >accept, < mixed >reject) - The client has requested the SFTP subsystem.

  accept

  and

  reject

  are functions if the client requested a response.

  accept()

  returns an SFTP instance in server mode (see the

  SFTP

  documentation for details).

  info

  has these properties:

• shell(< mixed >accept, < mixed >reject) - The client has requested an interactive shell.

  accept

  and

  reject

  are functions if the client requested a response.

  accept()

  returns a Channel for the interactive shell.

• signal(< mixed >accept, < mixed >reject, < object >info) - The client has sent a signal.

  accept

  and

  reject

  are functions if the client requested a response.

  info

  has these properties:
  • name - string - The signal name (e.g.

    SIGUSR1

    ).

• subsystem(< mixed >accept, < mixed >reject, < object >info) - The client has requested an arbitrary subsystem.

  accept

  and

  reject

  are functions if the client requested a response.

  accept()

  returns a Channel for the subsystem.

  info

  has these properties:
  • name - string - The name of the subsystem.

• window-change(< mixed >accept, < mixed >reject, < object >info) - The client reported a change in window dimensions during this session.

  accept

  and

  reject

  are functions if the client requested a response.

  info

  has these properties:
  • cols - integer - The new number of columns for the client window.
  • height - integer - The new height of the client window in pixels.
  • rows - integer - The new number of rows for the client window.
  • width - integer - The new width of the client window in pixels.

• x11(< mixed >accept, < mixed >reject, < object >info) - The client requested X11 forwarding.

  accept

  and

  reject

  are functions if the client requested a response.

  info

  has these properties:
  • cookie - string - The X11 authentication cookie encoded in hexadecimal.
  • protocol - string - The name of the X11 authentication method used (e.g.

    MIT-MAGIC-COOKIE-1

    ).
  • screen - integer - The screen number to forward X11 connections for.
  • single - boolean -

    true

    if only a single connection should be forwarded.

Channel

This is a normal streams2 Duplex Stream (used both by clients and servers), with the following changes:

• A boolean property

  allowHalfOpen

  exists and behaves similarly to the property of the same name for

  net.Socket

  . When the stream's end() is called, if

  allowHalfOpen

  is

  true

  , only EOF will be sent (the server can still send data if they have not already sent EOF). The default value for this property is

  true

  .

• A

  close

  event is emitted once the channel is completely closed on both the client and server.

• Client-specific:

  • For exec():

    • An

      exit

      event may (the SSH2 spec says it is optional) be emitted when the process finishes. If the process finished normally, the process's return value is passed to the

      exit

      callback. If the process was interrupted by a signal, the following are passed to the

      exit

      callback: null, < string >signalName, < boolean >didCoreDump, < string >description.
    • If there was an

      exit

      event, the

      close

      event will be passed the same arguments for convenience.
    • A

      stderr

      property contains a Readable stream that represents output from stderr.

  • For exec() and shell():

    • The readable side represents stdout and the writable side represents stdin.
    • setWindow(< integer >rows, < integer >cols, < integer >height, < integer >width) - (void) - Lets the server know that the local terminal window has been resized. The meaning of these arguments are described in the 'Pseudo-TTY settings' section.
    • signal(< string >signalName) - (void) - Sends a POSIX signal to the current process on the server. Valid signal names are: 'ABRT', 'ALRM', 'FPE', 'HUP', 'ILL', 'INT', 'KILL', 'PIPE', 'QUIT', 'SEGV', 'TERM', 'USR1', and 'USR2'. Some server implementations may ignore this request if they do not support signals. Note: If you are trying to send SIGINT and you find

      signal()

      doesn't work, try writing

      '\x03'

      to the Channel stream instead.

• Server-specific:

  • For exec-enabled channel instances there is an additional method available that may be called right before you close the channel. It has two different signatures:

    • exit(< integer >exitCode) - (void) - Sends an exit status code to the client.
    • exit(< string >signalName[, < boolean >coreDumped[, < string >errorMsg]]) - (void) - Sends an exit status code to the client.

  • For exec and shell-enabled channel instances,

    channel.stderr

    is a writable stream.

Pseudo-TTY settings

• cols - < integer > - Number of columns. Default:

  80

• height - < integer > - Height in pixels. Default:

  480

• modes - < object > - An object containing Terminal Modes as keys, with each value set to each mode argument. Default:

  null

• rows - < integer > - Number of rows. Default:

  24

• term - < string > - The value to use for $TERM. Default:

  'vt100'

• width - < integer > - Width in pixels. Default:

  640

rows

cols

width

height

rows

cols

Pixel dimensions refer to the drawable area of the window.

Zero dimension parameters are ignored.

Terminal modes

HTTPAgent

HTTPAgent methods

• (constructor)(< object >sshConfig[, < object >agentConfig]) - Creates and returns a new

  http.Agent

  instance used to tunnel an HTTP connection over SSH.

  sshConfig

  is what is passed to

  client.connect()

  and

  agentOptions

  is passed to the

  http.Agent

  constructor.

HTTPSAgent

HTTPSAgent methods

• (constructor)(< object >sshConfig[, < object >agentConfig]) - Creates and returns a new

  https.Agent

  instance used to tunnel an HTTP connection over SSH.

  sshConfig

  is what is passed to

  client.connect()

  and

  agentOptions

  is passed to the

  https.Agent

  constructor.

Utilities

• parseKey(< mixed >keyData[, < string >passphrase]) - mixed - Parses a private/public key in OpenSSH, RFC4716, or PPK format. For encrypted private keys, the key will be decrypted with the given

  passphrase

  .

  keyData

  can be a Buffer or string value containing the key contents. The returned value will be an array of objects (currently in the case of modern OpenSSH keys) or an object with these properties and methods:
  • comment - string - The comment for the key
  • equals(< mixed >otherKey) - boolean - This returns

    true

    if

    otherKey

    (a parsed or parseable key) is the same as this key. This method does not compare the keys' comments
  • getPrivatePEM() - string - This returns the PEM version of a private key
  • getPublicPEM() - string - This returns the PEM version of a public key (for either public key or derived from a private key)
  • getPublicSSH() - string - This returns the SSH version of a public key (for either public key or derived from a private key)
  • isPrivateKey() - boolean - This returns

    true

    if the key is a private key or not
  • sign(< mixed >data) - mixed - This signs the given

    data

    using this key and returns a Buffer containing the signature on success. On failure, an Error will be returned.

    data

    can be anything accepted by node's

    sign.update()

    .
  • type - string - The full key type (e.g.

    'ssh-rsa'

    )
  • verify(< mixed >data, < Buffer >signature) - mixed - This verifies a

    signature

    of the given

    data

    using this key and returns

    true

    if the signature could be verified. On failure, either

    false

    will be returned or an Error will be returned upon a more critical failure.

    data

    can be anything accepted by node's

    verify.update()

    .

• sftp.OPEN_MODE -

  OPEN_MODE

• sftp.STATUS_CODE -

  STATUS_CODE

• sftp.flagsToString -

  flagsToString()

• sftp.stringToFlags -

  stringToFlags()

AgentProtocol

AgentProtocol events

• identities(< opaque >request) - (Server mode only) The client has requested a list of public keys stored in the agent. Use

  failureReply()

  or

  getIdentitiesReply()

  to reply appropriately.

• sign(< opaque >request, < mixed >pubKey, < Buffer >data, < object >options) - (Server mode only) The client has requested

  data

  to be signed using the key identified by

  pubKey

  . Use

  failureReply()

  or

  signReply()

  to reply appropriately.

  options

  may contain any of:
  • hash - string - The explicitly desired hash to use when computing the signature. Currently if set, this may be either

    'sha256'

    or

    'sha512'

    for RSA keys.

AgentProtocol methods

• (constructor)(< boolean >isClient) - Creates and returns a new AgentProtocol instance.

  isClient

  determines whether the instance operates in client or server mode.

• failureReply(< opaque >request) - (void) - (Server mode only) Replies to the given

  request

  with a failure response.

• getIdentities(< function >callback) - (void) - (Client mode only) Requests a list of public keys from the agent.

  callback

  is passed

  (err, keys)

  where

  keys

  is a possible array of public keys for authentication.

• getIdentitiesReply(< opaque >request, < array >keys) - (void) - (Server mode only) Responds to a identities list

  request

  with the given array of keys in

  keys

  .

• sign(< mixed >pubKey, < Buffer >data, < object >options, < function >callback) - (void) - (Client mode only) Requests that the agent sign

  data

  using the key identified by

  pubKey

  .

  pubKey

  can be any parsed (using

  utils.parseKey()

  ) or parseable key value.

  callback

  is passed

  (err, signature)

  where

  signature

  is a possible Buffer containing the signature for the

  data

  .

  options

  may contain any of:
  • hash - string - The explicitly desired hash to use when computing the signature. Currently if set, this may be either

    'sha256'

    or

    'sha512'

    for RSA keys.

• signReply(< opaque >request, < Buffer >signature) - (void) - (Server mode only) Responds to a sign

  request

  with the given signature in

  signature

  .

BaseAgent

In order to create a custom agent, your class must:

• Extend

  BaseAgent

• Call

  super()

  in its constructor

• Implement at least the following methods:

  • getIdentities(< function >callback) - (void) - Passes

    (err, keys)

    to

    callback

    where

    keys

    is a possible array of public keys for authentication.
  • sign(< mixed >pubKey, < Buffer >data, < object >options, < function >callback) - (void) - Signs

    data

    using the key identified by

    pubKey

    .

    pubKey

    can be any parsed (using

    utils.parseKey()

    ) or parseable key value.

    callback

    should be passed

    (err, signature)

    where

    signature

    is a possible Buffer containing the signature for the

    data

    .

    options

    may contain any of:

• hash - string - The explicitly desired hash to use when computing the signature. Currently if set, this may be either

  'sha256'

  or

  'sha512'

  for RSA keys.

Additionally your class may implement the following method in order to support agent forwarding on the client:

• getStream(< function >callback) - (void) - Passes

  (err, stream)

  to

  callback

  where

  stream

  is a possible Duplex stream to be used to communicate with your agent. You will probably want to utilize

  AgentProtocol

  as agent forwarding is an OpenSSH feature, so the

  stream

  needs to be able to transmit/receive OpenSSH agent protocol packets.

createAgent

• createAgent(< string >agentValue) - (Agent) - Creates and returns a new agent instance using the same logic as the

  Client

  's

  agent

  configuration option: if the platform is Windows and it's the value "pageant", it creates a

  PageantAgent

  , otherwise if it's not a path to a Windows pipe it creates a

  CygwinAgent

  . In all other cases, it creates an

  OpenSSHAgent

  .

CygwinAgent

CygwinAgent methods

• (constructor)(< string >socketPath) - Communicates with an agent listening at

  socketPath

  in a Cygwin environment.

OpenSSHAgent

OpenSSHAgent methods

• (constructor)(< string >socketPath) - Communicates with an OpenSSH agent listening on the UNIX socket at

  socketPath

  .

PageantAgent

PageantAgent methods

• (constructor)() - Creates a new agent instance for communicating with a running Pageant agent process.