1 | sshpk
|
2 | =========
|
3 |
|
4 | Parse, convert, fingerprint and use SSH keys (both public and private) in pure
|
5 | node -- no `ssh-keygen` or other external dependencies.
|
6 |
|
7 | Supports RSA, DSA, ECDSA (nistp-\*) and ED25519 key types, in PEM (PKCS#1,
|
8 | PKCS#8) and OpenSSH formats.
|
9 |
|
10 | This library has been extracted from
|
11 | [`node-http-signature`](https://github.com/joyent/node-http-signature)
|
12 | (work by [Mark Cavage](https://github.com/mcavage) and
|
13 | [Dave Eddy](https://github.com/bahamas10)) and
|
14 | [`node-ssh-fingerprint`](https://github.com/bahamas10/node-ssh-fingerprint)
|
15 | (work by Dave Eddy), with additions (including ECDSA support) by
|
16 | [Alex Wilson](https://github.com/arekinath).
|
17 |
|
18 | Install
|
19 | -------
|
20 |
|
21 | ```
|
22 | npm install sshpk
|
23 | ```
|
24 |
|
25 | Examples
|
26 | --------
|
27 |
|
28 | ```js
|
29 | var sshpk = require('sshpk');
|
30 |
|
31 | var fs = require('fs');
|
32 |
|
33 | /* Read in an OpenSSH-format public key */
|
34 | var keyPub = fs.readFileSync('id_rsa.pub');
|
35 | var key = sshpk.parseKey(keyPub, 'ssh');
|
36 |
|
37 | /* Get metadata about the key */
|
38 | console.log('type => %s', key.type);
|
39 | console.log('size => %d bits', key.size);
|
40 | console.log('comment => %s', key.comment);
|
41 |
|
42 | /* Compute key fingerprints, in new OpenSSH (>6.7) format, and old MD5 */
|
43 | console.log('fingerprint => %s', key.fingerprint().toString());
|
44 | console.log('old-style fingerprint => %s', key.fingerprint('md5').toString());
|
45 | ```
|
46 |
|
47 | Example output:
|
48 |
|
49 | ```
|
50 | type => rsa
|
51 | size => 2048 bits
|
52 | comment => foo@foo.com
|
53 | fingerprint => SHA256:PYC9kPVC6J873CSIbfp0LwYeczP/W4ffObNCuDJ1u5w
|
54 | old-style fingerprint => a0:c8:ad:6c:32:9a:32:fa:59:cc:a9:8c:0a:0d:6e:bd
|
55 | ```
|
56 |
|
57 | More examples: converting between formats:
|
58 |
|
59 | ```js
|
60 | /* Read in a PEM public key */
|
61 | var keyPem = fs.readFileSync('id_rsa.pem');
|
62 | var key = sshpk.parseKey(keyPem, 'pem');
|
63 |
|
64 | /* Convert to PEM PKCS#8 public key format */
|
65 | var pemBuf = key.toBuffer('pkcs8');
|
66 |
|
67 | /* Convert to SSH public key format (and return as a string) */
|
68 | var sshKey = key.toString('ssh');
|
69 | ```
|
70 |
|
71 | Signing and verifying:
|
72 |
|
73 | ```js
|
74 | /* Read in an OpenSSH/PEM *private* key */
|
75 | var keyPriv = fs.readFileSync('id_ecdsa');
|
76 | var key = sshpk.parsePrivateKey(keyPriv, 'pem');
|
77 |
|
78 | var data = 'some data';
|
79 |
|
80 | /* Sign some data with the key */
|
81 | var s = key.createSign('sha1');
|
82 | s.update(data);
|
83 | var signature = s.sign();
|
84 |
|
85 | /* Now load the public key (could also use just key.toPublic()) */
|
86 | var keyPub = fs.readFileSync('id_ecdsa.pub');
|
87 | key = sshpk.parseKey(keyPub, 'ssh');
|
88 |
|
89 | /* Make a crypto.Verifier with this key */
|
90 | var v = key.createVerify('sha1');
|
91 | v.update(data);
|
92 | var valid = v.verify(signature);
|
93 | /* => true! */
|
94 | ```
|
95 |
|
96 | Matching fingerprints with keys:
|
97 |
|
98 | ```js
|
99 | var fp = sshpk.parseFingerprint('SHA256:PYC9kPVC6J873CSIbfp0LwYeczP/W4ffObNCuDJ1u5w');
|
100 |
|
101 | var keys = [sshpk.parseKey(...), sshpk.parseKey(...), ...];
|
102 |
|
103 | keys.forEach(function (key) {
|
104 | if (fp.matches(key))
|
105 | console.log('found it!');
|
106 | });
|
107 | ```
|
108 |
|
109 | Usage
|
110 | -----
|
111 |
|
112 | ## Public keys
|
113 |
|
114 | ### `parseKey(data[, format = 'auto'[, options]])`
|
115 |
|
116 | Parses a key from a given data format and returns a new `Key` object.
|
117 |
|
118 | Parameters
|
119 |
|
120 | - `data` -- Either a Buffer or String, containing the key
|
121 | - `format` -- String name of format to use, valid options are:
|
122 | - `auto`: choose automatically from all below
|
123 | - `pem`: supports both PKCS#1 and PKCS#8
|
124 | - `ssh`: standard OpenSSH format,
|
125 | - `pkcs1`, `pkcs8`: variants of `pem`
|
126 | - `rfc4253`: raw OpenSSH wire format
|
127 | - `openssh`: new post-OpenSSH 6.5 internal format, produced by
|
128 | `ssh-keygen -o`
|
129 | - `dnssec`: `.key` file format output by `dnssec-keygen` etc
|
130 | - `putty`: the PuTTY `.ppk` file format (supports truncated variant without
|
131 | all the lines from `Private-Lines:` onwards)
|
132 | - `options` -- Optional Object, extra options, with keys:
|
133 | - `filename` -- Optional String, name for the key being parsed
|
134 | (eg. the filename that was opened). Used to generate
|
135 | Error messages
|
136 | - `passphrase` -- Optional String, encryption passphrase used to decrypt an
|
137 | encrypted PEM file
|
138 |
|
139 | ### `Key.isKey(obj)`
|
140 |
|
141 | Returns `true` if the given object is a valid `Key` object created by a version
|
142 | of `sshpk` compatible with this one.
|
143 |
|
144 | Parameters
|
145 |
|
146 | - `obj` -- Object to identify
|
147 |
|
148 | ### `Key#type`
|
149 |
|
150 | String, the type of key. Valid options are `rsa`, `dsa`, `ecdsa`.
|
151 |
|
152 | ### `Key#size`
|
153 |
|
154 | Integer, "size" of the key in bits. For RSA/DSA this is the size of the modulus;
|
155 | for ECDSA this is the bit size of the curve in use.
|
156 |
|
157 | ### `Key#comment`
|
158 |
|
159 | Optional string, a key comment used by some formats (eg the `ssh` format).
|
160 |
|
161 | ### `Key#curve`
|
162 |
|
163 | Only present if `this.type === 'ecdsa'`, string containing the name of the
|
164 | named curve used with this key. Possible values include `nistp256`, `nistp384`
|
165 | and `nistp521`.
|
166 |
|
167 | ### `Key#toBuffer([format = 'ssh'])`
|
168 |
|
169 | Convert the key into a given data format and return the serialized key as
|
170 | a Buffer.
|
171 |
|
172 | Parameters
|
173 |
|
174 | - `format` -- String name of format to use, for valid options see `parseKey()`
|
175 |
|
176 | ### `Key#toString([format = 'ssh])`
|
177 |
|
178 | Same as `this.toBuffer(format).toString()`.
|
179 |
|
180 | ### `Key#fingerprint([algorithm = 'sha256'[, hashType = 'ssh']])`
|
181 |
|
182 | Creates a new `Fingerprint` object representing this Key's fingerprint.
|
183 |
|
184 | Parameters
|
185 |
|
186 | - `algorithm` -- String name of hash algorithm to use, valid options are `md5`,
|
187 | `sha1`, `sha256`, `sha384`, `sha512`
|
188 | - `hashType` -- String name of fingerprint hash type to use, valid options are
|
189 | `ssh` (the type of fingerprint used by OpenSSH, e.g. in
|
190 | `ssh-keygen`), `spki` (used by HPKP, some OpenSSL applications)
|
191 |
|
192 | ### `Key#createVerify([hashAlgorithm])`
|
193 |
|
194 | Creates a `crypto.Verifier` specialized to use this Key (and the correct public
|
195 | key algorithm to match it). The returned Verifier has the same API as a regular
|
196 | one, except that the `verify()` function takes only the target signature as an
|
197 | argument.
|
198 |
|
199 | Parameters
|
200 |
|
201 | - `hashAlgorithm` -- optional String name of hash algorithm to use, any
|
202 | supported by OpenSSL are valid, usually including
|
203 | `sha1`, `sha256`.
|
204 |
|
205 | `v.verify(signature[, format])` Parameters
|
206 |
|
207 | - `signature` -- either a Signature object, or a Buffer or String
|
208 | - `format` -- optional String, name of format to interpret given String with.
|
209 | Not valid if `signature` is a Signature or Buffer.
|
210 |
|
211 | ### `Key#createDiffieHellman()`
|
212 | ### `Key#createDH()`
|
213 |
|
214 | Creates a Diffie-Hellman key exchange object initialized with this key and all
|
215 | necessary parameters. This has the same API as a `crypto.DiffieHellman`
|
216 | instance, except that functions take `Key` and `PrivateKey` objects as
|
217 | arguments, and return them where indicated for.
|
218 |
|
219 | This is only valid for keys belonging to a cryptosystem that supports DHE
|
220 | or a close analogue (i.e. `dsa`, `ecdsa` and `curve25519` keys). An attempt
|
221 | to call this function on other keys will yield an `Error`.
|
222 |
|
223 | ## Private keys
|
224 |
|
225 | ### `parsePrivateKey(data[, format = 'auto'[, options]])`
|
226 |
|
227 | Parses a private key from a given data format and returns a new
|
228 | `PrivateKey` object.
|
229 |
|
230 | Parameters
|
231 |
|
232 | - `data` -- Either a Buffer or String, containing the key
|
233 | - `format` -- String name of format to use, valid options are:
|
234 | - `auto`: choose automatically from all below
|
235 | - `pem`: supports both PKCS#1 and PKCS#8
|
236 | - `ssh`, `openssh`: new post-OpenSSH 6.5 internal format, produced by
|
237 | `ssh-keygen -o`
|
238 | - `pkcs1`, `pkcs8`: variants of `pem`
|
239 | - `rfc4253`: raw OpenSSH wire format
|
240 | - `dnssec`: `.private` format output by `dnssec-keygen` etc.
|
241 | - `options` -- Optional Object, extra options, with keys:
|
242 | - `filename` -- Optional String, name for the key being parsed
|
243 | (eg. the filename that was opened). Used to generate
|
244 | Error messages
|
245 | - `passphrase` -- Optional String, encryption passphrase used to decrypt an
|
246 | encrypted PEM file
|
247 |
|
248 | ### `generatePrivateKey(type[, options])`
|
249 |
|
250 | Generates a new private key of a certain key type, from random data.
|
251 |
|
252 | Parameters
|
253 |
|
254 | - `type` -- String, type of key to generate. Currently supported are `'ecdsa'`
|
255 | and `'ed25519'`
|
256 | - `options` -- optional Object, with keys:
|
257 | - `curve` -- optional String, for `'ecdsa'` keys, specifies the curve to use.
|
258 | If ECDSA is specified and this option is not given, defaults to
|
259 | using `'nistp256'`.
|
260 |
|
261 | ### `PrivateKey.isPrivateKey(obj)`
|
262 |
|
263 | Returns `true` if the given object is a valid `PrivateKey` object created by a
|
264 | version of `sshpk` compatible with this one.
|
265 |
|
266 | Parameters
|
267 |
|
268 | - `obj` -- Object to identify
|
269 |
|
270 | ### `PrivateKey#type`
|
271 |
|
272 | String, the type of key. Valid options are `rsa`, `dsa`, `ecdsa`.
|
273 |
|
274 | ### `PrivateKey#size`
|
275 |
|
276 | Integer, "size" of the key in bits. For RSA/DSA this is the size of the modulus;
|
277 | for ECDSA this is the bit size of the curve in use.
|
278 |
|
279 | ### `PrivateKey#curve`
|
280 |
|
281 | Only present if `this.type === 'ecdsa'`, string containing the name of the
|
282 | named curve used with this key. Possible values include `nistp256`, `nistp384`
|
283 | and `nistp521`.
|
284 |
|
285 | ### `PrivateKey#toBuffer([format = 'pkcs1'])`
|
286 |
|
287 | Convert the key into a given data format and return the serialized key as
|
288 | a Buffer.
|
289 |
|
290 | Parameters
|
291 |
|
292 | - `format` -- String name of format to use, valid options are listed under
|
293 | `parsePrivateKey`. Note that ED25519 keys default to `openssh`
|
294 | format instead (as they have no `pkcs1` representation).
|
295 |
|
296 | ### `PrivateKey#toString([format = 'pkcs1'])`
|
297 |
|
298 | Same as `this.toBuffer(format).toString()`.
|
299 |
|
300 | ### `PrivateKey#toPublic()`
|
301 |
|
302 | Extract just the public part of this private key, and return it as a `Key`
|
303 | object.
|
304 |
|
305 | ### `PrivateKey#fingerprint([algorithm = 'sha256'])`
|
306 |
|
307 | Same as `this.toPublic().fingerprint()`.
|
308 |
|
309 | ### `PrivateKey#createVerify([hashAlgorithm])`
|
310 |
|
311 | Same as `this.toPublic().createVerify()`.
|
312 |
|
313 | ### `PrivateKey#createSign([hashAlgorithm])`
|
314 |
|
315 | Creates a `crypto.Sign` specialized to use this PrivateKey (and the correct
|
316 | key algorithm to match it). The returned Signer has the same API as a regular
|
317 | one, except that the `sign()` function takes no arguments, and returns a
|
318 | `Signature` object.
|
319 |
|
320 | Parameters
|
321 |
|
322 | - `hashAlgorithm` -- optional String name of hash algorithm to use, any
|
323 | supported by OpenSSL are valid, usually including
|
324 | `sha1`, `sha256`.
|
325 |
|
326 | `v.sign()` Parameters
|
327 |
|
328 | - none
|
329 |
|
330 | ### `PrivateKey#derive(newType)`
|
331 |
|
332 | Derives a related key of type `newType` from this key. Currently this is
|
333 | only supported to change between `ed25519` and `curve25519` keys which are
|
334 | stored with the same private key (but usually distinct public keys in order
|
335 | to avoid degenerate keys that lead to a weak Diffie-Hellman exchange).
|
336 |
|
337 | Parameters
|
338 |
|
339 | - `newType` -- String, type of key to derive, either `ed25519` or `curve25519`
|
340 |
|
341 | ## Fingerprints
|
342 |
|
343 | ### `parseFingerprint(fingerprint[, options])`
|
344 |
|
345 | Pre-parses a fingerprint, creating a `Fingerprint` object that can be used to
|
346 | quickly locate a key by using the `Fingerprint#matches` function.
|
347 |
|
348 | Parameters
|
349 |
|
350 | - `fingerprint` -- String, the fingerprint value, in any supported format
|
351 | - `options` -- Optional Object, with properties:
|
352 | - `algorithms` -- Array of strings, names of hash algorithms to limit
|
353 | support to. If `fingerprint` uses a hash algorithm not on
|
354 | this list, throws `InvalidAlgorithmError`.
|
355 | - `hashType` -- String, the type of hash the fingerprint uses, either `ssh`
|
356 | or `spki` (normally auto-detected based on the format, but
|
357 | can be overridden)
|
358 | - `type` -- String, the entity this fingerprint identifies, either `key` or
|
359 | `certificate`
|
360 |
|
361 | ### `Fingerprint.isFingerprint(obj)`
|
362 |
|
363 | Returns `true` if the given object is a valid `Fingerprint` object created by a
|
364 | version of `sshpk` compatible with this one.
|
365 |
|
366 | Parameters
|
367 |
|
368 | - `obj` -- Object to identify
|
369 |
|
370 | ### `Fingerprint#toString([format])`
|
371 |
|
372 | Returns a fingerprint as a string, in the given format.
|
373 |
|
374 | Parameters
|
375 |
|
376 | - `format` -- Optional String, format to use, valid options are `hex` and
|
377 | `base64`. If this `Fingerprint` uses the `md5` algorithm, the
|
378 | default format is `hex`. Otherwise, the default is `base64`.
|
379 |
|
380 | ### `Fingerprint#matches(keyOrCertificate)`
|
381 |
|
382 | Verifies whether or not this `Fingerprint` matches a given `Key` or
|
383 | `Certificate`. This function uses double-hashing to avoid leaking timing
|
384 | information. Returns a boolean.
|
385 |
|
386 | Note that a `Key`-type Fingerprint will always return `false` if asked to match
|
387 | a `Certificate` and vice versa.
|
388 |
|
389 | Parameters
|
390 |
|
391 | - `keyOrCertificate` -- a `Key` object or `Certificate` object, the entity to
|
392 | match this fingerprint against
|
393 |
|
394 | ## Signatures
|
395 |
|
396 | ### `parseSignature(signature, algorithm, format)`
|
397 |
|
398 | Parses a signature in a given format, creating a `Signature` object. Useful
|
399 | for converting between the SSH and ASN.1 (PKCS/OpenSSL) signature formats, and
|
400 | also returned as output from `PrivateKey#createSign().sign()`.
|
401 |
|
402 | A Signature object can also be passed to a verifier produced by
|
403 | `Key#createVerify()` and it will automatically be converted internally into the
|
404 | correct format for verification.
|
405 |
|
406 | Parameters
|
407 |
|
408 | - `signature` -- a Buffer (binary) or String (base64), data of the actual
|
409 | signature in the given format
|
410 | - `algorithm` -- a String, name of the algorithm to be used, possible values
|
411 | are `rsa`, `dsa`, `ecdsa`
|
412 | - `format` -- a String, either `asn1` or `ssh`
|
413 |
|
414 | ### `Signature.isSignature(obj)`
|
415 |
|
416 | Returns `true` if the given object is a valid `Signature` object created by a
|
417 | version of `sshpk` compatible with this one.
|
418 |
|
419 | Parameters
|
420 |
|
421 | - `obj` -- Object to identify
|
422 |
|
423 | ### `Signature#toBuffer([format = 'asn1'])`
|
424 |
|
425 | Converts a Signature to the given format and returns it as a Buffer.
|
426 |
|
427 | Parameters
|
428 |
|
429 | - `format` -- a String, either `asn1` or `ssh`
|
430 |
|
431 | ### `Signature#toString([format = 'asn1'])`
|
432 |
|
433 | Same as `this.toBuffer(format).toString('base64')`.
|
434 |
|
435 | ## Certificates
|
436 |
|
437 | `sshpk` includes basic support for parsing certificates in X.509 (PEM) format
|
438 | and the OpenSSH certificate format. This feature is intended to be used mainly
|
439 | to access basic metadata about certificates, extract public keys from them, and
|
440 | also to generate simple self-signed certificates from an existing key.
|
441 |
|
442 | Notably, there is no implementation of CA chain-of-trust verification, and only
|
443 | very minimal support for key usage restrictions. Please do the security world
|
444 | a favour, and DO NOT use this code for certificate verification in the
|
445 | traditional X.509 CA chain style.
|
446 |
|
447 | ### `parseCertificate(data, format)`
|
448 |
|
449 | Parameters
|
450 |
|
451 | - `data` -- a Buffer or String
|
452 | - `format` -- a String, format to use, one of `'openssh'`, `'pem'` (X.509 in a
|
453 | PEM wrapper), or `'x509'` (raw DER encoded)
|
454 |
|
455 | ### `createSelfSignedCertificate(subject, privateKey[, options])`
|
456 |
|
457 | Parameters
|
458 |
|
459 | - `subject` -- an Identity, the subject of the certificate
|
460 | - `privateKey` -- a PrivateKey, the key of the subject: will be used both to be
|
461 | placed in the certificate and also to sign it (since this is
|
462 | a self-signed certificate)
|
463 | - `options` -- optional Object, with keys:
|
464 | - `lifetime` -- optional Number, lifetime of the certificate from now in
|
465 | seconds
|
466 | - `validFrom`, `validUntil` -- optional Dates, beginning and end of
|
467 | certificate validity period. If given
|
468 | `lifetime` will be ignored
|
469 | - `serial` -- optional Buffer, the serial number of the certificate
|
470 | - `purposes` -- optional Array of String, X.509 key usage restrictions
|
471 |
|
472 | ### `createCertificate(subject, key, issuer, issuerKey[, options])`
|
473 |
|
474 | Parameters
|
475 |
|
476 | - `subject` -- an Identity, the subject of the certificate
|
477 | - `key` -- a Key, the public key of the subject
|
478 | - `issuer` -- an Identity, the issuer of the certificate who will sign it
|
479 | - `issuerKey` -- a PrivateKey, the issuer's private key for signing
|
480 | - `options` -- optional Object, with keys:
|
481 | - `lifetime` -- optional Number, lifetime of the certificate from now in
|
482 | seconds
|
483 | - `validFrom`, `validUntil` -- optional Dates, beginning and end of
|
484 | certificate validity period. If given
|
485 | `lifetime` will be ignored
|
486 | - `serial` -- optional Buffer, the serial number of the certificate
|
487 | - `purposes` -- optional Array of String, X.509 key usage restrictions
|
488 |
|
489 | ### `Certificate#subjects`
|
490 |
|
491 | Array of `Identity` instances describing the subject of this certificate.
|
492 |
|
493 | ### `Certificate#issuer`
|
494 |
|
495 | The `Identity` of the Certificate's issuer (signer).
|
496 |
|
497 | ### `Certificate#subjectKey`
|
498 |
|
499 | The public key of the subject of the certificate, as a `Key` instance.
|
500 |
|
501 | ### `Certificate#issuerKey`
|
502 |
|
503 | The public key of the signing issuer of this certificate, as a `Key` instance.
|
504 | May be `undefined` if the issuer's key is unknown (e.g. on an X509 certificate).
|
505 |
|
506 | ### `Certificate#serial`
|
507 |
|
508 | The serial number of the certificate. As this is normally a 64-bit or wider
|
509 | integer, it is returned as a Buffer.
|
510 |
|
511 | ### `Certificate#purposes`
|
512 |
|
513 | Array of Strings indicating the X.509 key usage purposes that this certificate
|
514 | is valid for. The possible strings at the moment are:
|
515 |
|
516 | * `'signature'` -- key can be used for digital signatures
|
517 | * `'identity'` -- key can be used to attest about the identity of the signer
|
518 | (X.509 calls this `nonRepudiation`)
|
519 | * `'codeSigning'` -- key can be used to sign executable code
|
520 | * `'keyEncryption'` -- key can be used to encrypt other keys
|
521 | * `'encryption'` -- key can be used to encrypt data (only applies for RSA)
|
522 | * `'keyAgreement'` -- key can be used for key exchange protocols such as
|
523 | Diffie-Hellman
|
524 | * `'ca'` -- key can be used to sign other certificates (is a Certificate
|
525 | Authority)
|
526 | * `'crl'` -- key can be used to sign Certificate Revocation Lists (CRLs)
|
527 |
|
528 | ### `Certificate#getExtension(nameOrOid)`
|
529 |
|
530 | Retrieves information about a certificate extension, if present, or returns
|
531 | `undefined` if not. The string argument `nameOrOid` should be either the OID
|
532 | (for X509 extensions) or the name (for OpenSSH extensions) of the extension
|
533 | to retrieve.
|
534 |
|
535 | The object returned will have the following properties:
|
536 |
|
537 | * `format` -- String, set to either `'x509'` or `'openssh'`
|
538 | * `name` or `oid` -- String, only one set based on value of `format`
|
539 | * `data` -- Buffer, the raw data inside the extension
|
540 |
|
541 | ### `Certificate#getExtensions()`
|
542 |
|
543 | Returns an Array of all present certificate extensions, in the same manner and
|
544 | format as `getExtension()`.
|
545 |
|
546 | ### `Certificate#isExpired([when])`
|
547 |
|
548 | Tests whether the Certificate is currently expired (i.e. the `validFrom` and
|
549 | `validUntil` dates specify a range of time that does not include the current
|
550 | time).
|
551 |
|
552 | Parameters
|
553 |
|
554 | - `when` -- optional Date, if specified, tests whether the Certificate was or
|
555 | will be expired at the specified time instead of now
|
556 |
|
557 | Returns a Boolean.
|
558 |
|
559 | ### `Certificate#isSignedByKey(key)`
|
560 |
|
561 | Tests whether the Certificate was validly signed by the given (public) Key.
|
562 |
|
563 | Parameters
|
564 |
|
565 | - `key` -- a Key instance
|
566 |
|
567 | Returns a Boolean.
|
568 |
|
569 | ### `Certificate#isSignedBy(certificate)`
|
570 |
|
571 | Tests whether this Certificate was validly signed by the subject of the given
|
572 | certificate. Also tests that the issuer Identity of this Certificate and the
|
573 | subject Identity of the other Certificate are equivalent.
|
574 |
|
575 | Parameters
|
576 |
|
577 | - `certificate` -- another Certificate instance
|
578 |
|
579 | Returns a Boolean.
|
580 |
|
581 | ### `Certificate#fingerprint([hashAlgo])`
|
582 |
|
583 | Returns the X509-style fingerprint of the entire certificate (as a Fingerprint
|
584 | instance). This matches what a web-browser or similar would display as the
|
585 | certificate fingerprint and should not be confused with the fingerprint of the
|
586 | subject's public key.
|
587 |
|
588 | Parameters
|
589 |
|
590 | - `hashAlgo` -- an optional String, any hash function name
|
591 |
|
592 | ### `Certificate#toBuffer([format])`
|
593 |
|
594 | Serializes the Certificate to a Buffer and returns it.
|
595 |
|
596 | Parameters
|
597 |
|
598 | - `format` -- an optional String, output format, one of `'openssh'`, `'pem'` or
|
599 | `'x509'`. Defaults to `'x509'`.
|
600 |
|
601 | Returns a Buffer.
|
602 |
|
603 | ### `Certificate#toString([format])`
|
604 |
|
605 | - `format` -- an optional String, output format, one of `'openssh'`, `'pem'` or
|
606 | `'x509'`. Defaults to `'pem'`.
|
607 |
|
608 | Returns a String.
|
609 |
|
610 | ## Certificate identities
|
611 |
|
612 | ### `identityForHost(hostname)`
|
613 |
|
614 | Constructs a host-type Identity for a given hostname.
|
615 |
|
616 | Parameters
|
617 |
|
618 | - `hostname` -- the fully qualified DNS name of the host
|
619 |
|
620 | Returns an Identity instance.
|
621 |
|
622 | ### `identityForUser(uid)`
|
623 |
|
624 | Constructs a user-type Identity for a given UID.
|
625 |
|
626 | Parameters
|
627 |
|
628 | - `uid` -- a String, user identifier (login name)
|
629 |
|
630 | Returns an Identity instance.
|
631 |
|
632 | ### `identityForEmail(email)`
|
633 |
|
634 | Constructs an email-type Identity for a given email address.
|
635 |
|
636 | Parameters
|
637 |
|
638 | - `email` -- a String, email address
|
639 |
|
640 | Returns an Identity instance.
|
641 |
|
642 | ### `identityFromDN(dn)`
|
643 |
|
644 | Parses an LDAP-style DN string (e.g. `'CN=foo, C=US'`) and turns it into an
|
645 | Identity instance.
|
646 |
|
647 | Parameters
|
648 |
|
649 | - `dn` -- a String
|
650 |
|
651 | Returns an Identity instance.
|
652 |
|
653 | ### `identityFromArray(arr)`
|
654 |
|
655 | Constructs an Identity from an array of DN components (see `Identity#toArray()`
|
656 | for the format).
|
657 |
|
658 | Parameters
|
659 |
|
660 | - `arr` -- an Array of Objects, DN components with `name` and `value`
|
661 |
|
662 | Returns an Identity instance.
|
663 |
|
664 |
|
665 | Supported attributes in DNs:
|
666 |
|
667 | | Attribute name | OID |
|
668 | | -------------- | --- |
|
669 | | `cn` | `2.5.4.3` |
|
670 | | `o` | `2.5.4.10` |
|
671 | | `ou` | `2.5.4.11` |
|
672 | | `l` | `2.5.4.7` |
|
673 | | `s` | `2.5.4.8` |
|
674 | | `c` | `2.5.4.6` |
|
675 | | `sn` | `2.5.4.4` |
|
676 | | `postalCode` | `2.5.4.17` |
|
677 | | `serialNumber` | `2.5.4.5` |
|
678 | | `street` | `2.5.4.9` |
|
679 | | `x500UniqueIdentifier` | `2.5.4.45` |
|
680 | | `role` | `2.5.4.72` |
|
681 | | `telephoneNumber` | `2.5.4.20` |
|
682 | | `description` | `2.5.4.13` |
|
683 | | `dc` | `0.9.2342.19200300.100.1.25` |
|
684 | | `uid` | `0.9.2342.19200300.100.1.1` |
|
685 | | `mail` | `0.9.2342.19200300.100.1.3` |
|
686 | | `title` | `2.5.4.12` |
|
687 | | `gn` | `2.5.4.42` |
|
688 | | `initials` | `2.5.4.43` |
|
689 | | `pseudonym` | `2.5.4.65` |
|
690 |
|
691 | ### `Identity#toString()`
|
692 |
|
693 | Returns the identity as an LDAP-style DN string.
|
694 | e.g. `'CN=foo, O=bar corp, C=us'`
|
695 |
|
696 | ### `Identity#type`
|
697 |
|
698 | The type of identity. One of `'host'`, `'user'`, `'email'` or `'unknown'`
|
699 |
|
700 | ### `Identity#hostname`
|
701 | ### `Identity#uid`
|
702 | ### `Identity#email`
|
703 |
|
704 | Set when `type` is `'host'`, `'user'`, or `'email'`, respectively. Strings.
|
705 |
|
706 | ### `Identity#cn`
|
707 |
|
708 | The value of the first `CN=` in the DN, if any. It's probably better to use
|
709 | the `#get()` method instead of this property.
|
710 |
|
711 | ### `Identity#get(name[, asArray])`
|
712 |
|
713 | Returns the value of a named attribute in the Identity DN. If there is no
|
714 | attribute of the given name, returns `undefined`. If multiple components
|
715 | of the DN contain an attribute of this name, an exception is thrown unless
|
716 | the `asArray` argument is given as `true` -- then they will be returned as
|
717 | an Array in the same order they appear in the DN.
|
718 |
|
719 | Parameters
|
720 |
|
721 | - `name` -- a String
|
722 | - `asArray` -- an optional Boolean
|
723 |
|
724 | ### `Identity#toArray()`
|
725 |
|
726 | Returns the Identity as an Array of DN component objects. This looks like:
|
727 |
|
728 | ```js
|
729 | [ {
|
730 | "name": "cn",
|
731 | "value": "Joe Bloggs"
|
732 | },
|
733 | {
|
734 | "name": "o",
|
735 | "value": "Organisation Ltd"
|
736 | } ]
|
737 | ```
|
738 |
|
739 | Each object has a `name` and a `value` property. The returned objects may be
|
740 | safely modified.
|
741 |
|
742 | Errors
|
743 | ------
|
744 |
|
745 | ### `InvalidAlgorithmError`
|
746 |
|
747 | The specified algorithm is not valid, either because it is not supported, or
|
748 | because it was not included on a list of allowed algorithms.
|
749 |
|
750 | Thrown by `Fingerprint.parse`, `Key#fingerprint`.
|
751 |
|
752 | Properties
|
753 |
|
754 | - `algorithm` -- the algorithm that could not be validated
|
755 |
|
756 | ### `FingerprintFormatError`
|
757 |
|
758 | The fingerprint string given could not be parsed as a supported fingerprint
|
759 | format, or the specified fingerprint format is invalid.
|
760 |
|
761 | Thrown by `Fingerprint.parse`, `Fingerprint#toString`.
|
762 |
|
763 | Properties
|
764 |
|
765 | - `fingerprint` -- if caused by a fingerprint, the string value given
|
766 | - `format` -- if caused by an invalid format specification, the string value given
|
767 |
|
768 | ### `KeyParseError`
|
769 |
|
770 | The key data given could not be parsed as a valid key.
|
771 |
|
772 | Properties
|
773 |
|
774 | - `keyName` -- `filename` that was given to `parseKey`
|
775 | - `format` -- the `format` that was trying to parse the key (see `parseKey`)
|
776 | - `innerErr` -- the inner Error thrown by the format parser
|
777 |
|
778 | ### `KeyEncryptedError`
|
779 |
|
780 | The key is encrypted with a symmetric key (ie, it is password protected). The
|
781 | parsing operation would succeed if it was given the `passphrase` option.
|
782 |
|
783 | Properties
|
784 |
|
785 | - `keyName` -- `filename` that was given to `parseKey`
|
786 | - `format` -- the `format` that was trying to parse the key (currently can only
|
787 | be `"pem"`)
|
788 |
|
789 | ### `CertificateParseError`
|
790 |
|
791 | The certificate data given could not be parsed as a valid certificate.
|
792 |
|
793 | Properties
|
794 |
|
795 | - `certName` -- `filename` that was given to `parseCertificate`
|
796 | - `format` -- the `format` that was trying to parse the key
|
797 | (see `parseCertificate`)
|
798 | - `innerErr` -- the inner Error thrown by the format parser
|
799 |
|
800 | Friends of sshpk
|
801 | ----------------
|
802 |
|
803 | * [`sshpk-agent`](https://github.com/arekinath/node-sshpk-agent) is a library
|
804 | for speaking the `ssh-agent` protocol from node.js, which uses `sshpk`
|