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 <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Minwoo Jung <[email protected]>
Reviewed-By: Tobias Nießen <[email protected]>

Author: jasnell

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');

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

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,

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