From dda58d3851d8d9f6e6ea6fee9dd47739e2de42fc Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Tue, 23 Jan 2018 15:58:14 -0800
Subject: [PATCH] crypto: runtime deprecate DEFAULT_ENCODING
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Runtime deprecate the crypto.DEFAULT_ENCODING property.

This is specifically in preparation for eventual ESM support
Refs: https://github.com/nodejs/node/pull/18131

PR-URL: https://github.com/nodejs/node/pull/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>
---
 doc/api/crypto.md                          | 16 ++++++++++------
 doc/api/deprecations.md                    |  8 ++++++++
 lib/crypto.js                              |  6 ++++--
 test/parallel/test-crypto-authenticated.js |  2 ++
 4 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index ce91007640a7ed..5e2af21dab19a5 100644
--- 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
index de2f42cd0e63fd..87199e4a306da1 100644
--- 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
index d7c59f553edd2a..5983f1db4f54d2 100644
--- 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
index 384044210d5b85..c016b3500dec81 100644
--- 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