crypto: docs-only deprecate crypto.fips, replace

Docs-only deprecate the getter/setter crypto.fips and replace
with crypto.setFips() and crypto.getFips()

This is specifically in preparation for ESM module support

PR-URL: nodejs#18335
Refs: nodejs#18131
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

Author: jasnell

doc/api/crypto.md

@@ -1288,11 +1288,15 @@ become deprecated in a future Node.js release.
 ### crypto.fips
 <!-- YAML
 added: v6.0.0
+deprecated: REPLACEME
 -->
 
 Property for checking and controlling whether a FIPS compliant crypto provider
 is currently in use. Setting to true requires a FIPS build of Node.js.
 
+This property is deprecated. Please use `crypto.setFips()` and
+`crypto.getFips()` instead.
+
 ### crypto.createCipher(algorithm, password[, options])
 <!-- YAML
 added: v0.1.94
@@ -1665,6 +1669,14 @@ const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
 console.log(aliceSecret === bobSecret);
 ```
 
+### crypto.getFips()
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if and only if a FIPS compliant crypto provider is
+currently in use.
+
 ### crypto.getHashes()
 <!-- YAML
 added: v0.9.3
@@ -2086,6 +2098,15 @@ is a bit field taking one of or a mix of the following flags (defined in
 * `crypto.constants.ENGINE_METHOD_ALL`
 * `crypto.constants.ENGINE_METHOD_NONE`
 
+### crypto.setFips(bool)
+<!-- YAML
+added: REPLACEME
+-->
+* `bool` {boolean} `true` to enable FIPS mode.
+
+Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build.
+Throws an error if FIPS mode is not available.
+
 ### crypto.timingSafeEqual(a, b)
 <!-- YAML
 added: v6.6.0

doc/api/deprecations.md

@@ -82,15 +82,15 @@ is strongly recommended:
 
 * [`Buffer.alloc(size[, fill[, encoding]])`][alloc] - Create a `Buffer` with
   *initialized* memory.
-* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with 
+* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with
   *uninitialized* memory.
 * [`Buffer.allocUnsafeSlow(size)`][] - Create a `Buffer` with *uninitialized*
    memory.
 * [`Buffer.from(array)`][] - Create a `Buffer` with a copy of `array`
-* [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] - 
+* [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] -
   Create a `Buffer` that wraps the given `arrayBuffer`.
 * [`Buffer.from(buffer)`][] - Create a `Buffer` that copies `buffer`.
-* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer` 
+* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer`
   that copies `string`.
 
 <a id="DEP0006"></a>
@@ -784,6 +784,14 @@ Importing assert directly is not recommended as the exposed functions will use
 loose equality checks. Use `require('assert').strict` instead. The API is the
 same as the legacy assert but it will always use strict equality checks.
 
+<a id="DEP0093"></a>
+### DEP0093: crypto.fips is deprecated and replaced.
+
+Type: Documentation-only
+
+The [`crypto.fips`][] property is deprecated. Please use `crypto.setFips()`
+and `crypto.getFips()` instead.
+
 <a id="DEP0098"></a>
 ### DEP0098: AsyncHooks Embedder AsyncResource.emit{Before,After} APIs
 
@@ -820,6 +828,7 @@ expose values under these names.
 [`console.error()`]: console.html#console_console_error_data_args
 [`console.log()`]: console.html#console_console_log_data_args
 [`crypto.createCredentials()`]: crypto.html#crypto_crypto_createcredentials_details
+[`crypto.fips`]: crypto.html#crypto_crypto_fips
 [`crypto.pbkdf2()`]: crypto.html#crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
 [`domain`]: domain.html
 [`ecdh.setPublicKey()`]: crypto.html#crypto_ecdh_setpublickey_publickey_encoding

lib/crypto.js

@@ -162,6 +162,10 @@ module.exports = exports = {
   rng: randomBytes,
   setEngine,
   timingSafeEqual,
+  getFips: !fipsMode ? getFipsDisabled :
+    fipsForced ? getFipsForced : getFipsCrypto,
+  setFips: !fipsMode ? setFipsDisabled :
+    fipsForced ? setFipsForced : setFipsCrypto,
 
   // Classes
   Certificate,
@@ -196,6 +200,7 @@ function getFipsForced() {
 }
 
 Object.defineProperties(exports, {
+  // crypto.fips is deprecated. DEP00XX. Use crypto.getFips()/crypto.setFips()
   fips: {
     get: !fipsMode ? getFipsDisabled :
       fipsForced ? getFipsForced : getFipsCrypto,

test/parallel/test-crypto-fips.js

@@ -67,23 +67,23 @@ testHelper(
   'stdout',
   [],
   FIPS_DISABLED,
-  'require("crypto").fips',
+  'require("crypto").getFips()',
   Object.assign({}, process.env, { 'OPENSSL_CONF': '' }));
 
 // --enable-fips should turn FIPS mode on
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   ['--enable-fips'],
   compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
-  'require("crypto").fips',
+  'require("crypto").getFips()',
   process.env);
 
 //--force-fips should turn FIPS mode on
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   ['--force-fips'],
   compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
-  'require("crypto").fips',
+  'require("crypto").getFips()',
   process.env);
 
 // If Node was configured using --shared-openssl fips support might be
@@ -104,140 +104,140 @@ if (!sharedOpenSSL()) {
     'stdout',
     [`--openssl-config=${CNF_FIPS_ON}`],
     compiledWithFips() ? FIPS_ENABLED : FIPS_DISABLED,
-    'require("crypto").fips',
+    'require("crypto").getFips()',
     process.env);
 
   // OPENSSL_CONF should be able to turn on FIPS mode
   testHelper(
     'stdout',
     [],
     compiledWithFips() ? FIPS_ENABLED : FIPS_DISABLED,
-    'require("crypto").fips',
+    'require("crypto").getFips()',
     Object.assign({}, process.env, { 'OPENSSL_CONF': CNF_FIPS_ON }));
 
   // --openssl-config option should override OPENSSL_CONF
   testHelper(
     'stdout',
     [`--openssl-config=${CNF_FIPS_ON}`],
     compiledWithFips() ? FIPS_ENABLED : FIPS_DISABLED,
-    'require("crypto").fips',
+    'require("crypto").getFips()',
     Object.assign({}, process.env, { 'OPENSSL_CONF': CNF_FIPS_OFF }));
 }
 
 testHelper(
   'stdout',
   [`--openssl-config=${CNF_FIPS_OFF}`],
   FIPS_DISABLED,
-  'require("crypto").fips',
+  'require("crypto").getFips()',
   Object.assign({}, process.env, { 'OPENSSL_CONF': CNF_FIPS_ON }));
 
 // --enable-fips should take precedence over OpenSSL config file
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   ['--enable-fips', `--openssl-config=${CNF_FIPS_OFF}`],
   compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
-  'require("crypto").fips',
+  'require("crypto").getFips()',
   process.env);
 
 // OPENSSL_CONF should _not_ make a difference to --enable-fips
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   ['--enable-fips'],
   compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
-  'require("crypto").fips',
+  'require("crypto").getFips()',
   Object.assign({}, process.env, { 'OPENSSL_CONF': CNF_FIPS_OFF }));
 
 // --force-fips should take precedence over OpenSSL config file
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   ['--force-fips', `--openssl-config=${CNF_FIPS_OFF}`],
   compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
-  'require("crypto").fips',
+  'require("crypto").getFips()',
   process.env);
 
 // Using OPENSSL_CONF should not make a difference to --force-fips
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   ['--force-fips'],
   compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
-  'require("crypto").fips',
+  'require("crypto").getFips()',
   Object.assign({}, process.env, { 'OPENSSL_CONF': CNF_FIPS_OFF }));
 
 // setFipsCrypto should be able to turn FIPS mode on
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   [],
   compiledWithFips() ? FIPS_ENABLED : FIPS_ERROR_STRING,
-  '(require("crypto").fips = true,' +
-  'require("crypto").fips)',
+  '(require("crypto").setFips(true),' +
+  'require("crypto").getFips())',
   process.env);
 
 // setFipsCrypto should be able to turn FIPS mode on and off
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   [],
   compiledWithFips() ? FIPS_DISABLED : FIPS_ERROR_STRING,
-  '(require("crypto").fips = true,' +
-  'require("crypto").fips = false,' +
-  'require("crypto").fips)',
+  '(require("crypto").setFips(true),' +
+  'require("crypto").setFips(false),' +
+  'require("crypto").getFips())',
   process.env);
 
 // setFipsCrypto takes precedence over OpenSSL config file, FIPS on
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   [`--openssl-config=${CNF_FIPS_OFF}`],
   compiledWithFips() ? FIPS_ENABLED : FIPS_ERROR_STRING,
-  '(require("crypto").fips = true,' +
-  'require("crypto").fips)',
+  '(require("crypto").setFips(true),' +
+  'require("crypto").getFips())',
   process.env);
 
 // setFipsCrypto takes precedence over OpenSSL config file, FIPS off
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   [`--openssl-config=${CNF_FIPS_ON}`],
   compiledWithFips() ? FIPS_DISABLED : FIPS_ERROR_STRING,
-  '(require("crypto").fips = false,' +
-  'require("crypto").fips)',
+  '(require("crypto").setFips(false),' +
+  'require("crypto").getFips())',
   process.env);
 
 // --enable-fips does not prevent use of setFipsCrypto API
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   ['--enable-fips'],
   compiledWithFips() ? FIPS_DISABLED : OPTION_ERROR_STRING,
-  '(require("crypto").fips = false,' +
-  'require("crypto").fips)',
+  '(require("crypto").setFips(false),' +
+  'require("crypto").getFips())',
   process.env);
 
 // --force-fips prevents use of setFipsCrypto API
 testHelper(
   'stderr',
   ['--force-fips'],
   compiledWithFips() ? FIPS_ERROR_STRING2 : OPTION_ERROR_STRING,
-  'require("crypto").fips = false',
+  'require("crypto").setFips(false)',
   process.env);
 
 // --force-fips makes setFipsCrypto enable a no-op (FIPS stays on)
 testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   ['--force-fips'],
   compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
-  '(require("crypto").fips = true,' +
-  'require("crypto").fips)',
+  '(require("crypto").setFips(true),' +
+  'require("crypto").getFips())',
   process.env);
 
 // --force-fips and --enable-fips order does not matter
 testHelper(
   'stderr',
   ['--force-fips', '--enable-fips'],
   compiledWithFips() ? FIPS_ERROR_STRING2 : OPTION_ERROR_STRING,
-  'require("crypto").fips = false',
+  'require("crypto").setFips(false)',
   process.env);
 
 //--enable-fips and --force-fips order does not matter
 testHelper(
   'stderr',
   ['--enable-fips', '--force-fips'],
   compiledWithFips() ? FIPS_ERROR_STRING2 : OPTION_ERROR_STRING,
-  'require("crypto").fips = false',
+  'require("crypto").setFips(false)',
   process.env);