diff options
| author | Tobias Nießen <tniessen@tnie.de> | 2022-01-17 17:35:47 +0300 |
|---|---|---|
| committer | Tobias Nießen <tniessen@tnie.de> | 2022-01-19 18:05:32 +0300 |
| commit | da1b59fc1388f8bffab870d80efa96db49439b6e (patch) | |
| tree | 409222019979fd5de213d7f55c3418fed56141bb /doc/api/crypto.md | |
| parent | 119519e1da2be1f180e8d66bd0bb79403624ea73 (diff) | |
crypto: support RFC 2818 compatible checkHost
The 'subject' option should not only accept the values 'always' and
'never' because neither is compatible with RFC 2818, i.e., HTTPS. This
change adds a third value 'default', which implies the behavior that
HTTPS mandates.
The new 'default' case matches the default behavior of OpenSSL for both
DNS names and email addresses.
Future Node.js versions should change the default option value from
'always' to 'default'.
Refs: https://github.com/nodejs/node/pull/36804
PR-URL: https://github.com/nodejs/node/pull/41569
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Diffstat (limited to 'doc/api/crypto.md')
| -rw-r--r-- | doc/api/crypto.md | 38 |
1 files changed, 36 insertions, 2 deletions
diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 3efc08631e0..4d9493ac5de 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -2471,11 +2471,16 @@ added: v15.6.0 <!-- YAML added: v15.6.0 +changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/41569 + description: The subject option can now be set to `'default'`. --> * `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])` <!-- YAML added: v15.6.0 +changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/41569 + description: The subject option can now be set to `'default'`. --> * `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])` <!-- YAML @@ -5937,6 +5970,7 @@ See the [list of SSL OP Flags][] for details. [OpenSSL's SPKAC implementation]: https://www.openssl.org/docs/man1.1.0/apps/openssl-spkac.html [RFC 1421]: https://www.rfc-editor.org/rfc/rfc1421.txt [RFC 2412]: https://www.rfc-editor.org/rfc/rfc2412.txt +[RFC 2818]: https://www.rfc-editor.org/rfc/rfc2818.txt [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt [RFC 3610]: https://www.rfc-editor.org/rfc/rfc3610.txt [RFC 4055]: https://www.rfc-editor.org/rfc/rfc4055.txt |