README.md (24643B)
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`