Commit 7849d53
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>1 parent a596577 commit 7849d53
2 files changed
Lines changed: 53 additions & 4 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -742,6 +742,55 @@ and their processing can be delayed due to packet loss or reordering. However, | |||
| 742 | 742 | smaller fragments add extra TLS framing bytes and CPU overhead, which may | |
| 743 | 743 | decrease overall server throughput. | |
| 744 | 744 | ||
| 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 | + | ||
| 745 | 794 | ## tls.connect(options[, callback]) | |
| 746 | 795 | <!-- YAML | |
| 747 | 796 | added: v0.11.3 | |
@@ -793,9 +842,10 @@ changes: | |||
| 793 | 842 | extension. | |
| 794 | 843 | * `checkServerIdentity(servername, cert)` {Function} A callback function | |
| 795 | 844 | 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. | ||
| 799 | 849 | * `session` {Buffer} A `Buffer` instance, containing TLS session. | |
| 800 | 850 | * `minDHSize` {number} Minimum size of the DH parameter in bits to accept a | |
| 801 | 851 | TLS connection. When a server offers a DH parameter with a size less | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -236,7 +236,6 @@ exports.parseCertString = internalUtil.deprecate( | |||
| 236 | 236 | 'Please use querystring.parse() instead.', | |
| 237 | 237 | 'DEP0076'); | |
| 238 | 238 | ||
| 239 | - // Public API | ||
| 240 | 239 | exports.createSecureContext = require('_tls_common').createSecureContext; | |
| 241 | 240 | exports.SecureContext = require('_tls_common').SecureContext; | |
| 242 | 241 | exports.TLSSocket = require('_tls_wrap').TLSSocket; | |
0 commit comments