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 smaller fragments add extra TLS framing bytes and CPU overhead, which may
decrease overall server throughput. 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]) ## tls.connect(options[, callback])
<!-- YAML <!-- YAML
added: v0.11.3 added: v0.11.3
@ -793,9 +842,10 @@ changes:
extension. extension.
* `checkServerIdentity(servername, cert)` {Function} A callback function * `checkServerIdentity(servername, cert)` {Function} A callback function
   to be used (instead of the builtin `tls.checkServerIdentity()` function)    to be used (instead of the builtin `tls.checkServerIdentity()` function)
when checking the server's hostname against the certificate. when checking the server's hostname (or the provided `servername` when
This should return an {Error} if verification fails. The method should return explicitly set) against the certificate. This should return an {Error} if
`undefined` if the `servername` and `cert` are verified. verification fails. The method should return `undefined` if the `servername`
and `cert` are verified.
* `session` {Buffer} A `Buffer` instance, containing TLS session. * `session` {Buffer} A `Buffer` instance, containing TLS session.
* `minDHSize` {number} Minimum size of the DH parameter in bits to accept a * `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 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.', 'Please use querystring.parse() instead.',
'DEP0076'); 'DEP0076');
// Public API
exports.createSecureContext = require('_tls_common').createSecureContext; exports.createSecureContext = require('_tls_common').createSecureContext;
exports.SecureContext = require('_tls_common').SecureContext; exports.SecureContext = require('_tls_common').SecureContext;
exports.TLSSocket = require('_tls_wrap').TLSSocket; exports.TLSSocket = require('_tls_wrap').TLSSocket;