doc: correct checkHost behavior with wildcards etc

tniessen · danielleadams · commit d4458162a4e1 · 2022-01-31T23:55:05.000-05:00
The current documentation is inaccurate in that checkHost does not necessarily return the given host name, but instead returns the subject name that matched the given host name. Refs: #36804 PR-URL: #41468 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Filip Skokan <panva.ip@gmail.com>
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
@@ -2498,11 +2498,17 @@ added: v15.6.0
   * `partialWildcards` {boolean} **Default:** `true`.
   * `multiLabelWildcards` {boolean} **Default:** `false`.
   * `singleLabelSubdomains` {boolean} **Default:** `false`.
-* Returns: {string|undefined} Returns `name` if the certificate matches,
-  `undefined` if it does not.
+* Returns: {string|undefined} Returns a subject name that matches `name`,
+  or `undefined` if no subject name matches `name`.
 
 Checks whether the certificate matches the given host name.
 
+If the certificate matches the given host name, the matching subject name is
+returned. The returned name might be an exact match (e.g., `foo.example.com`)
+or it might contain wildcards (e.g., `*.example.com`). Because host name
+comparisons are case-insensitive, the returned subject name might also differ
+from the given `name` in capitalization.
+
 ### `x509.checkIP(ip[, options])`
 
 <!-- YAML
