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: https://github.com/nodejs/node/pull/18335
Refs: https://github.com/nodejs/node/pull/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>

doc/api/crypto.md

@@ -1239,11 +1239,15 @@ This property is deprecated.
 ### 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
@@ -1576,6 +1580,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
@@ -1999,6 +2011,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

@@ -840,6 +840,13 @@ Assigning properties to the top-level `this` as an alternative
 to `module.exports` is deprecated. Developers should use `exports`
 or `module.exports` instead.
 
+### DEP00XX: crypto.fips is deprecated and replaced.
+
+Type: Documentation-only
+
+The [`crypto.fips`][] property is deprecated. Please use `crypto.setFips()`
+and `crypto.getFips()` instead.
+
 [`--pending-deprecation`]: cli.html#cli_pending_deprecation
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
 [`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
@@ -855,6 +862,7 @@ or `module.exports` instead.
 [`console.log()`]: console.html#console_console_log_data_args
 [`crypto.createCredentials()`]: crypto.html#crypto_crypto_createcredentials_details
 [`crypto.DEFAULT_ENCODING`]: crypto.html#crypto_crypto_default_encoding
+[`crypto.fips`]: crypto.html#crypto_crypto_fips
 [`crypto.pbkdf2()`]: crypto.html#crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
 [`decipher.setAuthTag()`]: crypto.html#crypto_decipher_setauthtag_buffer
 [`domain`]: domain.html

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,7 +67,7 @@ testHelper(
   'stdout',
   [],
   FIPS_DISABLED,
-  'require("crypto").fips',
+  'require("crypto").getFips()',
   Object.assign({}, process.env, { 'OPENSSL_CONF': '' }));
 
 // --enable-fips should turn FIPS mode on
@@ -75,7 +75,7 @@ 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
@@ -83,7 +83,7 @@ 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,7 +104,7 @@ 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
@@ -112,7 +112,7 @@ if (!sharedOpenSSL()) {
     '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
@@ -120,7 +120,7 @@ if (!sharedOpenSSL()) {
     '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 }));
 }
 
@@ -128,7 +128,7 @@ 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
@@ -136,7 +136,7 @@ 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
@@ -144,7 +144,7 @@ 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
@@ -152,7 +152,7 @@ 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
@@ -160,7 +160,7 @@ 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
@@ -168,8 +168,8 @@ testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   [],
   compiledWithFips() ? FIPS_ENABLED : FIPS_ERROR_STRING,
-  '(require("crypto").fips = true,' +
+  '(require("crypto").setFips(true),' +
-  'require("crypto").fips)',
+  'require("crypto").getFips())',
   process.env);
 
 // setFipsCrypto should be able to turn FIPS mode on and off
@@ -177,9 +177,9 @@ testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   [],
   compiledWithFips() ? FIPS_DISABLED : FIPS_ERROR_STRING,
-  '(require("crypto").fips = true,' +
+  '(require("crypto").setFips(true),' +
-  'require("crypto").fips = false,' +
+  'require("crypto").setFips(false),' +
-  'require("crypto").fips)',
+  'require("crypto").getFips())',
   process.env);
 
 // setFipsCrypto takes precedence over OpenSSL config file, FIPS on
@@ -187,8 +187,8 @@ testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   [`--openssl-config=${CNF_FIPS_OFF}`],
   compiledWithFips() ? FIPS_ENABLED : FIPS_ERROR_STRING,
-  '(require("crypto").fips = true,' +
+  '(require("crypto").setFips(true),' +
-  'require("crypto").fips)',
+  'require("crypto").getFips())',
   process.env);
 
 // setFipsCrypto takes precedence over OpenSSL config file, FIPS off
@@ -196,8 +196,8 @@ testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   [`--openssl-config=${CNF_FIPS_ON}`],
   compiledWithFips() ? FIPS_DISABLED : FIPS_ERROR_STRING,
-  '(require("crypto").fips = false,' +
+  '(require("crypto").setFips(false),' +
-  'require("crypto").fips)',
+  'require("crypto").getFips())',
   process.env);
 
 // --enable-fips does not prevent use of setFipsCrypto API
@@ -205,8 +205,8 @@ testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   ['--enable-fips'],
   compiledWithFips() ? FIPS_DISABLED : OPTION_ERROR_STRING,
-  '(require("crypto").fips = false,' +
+  '(require("crypto").setFips(false),' +
-  'require("crypto").fips)',
+  'require("crypto").getFips())',
   process.env);
 
 // --force-fips prevents use of setFipsCrypto API
@@ -214,7 +214,7 @@ 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)
@@ -222,8 +222,8 @@ testHelper(
   compiledWithFips() ? 'stdout' : 'stderr',
   ['--force-fips'],
   compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
-  '(require("crypto").fips = true,' +
+  '(require("crypto").setFips(true),' +
-  'require("crypto").fips)',
+  'require("crypto").getFips())',
   process.env);
 
 // --force-fips and --enable-fips order does not matter
@@ -231,7 +231,7 @@ 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
@@ -239,5 +239,5 @@ testHelper(
   'stderr',
   ['--enable-fips', '--force-fips'],
   compiledWithFips() ? FIPS_ERROR_STRING2 : OPTION_ERROR_STRING,
-  'require("crypto").fips = false',
+  'require("crypto").setFips(false)',
   process.env);