From df5f0736399570921557356c979dd723427f30c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Tue, 11 Jan 2022 03:39:51 +0100 Subject: [PATCH] doc: correct checkHost behavior with wildcards etc 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: https://github.com/nodejs/node/pull/36804 --- doc/api/crypto.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/api/crypto.md b/doc/api/crypto.md index f2271f32d9f104..4dbccff3122d36 100644 --- 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])`