sshpk-agent

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
--------

`js
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
-----

$3

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.

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

- callback -- function (error, extensions) with arguments:
- error -- null if no error, otherwise instance of Error
- extensions` -- Array of String, supported extensions