1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: document tls.checkServerIdentity

Browse Source 
The funciton was added in eb2ca104628e415fc73c330cdd76fca77bf5ba97

PR-URL: https://github.com/nodejs/node/pull/17203
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
This commit is contained in:
Hannes Magnusson 2017-11-22 12:28:59 -08:00 committed by Anna Henningsen
parent da429c3d20
commit df63e53458
No known key found for this signature in database
GPG Key ID: 9C63F3A6CD2AD8F9
2 changed files with 53 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
doc/api/tls.md
View File

@ -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
@ -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

1
lib/tls.js
View File

@ -236,7 +236,6 @@ exports.parseCertString = internalUtil.deprecate(
'Please use querystring.parse() instead.',
'DEP0076');
// Public API
exports.createSecureContext = require('_tls_common').createSecureContext;
exports.SecureContext = require('_tls_common').SecureContext;
exports.TLSSocket = require('_tls_wrap').TLSSocket;