diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 38ee1e79e9346c..23ba770af30d8d 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -2472,6 +2472,9 @@ added: v15.6.0 * `name` {string} * `options` {Object} - * `subject` {string} `'always'` or `'never'`. **Default:** `'always'`. + * `subject` {string} `'default'`, `'always'`, or `'never'`. + **Default:** `'always'`. * `wildcards` {boolean} **Default:** `true`. * `partialWildcards` {boolean} **Default:** `true`. * `multiLabelWildcards` {boolean} **Default:** `false`. @@ -2511,6 +2535,18 @@ 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. +If the `'subject'` option is set to `'always'` and if the subject alternative +name extension either does not exist or does not contain a matching DNS name, +the certificate subject is considered. + +If the `'subject'` option is set to `'default'`, the certificate subject is only +considered if the subject alternative name extension either does not exist or +does not contain any DNS names. This behavior is consistent with [RFC 2818][] +("HTTP Over TLS"). + +If the `'subject'` option is set to `'never'`, the certificate subject is never +considered, even if the certificate contains no subject alternative names. + ### `x509.checkIP(ip)`