Skip to content

Commit

Permalink
doc: document tls.checkServerIdentity
Browse files Browse the repository at this point in the history
The funciton was added in eb2ca10

PR-URL: #17203
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
  • Loading branch information
Hannes-Magnusson-CK authored and gibfahn committed Dec 20, 2017
1 parent e786fde commit a3d218d
Show file tree
Hide file tree
Showing 2 changed files with 53 additions and 4 deletions.
56 changes: 53 additions & 3 deletions doc/api/tls.md
Original file line number Diff line number Diff line change
Expand Up @@ -742,6 +742,55 @@ and their processing can be delayed due to packet loss or reordering. However,
smaller fragments add extra TLS framing bytes and CPU overhead, which may
decrease overall server throughput.

## tls.checkServerIdentity(host, cert)
<!-- YAML
added: v0.8.4
-->

* `host` {string} The hostname to verify the certificate against
* `cert` {Object} An object representing the peer's certificate. The returned
object has some properties corresponding to the fields of the certificate.

Verifies the certificate `cert` is issued to host `host`.

Returns {Error} object, populating it with the reason, host and cert on failure.
On success, returns {undefined}.

*Note*: This function can be overwritten by providing alternative function
as part of the `options.checkServerIdentity` option passed to `tls.connect()`.
The overwriting function can call `tls.checkServerIdentity()` of course, to augment
the checks done with additional verification.

*Note*: This function is only called if the certificate passed all other checks, such as
being issued by trusted CA (`options.ca`).

The cert object contains the parsed certificate and will have a structure similar to:

```text
{ subject:
{ OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
CN: '*.nodejs.org' },
issuer:
{ C: 'GB',
ST: 'Greater Manchester',
L: 'Salford',
O: 'COMODO CA Limited',
CN: 'COMODO RSA Domain Validation Secure Server CA' },
subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
infoAccess:
{ 'CA Issuers - URI':
[ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
exponent: '0x10001',
valid_from: 'Aug 14 00:00:00 2017 GMT',
valid_to: 'Nov 20 23:59:59 2019 GMT',
fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
serialNumber: '66593D57F20CBC573E433381B5FEC280',
raw: <Buffer ....> }
```

## tls.connect(options[, callback])
<!-- YAML
added: v0.11.3
Expand Down Expand Up @@ -793,9 +842,10 @@ changes:
extension.
* `checkServerIdentity(servername, cert)` {Function} A callback function
   to be used (instead of the builtin `tls.checkServerIdentity()` function)
when checking the server's hostname against the certificate.
This should return an {Error} if verification fails. The method should return
`undefined` if the `servername` and `cert` are verified.
when checking the server's hostname (or the provided `servername` when
explicitly set) against the certificate. This should return an {Error} if
verification fails. The method should return `undefined` if the `servername`
and `cert` are verified.
* `session` {Buffer} A `Buffer` instance, containing TLS session.
* `minDHSize` {number} Minimum size of the DH parameter in bits to accept a
TLS connection. When a server offers a DH parameter with a size less
Expand Down
1 change: 0 additions & 1 deletion lib/tls.js
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,6 @@ exports.parseCertString = function parseCertString(s) {
return out;
};

// Public API
exports.createSecureContext = require('_tls_common').createSecureContext;
exports.SecureContext = require('_tls_common').SecureContext;
exports.TLSSocket = require('_tls_wrap').TLSSocket;
Expand Down

0 comments on commit a3d218d

Please sign in to comment.