From 54fc810af2edc805dcfddc3fe7493f86036c7832 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Tue, 29 Mar 2022 19:55:41 +0200 Subject: [PATCH] doc: suggest checkHost in checkServerIdentity docs Refs: https://github.com/nodejs/node/pull/42470 PR-URL: https://github.com/nodejs/node/pull/42495 Reviewed-By: Luigi Pinca Reviewed-By: Rich Trott --- doc/api/tls.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/api/tls.md b/doc/api/tls.md index 3fd965ca0567eb..f6d1b609943925 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -1513,6 +1513,11 @@ Verifies the certificate `cert` is issued to `hostname`. Returns {Error} object, populating it with `reason`, `host`, and `cert` on failure. On success, returns {undefined}. +This function is intended to be used in combination with the +`checkServerIdentity` option that can be passed to [`tls.connect()`][] and as +such operates on a [certificate object][]. For other purposes, consider using +[`x509.checkHost()`][] instead. + This function can be overwritten by providing an alternative function as the `options.checkServerIdentity` option that is passed to `tls.connect()`. The overwriting function can call `tls.checkServerIdentity()` of course, to augment @@ -2243,6 +2248,7 @@ added: v11.4.0 [`tls.createServer()`]: #tlscreateserveroptions-secureconnectionlistener [`tls.getCiphers()`]: #tlsgetciphers [`tls.rootCertificates`]: #tlsrootcertificates +[`x509.checkHost()`]: crypto.md#x509checkhostname-options [asn1.js]: https://www.npmjs.com/package/asn1.js [certificate object]: #certificate-object [cipher list format]: https://www.openssl.org/docs/man1.1.1/man1/ciphers.html#CIPHER-LIST-FORMAT