doc: document tls.checkServerIdentity

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>

doc/api/tls.md

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

lib/tls.js

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