diff --git a/doc/api/cli.md b/doc/api/cli.md index 4c4b029cd34..a193b8e9eb8 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -1226,9 +1226,8 @@ priority than `--dns-result-order`. added: v6.0.0 --> -Enable [FIPS mode][] at startup. With OpenSSL 3, a configured provider named -`fips` must be available and initialize successfully. With OpenSSL 1.1.1, -Node.js must be built against a FIPS-capable OpenSSL. +Enable [FIPS mode][] at startup. A configured provider named `fips` must be +available and initialize successfully. ### `--enable-fips-indicator-events` @@ -2532,8 +2531,7 @@ added: v6.9.0 --> Load an OpenSSL configuration file on startup. The file can activate an -OpenSSL 3 FIPS provider or configure a FIPS-capable OpenSSL 1.1.1 build. See -[FIPS mode][]. +OpenSSL FIPS provider. See [FIPS mode][]. This option takes precedence over the `OPENSSL_CONF` environment variable. @@ -2545,7 +2543,7 @@ added: - v16.17.0 --> -Enable OpenSSL 3.0 legacy provider. For more information please see +Enable OpenSSL's legacy provider. For more information please see [OSSL\_PROVIDER-legacy][OSSL_PROVIDER-legacy]. ### `--openssl-shared-config` diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 085ccdcc9c0..1dcc1b21046 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -3751,8 +3751,8 @@ defaults to 16 bytes. `SIV` and `GCM-SIV` only support 16-byte authentication tags. The `ctsMode` and `xtsStandard` options configure parameters exposed by OpenSSL -providers. They are available only with OpenSSL 3.0 or later and a provider -that supports the corresponding parameter. `ctsMode` applies only to CBC-CTS +providers. They are not available with BoringSSL and require a provider that +supports the corresponding parameter. `ctsMode` applies only to CBC-CTS ciphers, and `xtsStandard` applies only to `sm4-xts`. Supplying either option for an available cipher implementation that does not support it throws an `ERR_CRYPTO_UNSUPPORTED_OPERATION` error. See [CBC-CTS mode][] and [XTS mode][] @@ -3860,8 +3860,8 @@ set if a different length is used. For `SIV` and `GCM-SIV`, the `authTagLength` option defaults to 16 bytes and only 16-byte authentication tags are supported. The `ctsMode` and `xtsStandard` options configure parameters exposed by OpenSSL -providers. They are available only with OpenSSL 3.0 or later and a provider -that supports the corresponding parameter. `ctsMode` applies only to CBC-CTS +providers. They are not available with BoringSSL and require a provider that +supports the corresponding parameter. `ctsMode` applies only to CBC-CTS ciphers, and `xtsStandard` applies only to `sm4-xts`. Supplying either option for an available cipher implementation that does not support it throws an `ERR_CRYPTO_UNSUPPORTED_OPERATION` error. See [CBC-CTS mode][] and [XTS mode][] @@ -4508,7 +4508,7 @@ Key decapsulation using a KEM algorithm with a private key. Supported key types and their KEM algorithms are: -* `'rsa'`[^openssl30] RSA Secret Value Encapsulation +* `'rsa'`[^noboringssl] RSA Secret Value Encapsulation * `'ec'`[^openssl32] DHKEM(P-256, HKDF-SHA256), DHKEM(P-384, HKDF-SHA256), DHKEM(P-521, HKDF-SHA256) * `'x25519'`[^openssl32] DHKEM(X25519, HKDF-SHA256) * `'x448'`[^openssl32] DHKEM(X448, HKDF-SHA512) @@ -4580,7 +4580,7 @@ Key encapsulation using a KEM algorithm with a public key. Supported key types and their KEM algorithms are: -* `'rsa'`[^openssl30] RSA Secret Value Encapsulation +* `'rsa'`[^noboringssl] RSA Secret Value Encapsulation * `'ec'`[^openssl32] DHKEM(P-256, HKDF-SHA256), DHKEM(P-384, HKDF-SHA256), DHKEM(P-521, HKDF-SHA256) * `'x25519'`[^openssl32] DHKEM(X25519, HKDF-SHA256) * `'x448'`[^openssl32] DHKEM(X448, HKDF-SHA512) @@ -5207,11 +5207,10 @@ added: v10.0.0 * Returns: {number} `1` if FIPS mode is enabled, `0` otherwise. A future semver-major release may change the return type of this API to a {boolean}. -With OpenSSL 3, this reports whether the default property query includes -`fips=yes`. It does not establish that a FIPS provider is loaded or validated. -It can return `1` even when a requested cryptographic implementation cannot be -fetched because no loaded provider supplies a match for `fips=yes`. See [FIPS -mode][]. +This reports whether the default property query includes `fips=yes`. It does not +establish that a FIPS provider is loaded or validated. It can return `1` even +when a requested cryptographic implementation cannot be fetched because no +loaded provider supplies a match for `fips=yes`. See [FIPS mode][]. ### `crypto.getHashes()` @@ -5231,10 +5230,9 @@ changes: This is the authoritative Node.js list of hash algorithms available to [`crypto.createHash()`][] and [`crypto.hash()`][] in the current process. With -OpenSSL 3 or later, the list depends on the loaded providers and the default -property query in effect when the list is first generated. Some listed -algorithms can require API-specific options, such as `outputLength` for XOF -hash functions. +OpenSSL, the list depends on the loaded providers and the default property query +in effect when the list is first generated. Some listed algorithms can require +API-specific options, such as `outputLength` for XOF hash functions. A listed hash algorithm is not necessarily supported by APIs that combine a digest with another cryptographic operation, such as HMAC, key derivation, or @@ -6665,11 +6663,10 @@ added: v10.0.0 * `bool` {boolean} `true` to enable FIPS mode, `false` to disable it. -Changes [FIPS mode][]. With OpenSSL 3, this only adds or removes `fips=yes` in -the default property query. It does not install, load, initialize, or validate -a FIPS provider. For a usable FIPS configuration, install the provider and -configure OpenSSL to load it when Node.js starts, as described in [FIPS -mode][]. +Changes [FIPS mode][]. This only adds or removes `fips=yes` in the default +property query. It does not install, load, initialize, or validate a FIPS +provider. For a usable FIPS configuration, install the provider and configure +OpenSSL to load it when Node.js starts, as described in [FIPS mode][]. If no loaded provider supplies a requested cryptographic implementation matching `fips=yes`, the call can still succeed and `crypto.getFips()` can still @@ -6688,8 +6685,7 @@ flags additionally require a configured provider named `fips` to initialize and pass its self-test; Node.js fails to start otherwise. Throws an error if OpenSSL cannot change the state. FIPS mode cannot be -disabled when Node.js was started with `--force-fips`. With OpenSSL 1.1.1, -enabling FIPS mode requires a FIPS-capable OpenSSL build. +disabled when Node.js was started with `--force-fips`. ### `crypto.sign(algorithm, data, key[, callback])` @@ -7156,7 +7152,7 @@ variant: input. Encryption and decryption must use the same variant. The option is available -only with CBC-CTS provider ciphers on OpenSSL 3.0 or later. +only with CBC-CTS provider ciphers and is not available with BoringSSL. Applications which use this mode must adhere to these restrictions: @@ -7192,8 +7188,8 @@ For `sm4-xts`, the `xtsStandard` option to [`crypto.createCipheriv()`][] or [`crypto.createDecipheriv()`][] selects either the default `'GB'` variant from GB/T 17964-2021 or the `'IEEE'` variant from IEEE Std 1619-2007. Encryption and decryption must use the same variant. The option is available only for -`sm4-xts`; it does not apply to AES-XTS ciphers. OpenSSL's default provider -supports `sm4-xts` in OpenSSL 3.2 or later. +`sm4-xts`; it does not apply to AES-XTS ciphers. `sm4-xts` requires OpenSSL 3.2 +or later and availability from the default provider. ### AES key wrap modes @@ -7215,7 +7211,7 @@ restrictions: ### SIV and GCM-SIV modes -`SIV`[^openssl30] and `GCM-SIV`[^openssl32] are supported [AEAD algorithms][] +`SIV`[^noboringssl] and `GCM-SIV`[^openssl32] are supported [AEAD algorithms][] when supported by OpenSSL. Applications which use these modes must adhere to certain restrictions when using the cipher API: @@ -7252,13 +7248,11 @@ provider and only applies when it is deployed according to its security policy. Vendor-provided Node.js or OpenSSL builds can require a different configuration; follow the vendor's documentation for those builds. -With OpenSSL 1.1.1, Node.js must be built against a FIPS-capable OpenSSL library. +FIPS support uses the provider model described in the [OpenSSL FIPS module +guide][]. Using FIPS-approved implementations requires: -With OpenSSL 3, FIPS support uses the provider model described in the -[OpenSSL FIPS module guide][]. Using FIPS-approved implementations requires: - -* A correctly installed OpenSSL 3 FIPS provider. -* An OpenSSL 3 [FIPS module configuration file][]. +* A correctly installed OpenSSL FIPS provider. +* An OpenSSL [FIPS module configuration file][]. * The FIPS provider to be loaded into the OpenSSL library context used by Node.js, normally by activating it in an OpenSSL configuration file when Node.js starts. @@ -7267,7 +7261,7 @@ With OpenSSL 3, FIPS support uses the provider model described in the OpenSSL configuration, [`--enable-fips`][], or [`--force-fips`][], or for subsequent fetches by `crypto.setFips(true)`. -An example OpenSSL 3 configuration file looks like this: +An example OpenSSL configuration file looks like this: ```text nodejs_conf = nodejs_init @@ -7332,8 +7326,8 @@ By default, Node.js reads the `nodejs_conf` section instead of OpenSSL's usual or build Node.js with `./configure --openssl-conf-name=` to change the default section name. -On OpenSSL 3, the configuration above enables the `fips=yes` property query at -startup. The following controls are also available: +The configuration above enables the `fips=yes` property query at startup. The +following controls are also available: * [`--enable-fips`][] and [`--force-fips`][] enable the property query and additionally require the configured provider named `fips` to initialize and @@ -7341,22 +7335,19 @@ startup. The following controls are also available: prevents FIPS mode from being disabled from script code. With `--force-fips=strict`, Node.js also rejects non-approved operations reported through the OpenSSL FIPS indicator callback. -* [`crypto.setFips()`][] changes the FIPS/property-query state. On OpenSSL 3, it - does not install, load, initialize, or validate a provider. Implementations - fetched before the call are not changed. -* [`crypto.getFips()`][] reports the FIPS/property-query state. On OpenSSL 3, a - return value of `1` does not prove that a FIPS provider is loaded or validated. +* [`crypto.setFips()`][] changes the FIPS/property-query state. It does not + install, load, initialize, or validate a provider. Implementations fetched + before the call are not changed. +* [`crypto.getFips()`][] reports the FIPS/property-query state. A return value of + `1` does not prove that a FIPS provider is loaded or validated. * With [`--enable-fips-indicator-events`][], the [`'crypto.fips.indicator'`][] diagnostics channel reports non-approved - operations permitted by an OpenSSL 3.4 or later FIPS provider configured for + operations permitted by an OpenSSL FIPS provider configured for backwards compatibility. -With OpenSSL 1.1.1, these controls use the library's FIPS mode support and -require a FIPS-capable OpenSSL build. - -Only algorithms available under the active FIPS settings can be used. With -OpenSSL 3, if no loaded provider supplies a requested cryptographic -implementation matching `fips=yes`, fetching it fails, typically with +Only algorithms available under the active FIPS settings can be used. If no +loaded provider supplies a requested cryptographic implementation matching +`fips=yes`, fetching it fails, typically with `ERR_OSSL_EVP_UNSUPPORTED`. The same error can occur for algorithms that Node.js supports when FIPS mode is disabled but that are unavailable under the active FIPS settings. @@ -7637,7 +7628,7 @@ See the [list of SSL OP Flags][] for details. -[^openssl30]: Requires OpenSSL >= 3.0 +[^noboringssl]: Not available when Node.js is built against BoringSSL [^openssl32]: Requires OpenSSL >= 3.2 @@ -7684,7 +7675,7 @@ See the [list of SSL OP Flags][] for details. [`--force-fips`]: cli.md#--force-fips [`--openssl-config`]: cli.md#--openssl-configfile [`--openssl-shared-config`]: cli.md#--openssl-shared-config -[`BN_is_prime_ex`]: https://www.openssl.org/docs/man1.1.1/man3/BN_is_prime_ex.html +[`BN_is_prime_ex`]: https://www.openssl.org/docs/man3.0/man3/BN_is_prime_ex.html [`Buffer`]: buffer.md [`DH_generate_key()`]: https://www.openssl.org/docs/man3.0/man3/DH_generate_key.html [`DiffieHellmanGroup`]: #class-diffiehellmangroup diff --git a/doc/api/tls.md b/doc/api/tls.md index 678513846ba..7e010f4c34e 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -182,8 +182,8 @@ On the client connection, a custom `checkServerIdentity` should be passed because the default one will fail in the absence of a certificate. According to the [RFC 4279][], PSK identities up to 128 bytes in length and -PSKs up to 64 bytes in length must be supported. As of OpenSSL 1.1.0 -maximum identity size is 128 bytes, and maximum PSK length is 256 bytes. +PSKs up to 64 bytes in length must be supported. In OpenSSL the maximum +identity size is 128 bytes, and the maximum PSK length is 256 bytes. The current implementation doesn't support asynchronous PSK callbacks due to the limitations of the underlying OpenSSL API. @@ -1238,7 +1238,7 @@ For example, a TLSv1.2 protocol with AES256-SHA cipher: ``` See -[SSL\_CIPHER\_get\_name](https://www.openssl.org/docs/man1.1.1/man3/SSL_CIPHER_get_name.html) +[SSL\_CIPHER\_get\_name](https://www.openssl.org/docs/man3.0/man3/SSL_CIPHER_get_name.html) for more information. ### `tlsSocket.getEphemeralKeyInfo()` @@ -1490,7 +1490,7 @@ added: v12.11.0 the client in the order of decreasing preference. See -[SSL\_get\_shared\_sigalgs](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_shared_sigalgs.html) +[SSL\_get\_shared\_sigalgs](https://www.openssl.org/docs/man3.0/man3/SSL_get_shared_sigalgs.html) for more information. ### `tlsSocket.getTLSTicket()` @@ -2100,7 +2100,7 @@ changes: The list can contain digest algorithms (`SHA256`, `MD5` etc.), public key algorithms (`RSA-PSS`, `ECDSA` etc.), combination of both (e.g 'RSA+SHA384') or TLS v1.3 scheme names (e.g. `rsa_pss_pss_sha512`). - See [OpenSSL man pages](https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set1_sigalgs_list.html) + See [OpenSSL man pages](https://www.openssl.org/docs/man3.0/man3/SSL_CTX_set1_sigalgs_list.html) for more info. * `ciphers` {string} Cipher suite specification, replacing the default. For more information, see [Modifying the default TLS cipher suite][]. Permitted @@ -2607,7 +2607,7 @@ added: v0.11.3 [RFC 5077]: https://tools.ietf.org/html/rfc5077 [RFC 5929]: https://tools.ietf.org/html/rfc5929 [RFC 8879]: https://tools.ietf.org/html/rfc8879 -[SSL_METHODS]: https://www.openssl.org/docs/man1.1.1/man7/ssl.html#Dealing-with-Protocol-Methods +[SSL_METHODS]: https://www.openssl.org/docs/man3.0/man7/ssl.html#Dealing-with-Protocol-Methods [Session Resumption]: #session-resumption [Stream]: stream.md#stream [TLS recommendations]: https://wiki.mozilla.org/Security/Server_Side_TLS @@ -2625,8 +2625,8 @@ added: v0.11.3 [`Duplex`]: stream.md#class-streamduplex [`NODE_EXTRA_CA_CERTS`]: cli.md#node_extra_ca_certsfile [`NODE_OPTIONS`]: cli.md#node_optionsoptions -[`SSL_export_keying_material`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_export_keying_material.html -[`SSL_get_version`]: https://www.openssl.org/docs/man1.1.1/man3/SSL_get_version.html +[`SSL_export_keying_material`]: https://www.openssl.org/docs/man3.0/man3/SSL_export_keying_material.html +[`SSL_get_version`]: https://www.openssl.org/docs/man3.0/man3/SSL_get_version.html [`crypto.getCurves()`]: crypto.md#cryptogetcurves [`import()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import [`net.Server.address()`]: net.md#serveraddress @@ -2661,6 +2661,6 @@ added: v0.11.3 [`x509.checkHost()`]: crypto.md#x509checkhostname-options [asn1.js]: https://www.npmjs.com/package/asn1.js [certificate object]: #certificate-object -[cipher list format]: https://www.openssl.org/docs/man1.1.1/man1/ciphers.html#CIPHER-LIST-FORMAT +[cipher list format]: https://www.openssl.org/docs/man3.0/man1/ciphers.html#CIPHER-LIST-FORMAT [forward secrecy]: https://en.wikipedia.org/wiki/Perfect_forward_secrecy [perfect forward secrecy]: #perfect-forward-secrecy diff --git a/doc/api/webcrypto.md b/doc/api/webcrypto.md index 025ed3b0ee2..98df2850931 100644 --- a/doc/api/webcrypto.md +++ b/doc/api/webcrypto.md @@ -124,15 +124,15 @@ WICG proposal: Algorithms: -* `'AES-OCB'`[^openssl30] +* `'AES-OCB'`[^noboringssl] * `'Argon2d'`[^openssl32] * `'Argon2i'`[^openssl32] * `'Argon2id'`[^openssl32] * `'ChaCha20-Poly1305'` * `'cSHAKE128'` * `'cSHAKE256'` -* `'KMAC128'`[^openssl30] -* `'KMAC256'`[^openssl30] +* `'KMAC128'`[^noboringssl] +* `'KMAC256'`[^noboringssl] * `'KT128'` * `'KT256'` * `'ML-DSA-44'`[^openssl35] @@ -2776,7 +2776,7 @@ added: [^modern-algos]: See [Modern Algorithms in the Web Cryptography API][] -[^openssl30]: Requires OpenSSL >= 3.0 +[^noboringssl]: Not available when Node.js is built against BoringSSL [^openssl32]: Requires OpenSSL >= 3.2 diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json index 06c3942d867..0d2cb83b517 100644 --- a/doc/node-config-schema.json +++ b/doc/node-config-schema.json @@ -547,7 +547,7 @@ }, "openssl-legacy-provider": { "type": "boolean", - "description": "enable OpenSSL 3.0 legacy provider" + "description": "enable OpenSSL's legacy provider" }, "openssl-shared-config": { "type": "boolean", diff --git a/doc/node.1 b/doc/node.1 index 0c0fa769a48..96582955181 100644 --- a/doc/node.1 +++ b/doc/node.1 @@ -745,9 +745,8 @@ The default is \fBverbatim\fR and \fBdns.setDefaultResultOrder()\fR have higher priority than \fB--dns-result-order\fR. . .It Fl -enable-fips -Enable FIPS mode at startup. With OpenSSL 3, a configured provider named -\fBfips\fR must be available and initialize successfully. With OpenSSL 1.1.1, -Node.js must be built against a FIPS-capable OpenSSL. +Enable FIPS mode at startup. A configured provider named \fBfips\fR must be +available and initialize successfully. . .It Fl -enable-fips-indicator-events Publish OpenSSL FIPS indicator results to the @@ -1286,12 +1285,11 @@ usually only useful for developers debugging Node.js itself. . .It Fl -openssl-config Ns = Ns Ar file Load an OpenSSL configuration file on startup. The file can activate an -OpenSSL 3 FIPS provider or configure a FIPS-capable OpenSSL 1.1.1 build. See -FIPS mode. +OpenSSL FIPS provider. See FIPS mode. This option takes precedence over the \fBOPENSSL_CONF\fR environment variable. . .It Fl -openssl-legacy-provider -Enable OpenSSL 3.0 legacy provider. For more information please see +Enable OpenSSL's legacy provider. For more information please see OSSL_PROVIDER-legacy. . .It Fl -openssl-shared-config diff --git a/src/crypto/README.md b/src/crypto/README.md index 63f14030697..3d561f712e0 100644 --- a/src/crypto/README.md +++ b/src/crypto/README.md @@ -158,10 +158,9 @@ callers can retain descriptor pointers across asynchronous jobs. For example, `ML-DSA-44`. For an existing key, use `key.isA(KeyAlgorithm::RSA_PSS)` or another descriptor. -On OpenSSL 3 and later this uses `EVP_PKEY_is_a()` to recognize provider aliases. +On OpenSSL this uses `EVP_PKEY_is_a()` to recognize provider aliases. Numeric key IDs are unsuitable for provider-only keys: OpenSSL can return `-1` -for their ID. Numeric adapters for BoringSSL and legacy OpenSSL stay private to -ncrypto. +for their ID. Numeric adapters for BoringSSL stay private to ncrypto. When a function needs algorithm metadata, use `key.getAlgorithm()`. It returns a pointer to a static descriptor, or `nullptr` for an empty key or an unrecognized