ssh-agent client for use with sshpk
npm install sshpk-agentsshpk-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
-----
Creates a new ssh-agent client.
Parameters
- options -- optional Object, containing properties:socketPath
- -- an optional String, path to the UNIX socket to reach the SSHprocess.env['SSH_AUTH_SOCK']
agent via. If not specified, defaults to
timeout
- -- an optional Number, milliseconds to wait for the agent to
respond to a request before returning error. Defaults to 2000.
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 forcallback
this request
- -- function (error, keys) with arguments:error
- -- null if no error, otherwise an instance of Error or itskeys
subclasses
- -- Array of sshpk.Key objects, the available public keys
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 forcallback
this request
- -- function (error, keys) with arguments:error
- -- null if no error, otherwise an instance of Error or itskeys
subclasses
- -- Array of sshpk.Certificate objects, the available certificates
Uses a key stored in the agent to sign some data.
Parameters
- key -- an Object, instance of sshpk.Key, key to sign withdata
- -- a Buffer or String, data to be signedoptions
- -- optional Object, containing properties:timeout
- -- an optional Number, overrides the constructor timeout just forcallback
this request
- -- function (error, signature) with arguments:error
- -- null if no error, otherwise instance of Errorsignature
- -- an Object, instance of sshpk.Signature
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 certificatekey
- -- an Object, instance of sshpk.Key, key to sign with and theoptions
subject key
- -- an Object, additional options, with keys:lifetime
- -- optional Number, lifetime of the certificate from now invalidFrom
seconds
- , validUntil -- optional Dates, beginning and end oflifetime
certificate validity period. If given, will be ignored.serial
- -- optional Buffer, the serial number of the certificatepurposes
- -- optional Array of String, X.509 key usage restrictionscallback
- -- function (error, certificate), with arguments:error
- -- null if no error, otherwise instance of Errorcertificate
- -- an Object, instance of sshpk.Certificate
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 certificatesubjectKey
- -- an Object, instance of sshpk.Key, key of the subjectissuer
entity (does not have to reside in the agent)
- -- an Identity, the issuer of the certificatekey
- -- an Object, instance of sshpk.Key, key to sign with (must be inissuer
the agent, and match up with the identity)options
- -- an Object, additional options, with keys:lifetime
- -- optional Number, lifetime of the certificate from now invalidFrom
seconds
- , validUntil -- optional Dates, beginning and end oflifetime
certificate validity period. If given, will be ignored.serial
- -- optional Buffer, the serial number of the certificatepurposes
- -- optional Array of String, X.509 key usage restrictionscallback
- -- function (error, certificate), with arguments:error
- -- null if no error, otherwise instance of Errorcertificate
- -- an Object, instance of sshpk.Certificate
Adds a new private key to the agent.
Parameters
- privkey -- an Object, instance of sshpk.PrivateKey, key to addoptions
- -- optional Object, containing properties:expires
- -- optional Number, seconds until this key expires. If not given,timeout
key will last indefinitely. Expiry is handled by the agent
itself.
- -- optional Number, overrides the constructor timeoutcallback
- -- function (error) with arguments:error
- -- null if no error, otherwise instance of Error
Adds a new certificate and private key pair to the agent.
Parameters
- cert -- an Object, instance of sshpk.Certificate, cert to addprivkey
- -- an Object, instance of sshpk.PrivateKey, subject private keyoptions
of the certificate
- -- optional Object, containing properties:expires
- -- optional Number, seconds until this key expires. If not given,timeout
key will last indefinitely. Expiry is handled by the agent
itself.
- -- optional Number, overrides the constructor timeoutcallback
- -- function (error) with arguments:error
- -- null if no error, otherwise instance of Error
Removes a private key from the agent.
Parameters
- key -- an Object, instance of sshpk.Key, key to removeoptions
- -- optional Object, containing properties:timeout
- -- an optional Number, overrides the constructor timeout just forcallback
this request
- -- function (error) with arguments:error
- -- null if no error, otherwise instance of Error
Removes all private keys from the agent.
Parameters
- options -- optional Object, containing properties:timeout
- -- an optional Number, overrides the constructor timeout just forcallback
this request
- -- function (error) with arguments:error
- -- null if no error, otherwise instance of Error
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 agentoptions
- -- optional Object, containing properties:timeout
- -- an optional Number, overrides the constructor timeout just forcallback
this request
- -- function (error) with arguments:error
- -- null if no error, otherwise instance of Error
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 agentoptions
- -- optional Object, containing properties:timeout
- -- an optional Number, overrides the constructor timeout just forcallback
this request
- -- function (error) with arguments:error
- -- null if no error, otherwise instance of Error
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 Errorextensions` -- Array of String, supported extensions
-