Sshpk-agent NPM

sshpk-agent

A library for using the ssh-agent protocol, written to leverage the modern node Streams API and use sshpk objects. Supports most client operations (including key add/remove), but agent support is coming. Re-uses socket connections where possible for lower latency operation.

Install

npm install sshpk-agent

Examples

var agent = require('sshpk-agent');
var sshpk = require('sshpk');

var client = new agent.Client();

/* Add a new key to the agent */
var pk = sshpk.parsePrivateKey(fs.readFileSync('id_rsa'), 'pem');
client.addKey(pk, function (err) {
  ...
});

/* List all the keys stored in the agent */
var key;
client.listKeys(function (err, keys) {
  if (err)
    return;
  /* keys is an array of sshpk.Key objects */
  key = keys[0];
});

/* Sign some data with a key */
var data = 'foobar';
client.sign(key, data, function (err, signature) {
  /* signature is an sshpk.Signature object */
  ...
  /* to find out what hash algorithm the agent used -- it chooses for you */
  var algo = signature.hashAlgorithm;
  ...
});

Usage

`new Client([options]);`

Creates a new ssh-agent client.

Parameters

options -- optional Object, containing properties:
- socketPath -- an optional String, path to the UNIX socket to reach the SSH agent via. If not specified, defaults to process.env['SSH_AUTH_SOCK']
- timeout -- an optional Number, milliseconds to wait for the agent to respond to a request before returning error. Defaults to 2000.

`Client#listKeys([options, ]callback);`

Retrieves a list of all keys stored in the agent.

Parameters

options -- optional Object, containg properties:
- timeout -- an optional Number, overrides the constructor timeout just for this request
callback -- function (error, keys) with arguments:
- error -- null if no error, otherwise an instance of Error or its subclasses
- keys -- Array of sshpk.Key objects, the available public keys

`Client#listCertificates([options, ]callback);`

Retrieves a list of all certificates stored in the agent.

Parameters

options -- optional Object, containg properties:
- timeout -- an optional Number, overrides the constructor timeout just for this request
callback -- function (error, keys) with arguments:
- error -- null if no error, otherwise an instance of Error or its subclasses
- keys -- Array of sshpk.Certificate objects, the available certificates

`Client#sign(key, data[, options], callback);`

Uses a key stored in the agent to sign some data.

Parameters

key -- an Object, instance of sshpk.Key, key to sign with
data -- a Buffer or String, data to be signed
options -- optional Object, containing properties:
- timeout -- an optional Number, overrides the constructor timeout just for this request
callback -- function (error, signature) with arguments:
- error -- null if no error, otherwise instance of Error
- signature -- an Object, instance of sshpk.Signature

`Client#createSelfSignedCertificate(subject, key, options, cb)`

Uses a key stored in the agent to create a self-signed certificate for that key. The certificate can be read back in both OpenSSH and X.509 formats.

Parameters

subject -- an Identity, the subject of the certificate
key -- an Object, instance of sshpk.Key, key to sign with and the subject key
options -- an Object, additional options, with keys:
- lifetime -- optional Number, lifetime of the certificate from now in seconds
- validFrom, validUntil -- optional Dates, beginning and end of certificate validity period. If given, lifetime will be ignored.
- serial -- optional Buffer, the serial number of the certificate
- purposes -- optional Array of String, X.509 key usage restrictions
callback -- function (error, certificate), with arguments:
- error -- null if no error, otherwise instance of Error
- certificate -- an Object, instance of sshpk.Certificate

`Client#createCertificate(subject, subjectKey, issuer, key, options, cb)`

Uses a key stored in the agent to create and sign a certificate for some other key (not necessarily in the agent). The certificate can be read back in both OpenSSH and X.509 formats.

Parameters

subject -- an Identity, the subject of the certificate
subjectKey -- an Object, instance of sshpk.Key, key of the subject entity (does not have to reside in the agent)
issuer -- an Identity, the issuer of the certificate
key -- an Object, instance of sshpk.Key, key to sign with (must be in the agent, and match up with the issuer identity)
options -- an Object, additional options, with keys:
- lifetime -- optional Number, lifetime of the certificate from now in seconds
- validFrom, validUntil -- optional Dates, beginning and end of certificate validity period. If given, lifetime will be ignored.
- serial -- optional Buffer, the serial number of the certificate
- purposes -- optional Array of String, X.509 key usage restrictions
callback -- function (error, certificate), with arguments:
- error -- null if no error, otherwise instance of Error
- certificate -- an Object, instance of sshpk.Certificate

`Client#addKey(privkey[, options], callback);`

Adds a new private key to the agent.

Parameters

privkey -- an Object, instance of sshpk.PrivateKey, key to add
options -- optional Object, containing properties:
- expires -- optional Number, seconds until this key expires. If not given, key will last indefinitely. Expiry is handled by the agent itself.
- timeout -- optional Number, overrides the constructor timeout
callback -- function (error) with arguments:
- error -- null if no error, otherwise instance of Error

`Client#addCertificate(cert, privkey[, options], callback);`

Adds a new certificate and private key pair to the agent.

Parameters

cert -- an Object, instance of sshpk.Certificate, cert to add
privkey -- an Object, instance of sshpk.PrivateKey, subject private key of the certificate
options -- optional Object, containing properties:
- expires -- optional Number, seconds until this key expires. If not given, key will last indefinitely. Expiry is handled by the agent itself.
- timeout -- optional Number, overrides the constructor timeout
callback -- function (error) with arguments:
- error -- null if no error, otherwise instance of Error

`Client#removeKey(key[, options], callback);`

Removes a private key from the agent.

Parameters

key -- an Object, instance of sshpk.Key, key to remove
options -- optional Object, containing properties:
- timeout -- an optional Number, overrides the constructor timeout just for this request
callback -- function (error) with arguments:
- error -- null if no error, otherwise instance of Error

`Client#removeAllKeys([options, ]callback);`

Removes all private keys from the agent.

Parameters

options -- optional Object, containing properties:
- timeout -- an optional Number, overrides the constructor timeout just for this request
callback -- function (error) with arguments:
- error -- null if no error, otherwise instance of Error

`Client#lock(password[, options], callback);`

Locks the agent with a password, causing it to respond with failure to all requests (except a request to list keys, which always returns an empty list), until unlocked with the same password.

Parameters

password -- a String, password to be required to unlock the agent
options -- optional Object, containing properties:
- timeout -- an optional Number, overrides the constructor timeout just for this request
callback -- function (error) with arguments:
- error -- null if no error, otherwise instance of Error

`Client#unlock(password[, options], callback);`

Unlocks an agent that has been previously locked. The given password must match the password used to lock the agent.

Parameters

password -- a String, password to unlock the agent
options -- optional Object, containing properties:
- timeout -- an optional Number, overrides the constructor timeout just for this request
callback -- function (error) with arguments:
- error -- null if no error, otherwise instance of Error

`Client#listExtensions(callback);`

Requests the "query" extension (see draft-miller-ssh-agent-00) from the agent to list what agent protocol extensions are supported. These are returned as a list of Strings.

Parameters