diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 70ecb0d4c64cad..6ae651a68a9e49 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -2471,11 +2471,16 @@ added: v15.6.0 * `email` {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`. @@ -2485,15 +2490,31 @@ added: v15.6.0 Checks whether the certificate matches the given email address. +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 email +address, 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 email addresses. + +If the `'subject'` option is set to `'never'`, the certificate subject is never +considered, even if the certificate contains no subject alternative names. + ### `x509.checkHost(name[, options])` * `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`. @@ -2509,6 +2530,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[, options])`