twitst4tz

twitter statistics web application
Log | Files | Refs | README | LICENSE

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`