@@ -742,6 +742,55 @@ and their processing can be delayed due to packet loss or reordering. However,
742742smaller fragments add extra TLS framing bytes and CPU overhead, which may
743743decrease overall server throughput.
744744
745+ ## tls.checkServerIdentity(host, cert)
746+ <!-- YAML
747+ added: v0.8.4
748+ -->
749+
750+ * ` host ` {string} The hostname to verify the certificate against
751+ * ` cert ` {Object} An object representing the peer's certificate. The returned
752+ object has some properties corresponding to the fields of the certificate.
753+
754+ Verifies the certificate ` cert ` is issued to host ` host ` .
755+
756+ Returns {Error} object, populating it with the reason, host and cert on failure.
757+ On success, returns {undefined}.
758+
759+ * Note* : This function can be overwritten by providing alternative function
760+ as part of the ` options.checkServerIdentity ` option passed to ` tls.connect() ` .
761+ The overwriting function can call ` tls.checkServerIdentity() ` of course, to augment
762+ the checks done with additional verification.
763+
764+ * Note* : This function is only called if the certificate passed all other checks, such as
765+ being issued by trusted CA (` options.ca ` ).
766+
767+ The cert object contains the parsed certificate and will have a structure similar to:
768+
769+ ``` text
770+ { subject:
771+ { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ],
772+ CN: '*.nodejs.org' },
773+ issuer:
774+ { C: 'GB',
775+ ST: 'Greater Manchester',
776+ L: 'Salford',
777+ O: 'COMODO CA Limited',
778+ CN: 'COMODO RSA Domain Validation Secure Server CA' },
779+ subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org',
780+ infoAccess:
781+ { 'CA Issuers - URI':
782+ [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ],
783+ 'OCSP - URI': [ 'http://ocsp.comodoca.com' ] },
784+ modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1',
785+ exponent: '0x10001',
786+ valid_from: 'Aug 14 00:00:00 2017 GMT',
787+ valid_to: 'Nov 20 23:59:59 2019 GMT',
788+ fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D',
789+ ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ],
790+ serialNumber: '66593D57F20CBC573E433381B5FEC280',
791+ raw: <Buffer ....> }
792+ ```
793+
745794## tls.connect(options[ , callback] )
746795<!-- YAML
747796added: v0.11.3
@@ -793,9 +842,10 @@ changes:
793842 extension.
794843 * ` checkServerIdentity(servername, cert) ` {Function} A callback function
795844 to be used (instead of the builtin ` tls.checkServerIdentity() ` function)
796- when checking the server's hostname against the certificate.
797- This should return an {Error} if verification fails. The method should return
798- ` undefined ` if the ` servername ` and ` cert ` are verified.
845+ when checking the server's hostname (or the provided ` servername ` when
846+ explicitly set) against the certificate. This should return an {Error} if
847+ verification fails. The method should return ` undefined ` if the ` servername `
848+ and ` cert ` are verified.
799849 * ` session ` {Buffer} A ` Buffer ` instance, containing TLS session.
800850 * ` minDHSize ` {number} Minimum size of the DH parameter in bits to accept a
801851 TLS connection. When a server offers a DH parameter with a size less
0 commit comments