diff options
author | Hannes Magnusson <hannes.magnusson@creditkarma.com> | 2017-11-22 12:28:59 -0800 |
---|---|---|
committer | Anna Henningsen <anna@addaleax.net> | 2017-12-01 20:44:52 +0100 |
commit | df63e534584a54dcf02b37446e1e821382e3cef3 (patch) | |
tree | b6fa1918f8059f95654b23e17b99ff40d3e487d6 /doc/api/tls.md | |
parent | da429c3d20ee31873eb9d76b8142f68fb3514408 (diff) | |
download | android-node-v8-df63e534584a54dcf02b37446e1e821382e3cef3.tar.gz android-node-v8-df63e534584a54dcf02b37446e1e821382e3cef3.tar.bz2 android-node-v8-df63e534584a54dcf02b37446e1e821382e3cef3.zip |
doc: document tls.checkServerIdentity
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>
Diffstat (limited to 'doc/api/tls.md')
-rw-r--r-- | doc/api/tls.md | 56 |
1 files changed, 53 insertions, 3 deletions
diff --git a/doc/api/tls.md b/doc/api/tls.md index a4de11f728..f9ff5ace5d 100644 --- a/doc/api/tls.md +++ b/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 |