crypto: runtime deprecate DEFAULT_ENCODING

Runtime deprecate the crypto.DEFAULT_ENCODING property. This is specifically in preparation for eventual ESM support Refs: #18131 PR-URL: #18333 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Minwoo Jung <minwoo@nodesource.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de>
nodejs · Jan 23, 2018 · 6035beea93e16f6d923201a33a541f6d724f00d6 · 6035bee
1 parent fd3a0cf
commit 6035beea93e16f6d923201a33a541f6d724f00d6
Unified Split

Showing with 24 additions and 8 deletions.

+10 −6 doc/api/crypto.md

+8 −0 doc/api/deprecations.md

+4 −2 lib/crypto.js

+2 −0 test/parallel/test-crypto-authenticated.js
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
@@ -1222,6 +1222,7 @@ related operations. The specific constants currently defined are described in
 ### crypto.DEFAULT_ENCODING
 <!-- YAML
 added: v0.9.3
+deprecated: REPLACEME
 -->

 The default encoding to use for functions that can take either strings
@@ -1231,8 +1232,9 @@ default to [`Buffer`][] objects.
 The `crypto.DEFAULT_ENCODING` mechanism is provided for backwards compatibility
 with legacy programs that expect `'latin1'` to be the default encoding.

-New applications should expect the default to be `'buffer'`. This property may
-become deprecated in a future Node.js release.
+New applications should expect the default to be `'buffer'`.
+
+This property is deprecated.

 ### crypto.fips
 <!-- YAML
@@ -1643,8 +1645,9 @@ crypto.pbkdf2('secret', 'salt', 100000, 64, 'sha512', (err, derivedKey) => {
 });
 ```

-The `crypto.DEFAULT_ENCODING` may be used to change the way the `derivedKey`
-is passed to the callback:
+The `crypto.DEFAULT_ENCODING` property can be used to change the way the
+`derivedKey` is passed to the callback. This property, however, has been
+deprecated and use should be avoided.

 ```js
 const crypto = require('crypto');
@@ -1705,8 +1708,9 @@ const key = crypto.pbkdf2Sync('secret', 'salt', 100000, 64, 'sha512');
 console.log(key.toString('hex'));  // '3745e48...08d59ae'
 ```

-The `crypto.DEFAULT_ENCODING` may be used to change the way the `derivedKey`
-is returned:
+The `crypto.DEFAULT_ENCODING` property may be used to change the way the
+`derivedKey` is returned.  This property, however, has been deprecated and use
+should be avoided.

 ```js
 const crypto = require('crypto');
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -824,6 +824,13 @@ a future version at which point only authentication tag lengths of 128, 120,
 is not included in this list will be considered invalid in compliance with
 [NIST SP 800-38D][].

+<a id="DEP00XX"></a>
+### DEP00XX: crypto.DEFAULT_ENCODING
+
+Type: Runtime
+
+The [`crypto.DEFAULT_ENCODING`][] property is deprecated.
+
 [`--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
@@ -838,6 +845,7 @@ is not included in this list will be considered invalid in compliance with
 [`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.DEFAULT_ENCODING`]: crypto.html#crypto_crypto_default_encoding
 [`crypto.pbkdf2()`]: crypto.html#crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
 [`decipher.setAuthTag()`]: crypto.html#crypto_decipher_setauthtag_buffer
 [`domain`]: domain.html
diff --git a/lib/crypto.js b/lib/crypto.js
@@ -205,8 +205,10 @@ Object.defineProperties(exports, {
  DEFAULT_ENCODING: {
    enumerable: true,
    configurable: true,
-    get: getDefaultEncoding,
-    set: setDefaultEncoding
+    get: deprecate(getDefaultEncoding,
+                   'crypto.DEFAULT_ENCODING is deprecated.', 'DEP00XX'),
+    set: deprecate(setDefaultEncoding,
+                   'crypto.DEFAULT_ENCODING is deprecated.', 'DEP00XX')
  },
  constants: {
    configurable: false,
diff --git a/test/parallel/test-crypto-authenticated.js b/test/parallel/test-crypto-authenticated.js
@@ -342,6 +342,8 @@ const expectedDeprecationWarnings = [0, 1, 2, 6, 9, 10, 11, 17]
  .map((i) => `Permitting authentication tag lengths of ${i} bytes is ` +
            'deprecated. Valid GCM tag lengths are 4, 8, 12, 13, 14, 15, 16.');

+expectedDeprecationWarnings.push('crypto.DEFAULT_ENCODING is deprecated.');
+
 common.expectWarning({
  Warning: expectedWarnings,
  DeprecationWarning: expectedDeprecationWarnings