Permalink
Browse files

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: #18335
Refs: #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>
  • Loading branch information...
jasnell committed Jan 24, 2018
1 parent a89d215 commit 6e7992e8b89b55253e43181b4910e6cdbd01318f
Showing with 61 additions and 27 deletions.
  1. +21 −0 doc/api/crypto.md
  2. +8 −0 doc/api/deprecations.md
  3. +5 −0 lib/crypto.js
  4. +27 −27 test/parallel/test-crypto-fips.js
@@ -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
@@ -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
@@ -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,
@@ -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);

0 comments on commit 6e7992e

Please sign in to comment.