Multi-version runtime detection, isKey/isPrivateKey etc

Author: Alex Wilson

README.md

@@ -129,6 +129,15 @@ Parameters
 - `name` -- Optional name for the key being parsed (eg. the filename that
             was opened). Used to generate Error messages
 
+### `Key.isKey(obj)`
+
+Returns `true` if the given object is a valid `Key` object created by a version
+of `sshpk` compatible with this one.
+
+Parameters
+
+- `obj` -- Object to identify
+
 ### `Key#type`
 
 String, the type of key. Valid options are `rsa`, `dsa`, `ecdsa`.
@@ -221,6 +230,15 @@ Parameters
 - `name` -- Optional name for the key being parsed (eg. the filename that
             was opened). Used to generate Error messages
 
+### `PrivateKey.isPrivateKey(obj)`
+
+Returns `true` if the given object is a valid `PrivateKey` object created by a
+version of `sshpk` compatible with this one.
+
+Parameters
+
+- `obj` -- Object to identify
+
 ### `PrivateKey#type`
 
 String, the type of key. Valid options are `rsa`, `dsa`, `ecdsa`.
@@ -306,6 +324,15 @@ Parameters
                   support to. If `fingerprint` uses a hash algorithm not on
                   this list, throws `InvalidAlgorithmError`.
 
+### `Fingerprint.isFingerprint(obj)`
+
+Returns `true` if the given object is a valid `Fingerprint` object created by a
+version of `sshpk` compatible with this one.
+
+Parameters
+
+- `obj` -- Object to identify
+
 ### `Fingerprint#toString([format])`
 
 Returns a fingerprint as a string, in the given format.
@@ -345,6 +372,15 @@ Parameters
                  are `rsa`, `dsa`, `ecdsa`
 - `format` -- a String, either `asn1` or `ssh`
 
+### `Signature.isSignature(obj)`
+
+Returns `true` if the given object is a valid `Signature` object created by a
+version of `sshpk` compatible with this one.
+
+Parameters
+
+- `obj` -- Object to identify
+
 ### `Signature#toBuffer([format = 'asn1'])`
 
 Converts a Signature to the given format and returns it as a Buffer.

bin/sshpk-conv

@@ -166,7 +166,7 @@ if (require.main === module) {
 			});
 		} else {
 			var kind = 'public';
-			if (key instanceof sshpk.PrivateKey)
+			if (PrivateKey.isPrivateKey(key))
 				kind = 'private';
 			console.log('%s: a %d bit %s %s key', inFileName,
 			    key.size, key.type.toUpperCase(), kind);

lib/dhe.js

@@ -17,7 +17,8 @@ var CRYPTO_HAVE_ECDH = (crypto.createECDH !== undefined &&
 var ecdh, ec, jsbn;
 
 function DiffieHellman(key) {
-	this._isPriv = (key instanceof PrivateKey);
+	utils.assertCompatible(key, Key, [1, 4], 'key');
+	this._isPriv = PrivateKey.isPrivateKey(key, [1, 3]);
 	this._algo = key.type;
 	this._curve = key.curve;
 	this._key = key;
@@ -102,11 +103,9 @@ DiffieHellman.prototype.getKey = DiffieHellman.prototype.getPrivateKey;
 
 DiffieHellman.prototype._keyCheck = function (pk, isPub) {
 	assert.object(pk, 'key');
-	if (!isPub) {
-		assert.ok(pk instanceof PrivateKey,
-		    'key must be a sshpk.PrivateKey');
-	}
-	assert.ok(pk instanceof Key, 'key must be a sshpk.Key');
+	if (!isPub)
+		utils.assertCompatible(pk, PrivateKey, [1, 3], 'key');
+	utils.assertCompatible(pk, Key, [1, 4], 'key');
 
 	if (pk.type !== this._algo) {
 		throw (new Error('A ' + pk.type + ' key cannot be used in ' +

lib/ed-compat.js

@@ -39,11 +39,17 @@ Verifier.prototype.update = function (chunk) {
 
 Verifier.prototype.verify = function (signature, fmt) {
 	var sig;
-	if (typeof (signature) === 'object' &&
-	    signature instanceof Signature)
+	if (Signature.isSignature(signature, [2, 0])) {
 		sig = signature.toBuffer('raw');
-	else if (typeof (signature) === 'string')
+
+	} else if (typeof (signature) === 'string') {
 		sig = new Buffer(signature, 'base64');
+
+	} else if (Signature.isSignature(signature, [1, 0])) {
+		throw (new Error('signature was created by too old ' +
+		    'a version of sshpk and cannot be verified'));
+	}
+
 	assert.buffer(sig);
 	return (nacl.sign.detached.verify(
 	    new Uint8Array(Buffer.concat(this.chunks)),

lib/fingerprint.js

@@ -7,6 +7,7 @@ var algs = require('./algs');
 var crypto = require('crypto');
 var errs = require('./errors');
 var Key = require('./key');
+var utils = require('./utils');
 
 var FingerprintFormatError = errs.FingerprintFormatError;
 var InvalidAlgorithmError = errs.InvalidAlgorithmError;
@@ -45,10 +46,7 @@ Fingerprint.prototype.toString = function (format) {
 
 Fingerprint.prototype.matches = function (key) {
 	assert.object(key, 'key');
-	/* Defer until runtime due to circular deps */
-	if (Key === undefined)
-		Key = require('./key');
-	assert.ok(key instanceof Key, 'key');
+	utils.assertCompatible(key, Key, [1, 0], 'key');
 
 	var theirHash = key.hash(this.algorithm);
 	var theirHash2 = crypto.createHash(this.algorithm).
@@ -123,3 +121,20 @@ function base64Strip(s) {
 function sshBase64Format(alg, h) {
 	return (alg.toUpperCase() + ':' + base64Strip(h));
 }
+
+Fingerprint.isFingerprint = function (obj, ver) {
+	return (utils.isCompatible(obj, Fingerprint, ver));
+};
+
+/*
+ * API versions for Fingerprint:
+ * [1,0] -- initial ver
+ * [1,1] -- first tagged ver
+ */
+Fingerprint.prototype._sshpkApiVersion = [1, 1];
+
+Fingerprint._oldVersionDetect = function (obj) {
+	assert.func(obj.toString);
+	assert.func(obj.matches);
+	return ([1, 0]);
+};

lib/formats/pem.js

@@ -106,7 +106,7 @@ function write(key, type) {
 
 	var der = new asn1.BerWriter();
 
-	if (key instanceof PrivateKey) {
+	if (PrivateKey.isPrivateKey(key)) {
 		if (type && type === 'pkcs8') {
 			header = 'PRIVATE KEY';
 			pkcs8.writePkcs8(der, key);
@@ -117,7 +117,7 @@ function write(key, type) {
 			pkcs1.writePkcs1(der, key);
 		}
 
-	} else if (key instanceof Key) {
+	} else if (Key.isKey(key)) {
 		if (type && type === 'pkcs1') {
 			header = alg + ' PUBLIC KEY';
 			pkcs1.writePkcs1(der, key);

lib/formats/pkcs1.js

@@ -219,19 +219,19 @@ function writePkcs1(der, key) {
 
 	switch (key.type) {
 	case 'rsa':
-		if (key instanceof PrivateKey)
+		if (PrivateKey.isPrivateKey(key))
 			writePkcs1RSAPrivate(der, key);
 		else
 			writePkcs1RSAPublic(der, key);
 		break;
 	case 'dsa':
-		if (key instanceof PrivateKey)
+		if (PrivateKey.isPrivateKey(key))
 			writePkcs1DSAPrivate(der, key);
 		else
 			writePkcs1DSAPublic(der, key);
 		break;
 	case 'ecdsa':
-		if (key instanceof PrivateKey)
+		if (PrivateKey.isPrivateKey(key))
 			writePkcs1ECDSAPrivate(der, key);
 		else
 			writePkcs1ECDSAPublic(der, key);

lib/formats/pkcs8.js

@@ -330,7 +330,7 @@ function readPkcs8ECDSAPublic(der) {
 function writePkcs8(der, key) {
 	der.startSequence();
 
-	if (key instanceof PrivateKey) {
+	if (PrivateKey.isPrivateKey(key)) {
 		var sillyInt = new Buffer(1);
 		sillyInt[0] = 0x0;
 		der.writeBuffer(sillyInt, asn1.Ber.Integer);
@@ -340,21 +340,21 @@ function writePkcs8(der, key) {
 	switch (key.type) {
 	case 'rsa':
 		der.writeOID('1.2.840.113549.1.1.1');
-		if (key instanceof PrivateKey)
+		if (PrivateKey.isPrivateKey(key))
 			writePkcs8RSAPrivate(key, der);
 		else
 			writePkcs8RSAPublic(key, der);
 		break;
 	case 'dsa':
 		der.writeOID('1.2.840.10040.4.1');
-		if (key instanceof PrivateKey)
+		if (PrivateKey.isPrivateKey(key))
 			writePkcs8DSAPrivate(key, der);
 		else
 			writePkcs8DSAPublic(key, der);
 		break;
 	case 'ecdsa':
 		der.writeOID('1.2.840.10045.2.1');
-		if (key instanceof PrivateKey)
+		if (PrivateKey.isPrivateKey(key))
 			writePkcs8ECDSAPrivate(key, der);
 		else
 			writePkcs8ECDSAPublic(key, der);

lib/formats/rfc4253.js

@@ -127,7 +127,7 @@ function write(key) {
 	var i;
 
 	var algInfo = algs.info[key.type];
-	if (key instanceof PrivateKey)
+	if (PrivateKey.isPrivateKey(key))
 		algInfo = algs.privInfo[key.type];
 	var parts = algInfo.parts;
 

lib/formats/ssh-private.js

@@ -78,13 +78,13 @@ function readSSHPrivate(type, buf) {
 
 function write(key) {
 	var pubKey;
-	if (key instanceof PrivateKey)
+	if (PrivateKey.isPrivateKey(key))
 		pubKey = key.toPublic();
 	else
 		pubKey = key;
 
 	var privBuf;
-	if (key instanceof PrivateKey) {
+	if (PrivateKey.isPrivateKey(key)) {
 		privBuf = new SSHBuffer({});
 		var checkInt = crypto.randomBytes(4).readUInt32BE(0);
 		privBuf.writeInt(checkInt);
@@ -113,7 +113,7 @@ function write(key) {
 	buf = buf.toBuffer();
 
 	var header;
-	if (key instanceof PrivateKey)
+	if (PrivateKey.isPrivateKey(key))
 		header = 'OPENSSH PRIVATE KEY';
 	else
 		header = 'OPENSSH PUBLIC KEY';

lib/formats/ssh.js

@@ -97,8 +97,8 @@ function read(buf) {
 
 function write(key) {
 	assert.object(key);
-	if (key instanceof PrivateKey)
-		throw (new Error('Private keys are not supported'));
+	if (!Key.isKey(key))
+		throw (new Error('Must be a public key'));
 
 	var parts = [];
 	var alg = rfc4253.keyTypeToAlg(key);

lib/key.js

@@ -176,10 +176,25 @@ Key.prototype.createVerify = function (hashAlgo) {
 	var oldVerify = v.verify.bind(v);
 	var key = this.toBuffer('pkcs8');
 	v.verify = function (signature, fmt) {
-		if (typeof (signature) === 'object' &&
-		    signature instanceof Signature)
+		if (Signature.isSignature(signature, [2, 0])) {
 			return (oldVerify(key, signature.toBuffer('asn1')));
-		return (oldVerify(key, signature, fmt));
+
+		} else if (typeof (signature) === 'string' ||
+		    Buffer.isBuffer(signature)) {
+			return (oldVerify(key, signature, fmt));
+
+		/*
+		 * Avoid doing this on valid arguments, walking the prototype
+		 * chain can be quite slow.
+		 */
+		} else if (Signature.isSignature(signature, [1, 0])) {
+			throw (new Error('signature was created by too old ' +
+			    'a version of sshpk and cannot be verified'));
+
+		} else {
+			throw (new TypeError('signature must be a string, ' +
+			    'Buffer, or Signature object'));
+		}
 	};
 	return (v);
 };
@@ -214,3 +229,32 @@ Key.parse = function (data, format, name) {
 		throw (new KeyParseError(name, format, e));
 	}
 };
+
+Key.isKey = function (obj, ver) {
+	return (utils.isCompatible(obj, Key, ver));
+};
+
+/*
+ * API versions for Key:
+ * [1,0] -- initial ver, may take Signature for createVerify or may not
+ * [1,1] -- added pkcs1, pkcs8 formats
+ * [1,2] -- added auto, ssh-private, openssh formats
+ * [1,3] -- added defaultHashAlgorithm
+ * [1,4] -- added ed support, createDH
+ * [1,5] -- first explicitly tagged version
+ */
+Key.prototype._sshpkApiVersion = [1, 5];
+
+Key._oldVersionDetect = function (obj) {
+	assert.func(obj.toBuffer);
+	assert.func(obj.fingerprint);
+	if (obj.createDH)
+		return ([1, 4]);
+	if (obj.defaultHashAlgorithm)
+		return ([1, 3]);
+	if (obj.formats['auto'])
+		return ([1, 2]);
+	if (obj.formats['pkcs1'])
+		return ([1, 1]);
+	return ([1, 0]);
+};

lib/private-key.js

@@ -196,3 +196,29 @@ PrivateKey.parse = function (data, format, name) {
 		throw (new KeyParseError(name, format, e));
 	}
 };
+
+PrivateKey.isPrivateKey = function (obj, ver) {
+	return (utils.isCompatible(obj, PrivateKey, ver));
+};
+
+/*
+ * API versions for PrivateKey:
+ * [1,0] -- initial ver
+ * [1,1] -- added auto, pkcs[18], openssh/ssh-private formats
+ * [1,2] -- added defaultHashAlgorithm
+ * [1,3] -- added derive, ed, createDH
+ * [1,4] -- first tagged version
+ */
+PrivateKey.prototype._sshpkApiVersion = [1, 4];
+
+PrivateKey._oldVersionDetect = function (obj) {
+	assert.func(obj.toPublic);
+	assert.func(obj.createSign);
+	if (obj.derive)
+		return ([1, 3]);
+	if (obj.defaultHashAlgorithm)
+		return ([1, 2]);
+	if (obj.formats['auto'])
+		return ([1, 1]);
+	return ([1, 0]);
+};

lib/signature.js

@@ -215,3 +215,23 @@ function parseECDSA(data, type, format, opts) {
 	opts.parts.push(s);
 	return (new Signature(opts));
 }
+
+Signature.isSignature = function (obj, ver) {
+	return (utils.isCompatible(obj, Signature, ver));
+};
+
+/*
+ * API versions for Signature:
+ * [1,0] -- initial ver
+ * [2,0] -- support for rsa in full ssh format, compat with sshpk-agent
+ *          hashAlgorithm property
+ * [2,1] -- first tagged version
+ */
+Signature.prototype._sshpkApiVersion = [2, 1];
+
+Signature._oldVersionDetect = function (obj) {
+	assert.func(obj.toBuffer);
+	if (obj.hasOwnProperty('hashAlgorithm'))
+		return ([2, 0]);
+	return ([1, 0]);
+};