Skip to content

Commit 6e7992e

Browse files
jasnelljasnell
committed
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 <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Guy Bedford <[email protected]> Reviewed-By: Jon Moss <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>
1 parent a89d215 commit 6e7992e

File tree

4 files changed

+61
-27
lines changed

4 files changed

+61
-27
lines changed

‎doc/api/crypto.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1239,11 +1239,15 @@ This property is deprecated.
12391239
### crypto.fips
12401240
<!-- YAML
12411241
added: v6.0.0
1242+
deprecated: REPLACEME
12421243
-->
12431244

12441245
Property for checking and controlling whether a FIPS compliant crypto provider is
12451246
currently in use. Setting to true requires a FIPS build of Node.js.
12461247

1248+
This property is deprecated. Please use `crypto.setFips()` and
1249+
`crypto.getFips()` instead.
1250+
12471251
### crypto.createCipher(algorithm, password[, options])
12481252
<!-- YAML
12491253
added: v0.1.94
@@ -1576,6 +1580,14 @@ const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex');
15761580
console.log(aliceSecret === bobSecret);
15771581
```
15781582

1583+
### crypto.getFips()
1584+
<!-- YAML
1585+
added: REPLACEME
1586+
-->
1587+
1588+
Returns `true` if and only if a FIPS compliant crypto provider is
1589+
currently in use.
1590+
15791591
### crypto.getHashes()
15801592
<!-- YAML
15811593
added: v0.9.3
@@ -1999,6 +2011,15 @@ is a bit field taking one of or a mix of the following flags (defined in
19992011
* `crypto.constants.ENGINE_METHOD_ALL`
20002012
* `crypto.constants.ENGINE_METHOD_NONE`
20012013

2014+
### crypto.setFips(bool)
2015+
<!-- YAML
2016+
added: REPLACEME
2017+
-->
2018+
* `bool` {boolean} `true` to enable FIPS mode.
2019+
2020+
Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build.
2021+
Throws an error if FIPS mode is not available.
2022+
20022023
### crypto.timingSafeEqual(a, b)
20032024
<!-- YAML
20042025
added: v6.6.0

‎doc/api/deprecations.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -840,6 +840,13 @@ Assigning properties to the top-level `this` as an alternative
840840
to `module.exports` is deprecated. Developers should use `exports`
841841
or `module.exports` instead.
842842
843+
### DEP00XX: crypto.fips is deprecated and replaced.
844+
845+
Type: Documentation-only
846+
847+
The [`crypto.fips`][] property is deprecated. Please use `crypto.setFips()`
848+
and `crypto.getFips()` instead.
849+
843850
[`--pending-deprecation`]: cli.html#cli_pending_deprecation
844851
[`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
845852
[`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
@@ -855,6 +862,7 @@ or `module.exports` instead.
855862
[`console.log()`]: console.html#console_console_log_data_args
856863
[`crypto.createCredentials()`]: crypto.html#crypto_crypto_createcredentials_details
857864
[`crypto.DEFAULT_ENCODING`]: crypto.html#crypto_crypto_default_encoding
865+
[`crypto.fips`]: crypto.html#crypto_crypto_fips
858866
[`crypto.pbkdf2()`]: crypto.html#crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
859867
[`decipher.setAuthTag()`]: crypto.html#crypto_decipher_setauthtag_buffer
860868
[`domain`]: domain.html

‎lib/crypto.js

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,10 @@ module.exports = exports = {
162162
rng: randomBytes,
163163
setEngine,
164164
timingSafeEqual,
165+
getFips: !fipsMode ? getFipsDisabled :
166+
fipsForced ? getFipsForced : getFipsCrypto,
167+
setFips: !fipsMode ? setFipsDisabled :
168+
fipsForced ? setFipsForced : setFipsCrypto,
165169

166170
// Classes
167171
Certificate,
@@ -196,6 +200,7 @@ function getFipsForced() {
196200
}
197201

198202
Object.defineProperties(exports, {
203+
// crypto.fips is deprecated. DEP00XX. Use crypto.getFips()/crypto.setFips()
199204
fips: {
200205
get: !fipsMode ? getFipsDisabled :
201206
fipsForced ? getFipsForced : getFipsCrypto,

‎test/parallel/test-crypto-fips.js

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -67,23 +67,23 @@ testHelper(
6767
'stdout',
6868
[],
6969
FIPS_DISABLED,
70-
'require("crypto").fips',
70+
'require("crypto").getFips()',
7171
Object.assign({}, process.env, { 'OPENSSL_CONF': '' }));
7272

7373
// --enable-fips should turn FIPS mode on
7474
testHelper(
7575
compiledWithFips() ? 'stdout' : 'stderr',
7676
['--enable-fips'],
7777
compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
78-
'require("crypto").fips',
78+
'require("crypto").getFips()',
7979
process.env);
8080

8181
//--force-fips should turn FIPS mode on
8282
testHelper(
8383
compiledWithFips() ? 'stdout' : 'stderr',
8484
['--force-fips'],
8585
compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
86-
'require("crypto").fips',
86+
'require("crypto").getFips()',
8787
process.env);
8888

8989
// If Node was configured using --shared-openssl fips support might be
@@ -104,140 +104,140 @@ if (!sharedOpenSSL()) {
104104
'stdout',
105105
[`--openssl-config=${CNF_FIPS_ON}`],
106106
compiledWithFips() ? FIPS_ENABLED : FIPS_DISABLED,
107-
'require("crypto").fips',
107+
'require("crypto").getFips()',
108108
process.env);
109109

110110
// OPENSSL_CONF should be able to turn on FIPS mode
111111
testHelper(
112112
'stdout',
113113
[],
114114
compiledWithFips() ? FIPS_ENABLED : FIPS_DISABLED,
115-
'require("crypto").fips',
115+
'require("crypto").getFips()',
116116
Object.assign({}, process.env, { 'OPENSSL_CONF': CNF_FIPS_ON }));
117117

118118
// --openssl-config option should override OPENSSL_CONF
119119
testHelper(
120120
'stdout',
121121
[`--openssl-config=${CNF_FIPS_ON}`],
122122
compiledWithFips() ? FIPS_ENABLED : FIPS_DISABLED,
123-
'require("crypto").fips',
123+
'require("crypto").getFips()',
124124
Object.assign({}, process.env, { 'OPENSSL_CONF': CNF_FIPS_OFF }));
125125
}
126126

127127
testHelper(
128128
'stdout',
129129
[`--openssl-config=${CNF_FIPS_OFF}`],
130130
FIPS_DISABLED,
131-
'require("crypto").fips',
131+
'require("crypto").getFips()',
132132
Object.assign({}, process.env, { 'OPENSSL_CONF': CNF_FIPS_ON }));
133133

134134
// --enable-fips should take precedence over OpenSSL config file
135135
testHelper(
136136
compiledWithFips() ? 'stdout' : 'stderr',
137137
['--enable-fips', `--openssl-config=${CNF_FIPS_OFF}`],
138138
compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
139-
'require("crypto").fips',
139+
'require("crypto").getFips()',
140140
process.env);
141141

142142
// OPENSSL_CONF should _not_ make a difference to --enable-fips
143143
testHelper(
144144
compiledWithFips() ? 'stdout' : 'stderr',
145145
['--enable-fips'],
146146
compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
147-
'require("crypto").fips',
147+
'require("crypto").getFips()',
148148
Object.assign({}, process.env, { 'OPENSSL_CONF': CNF_FIPS_OFF }));
149149

150150
// --force-fips should take precedence over OpenSSL config file
151151
testHelper(
152152
compiledWithFips() ? 'stdout' : 'stderr',
153153
['--force-fips', `--openssl-config=${CNF_FIPS_OFF}`],
154154
compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
155-
'require("crypto").fips',
155+
'require("crypto").getFips()',
156156
process.env);
157157

158158
// Using OPENSSL_CONF should not make a difference to --force-fips
159159
testHelper(
160160
compiledWithFips() ? 'stdout' : 'stderr',
161161
['--force-fips'],
162162
compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
163-
'require("crypto").fips',
163+
'require("crypto").getFips()',
164164
Object.assign({}, process.env, { 'OPENSSL_CONF': CNF_FIPS_OFF }));
165165

166166
// setFipsCrypto should be able to turn FIPS mode on
167167
testHelper(
168168
compiledWithFips() ? 'stdout' : 'stderr',
169169
[],
170170
compiledWithFips() ? FIPS_ENABLED : FIPS_ERROR_STRING,
171-
'(require("crypto").fips = true,' +
172-
'require("crypto").fips)',
171+
'(require("crypto").setFips(true),' +
172+
'require("crypto").getFips())',
173173
process.env);
174174

175175
// setFipsCrypto should be able to turn FIPS mode on and off
176176
testHelper(
177177
compiledWithFips() ? 'stdout' : 'stderr',
178178
[],
179179
compiledWithFips() ? FIPS_DISABLED : FIPS_ERROR_STRING,
180-
'(require("crypto").fips = true,' +
181-
'require("crypto").fips = false,' +
182-
'require("crypto").fips)',
180+
'(require("crypto").setFips(true),' +
181+
'require("crypto").setFips(false),' +
182+
'require("crypto").getFips())',
183183
process.env);
184184

185185
// setFipsCrypto takes precedence over OpenSSL config file, FIPS on
186186
testHelper(
187187
compiledWithFips() ? 'stdout' : 'stderr',
188188
[`--openssl-config=${CNF_FIPS_OFF}`],
189189
compiledWithFips() ? FIPS_ENABLED : FIPS_ERROR_STRING,
190-
'(require("crypto").fips = true,' +
191-
'require("crypto").fips)',
190+
'(require("crypto").setFips(true),' +
191+
'require("crypto").getFips())',
192192
process.env);
193193

194194
// setFipsCrypto takes precedence over OpenSSL config file, FIPS off
195195
testHelper(
196196
compiledWithFips() ? 'stdout' : 'stderr',
197197
[`--openssl-config=${CNF_FIPS_ON}`],
198198
compiledWithFips() ? FIPS_DISABLED : FIPS_ERROR_STRING,
199-
'(require("crypto").fips = false,' +
200-
'require("crypto").fips)',
199+
'(require("crypto").setFips(false),' +
200+
'require("crypto").getFips())',
201201
process.env);
202202

203203
// --enable-fips does not prevent use of setFipsCrypto API
204204
testHelper(
205205
compiledWithFips() ? 'stdout' : 'stderr',
206206
['--enable-fips'],
207207
compiledWithFips() ? FIPS_DISABLED : OPTION_ERROR_STRING,
208-
'(require("crypto").fips = false,' +
209-
'require("crypto").fips)',
208+
'(require("crypto").setFips(false),' +
209+
'require("crypto").getFips())',
210210
process.env);
211211

212212
// --force-fips prevents use of setFipsCrypto API
213213
testHelper(
214214
'stderr',
215215
['--force-fips'],
216216
compiledWithFips() ? FIPS_ERROR_STRING2 : OPTION_ERROR_STRING,
217-
'require("crypto").fips = false',
217+
'require("crypto").setFips(false)',
218218
process.env);
219219

220220
// --force-fips makes setFipsCrypto enable a no-op (FIPS stays on)
221221
testHelper(
222222
compiledWithFips() ? 'stdout' : 'stderr',
223223
['--force-fips'],
224224
compiledWithFips() ? FIPS_ENABLED : OPTION_ERROR_STRING,
225-
'(require("crypto").fips = true,' +
226-
'require("crypto").fips)',
225+
'(require("crypto").setFips(true),' +
226+
'require("crypto").getFips())',
227227
process.env);
228228

229229
// --force-fips and --enable-fips order does not matter
230230
testHelper(
231231
'stderr',
232232
['--force-fips', '--enable-fips'],
233233
compiledWithFips() ? FIPS_ERROR_STRING2 : OPTION_ERROR_STRING,
234-
'require("crypto").fips = false',
234+
'require("crypto").setFips(false)',
235235
process.env);
236236

237237
//--enable-fips and --force-fips order does not matter
238238
testHelper(
239239
'stderr',
240240
['--enable-fips', '--force-fips'],
241241
compiledWithFips() ? FIPS_ERROR_STRING2 : OPTION_ERROR_STRING,
242-
'require("crypto").fips = false',
242+
'require("crypto").setFips(false)',
243243
process.env);

0 commit comments

Comments
 (0)