From cf8563ea63fb1fa13080fa75647d1a2a10167d43 Mon Sep 17 00:00:00 2001
From: Mayank Asthana <mayankasthana1993@gmail.com>
Date: Mon, 5 Nov 2018 20:55:47 +0530
Subject: [PATCH] doc: update crypto examples to not use deprecated api

Updated Cipher and Decipher examples to not use deprecated
`crypto.createCipher` and `crypto.createDecipher` in examples and
instead use `createCipheriv` and `createDecipheriv`.

Fixes: https://github.com/nodejs/node/issues/24046
---
 doc/api/crypto.md | 77 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 67 insertions(+), 10 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index d12eb6d1360d38..97944d0d176cab 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -185,7 +185,18 @@ Example: Using `Cipher` objects as streams:
 
 ```js
 const crypto = require('crypto');
-const cipher = crypto.createCipher('aes192', 'a password');
+
+const algorithm = 'aes-192-cbc';
+const password = 'Password used to generate key';
+// Key length is dependent on the algorithm. In this case for aes192, it is
+// 24 bytes (192 bits).
+// Use async `crypto.scrypt()` instead.
+const key = crypto.scryptSync(password, 'salt', 24);
+// Use `crypto.randomBytes()` to generate a random iv instead of the static iv
+// shown here.
+const iv = Buffer.alloc(16, 0); // Initialization vector.
+
+const cipher = crypto.createCipheriv(algorithm, key, iv);
 
 let encrypted = '';
 cipher.on('readable', () => {
@@ -195,7 +206,7 @@ cipher.on('readable', () => {
 });
 cipher.on('end', () => {
   console.log(encrypted);
-  // Prints: ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504
+  // Prints: e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa
 });
 
 cipher.write('some clear text data');
@@ -207,7 +218,16 @@ Example: Using `Cipher` and piped streams:
 ```js
 const crypto = require('crypto');
 const fs = require('fs');
-const cipher = crypto.createCipher('aes192', 'a password');
+
+const algorithm = 'aes-192-cbc';
+const password = 'Password used to generate key';
+// Use the async `crypto.scrypt()` instead.
+const key = crypto.scryptSync(password, 'salt', 24);
+// Use `crypto.randomBytes()` to generate a random iv instead of the static iv
+// shown here.
+const iv = Buffer.alloc(16, 0); // Initialization vector.
+
+const cipher = crypto.createCipheriv(algorithm, key, iv);
 
 const input = fs.createReadStream('test.js');
 const output = fs.createWriteStream('test.enc');
@@ -219,12 +239,21 @@ Example: Using the [`cipher.update()`][] and [`cipher.final()`][] methods:
 
 ```js
 const crypto = require('crypto');
-const cipher = crypto.createCipher('aes192', 'a password');
+
+const algorithm = 'aes-192-cbc';
+const password = 'Password used to generate key';
+// Use the async `crypto.scrypt()` instead.
+const key = crypto.scryptSync(password, 'salt', 24);
+// Use `crypto.randomBytes` to generate a random iv instead of the static iv
+// shown here.
+const iv = Buffer.alloc(16, 0); // Initialization vector.
+
+const cipher = crypto.createCipheriv(algorithm, key, iv);
 
 let encrypted = cipher.update('some clear text data', 'utf8', 'hex');
 encrypted += cipher.final('hex');
 console.log(encrypted);
-// Prints: ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504
+// Prints: e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa
 ```
 
 ### cipher.final([outputEncoding])
@@ -340,7 +369,17 @@ Example: Using `Decipher` objects as streams:
 
 ```js
 const crypto = require('crypto');
-const decipher = crypto.createDecipher('aes192', 'a password');
+
+const algorithm = 'aes-192-cbc';
+const password = 'Password used to generate key';
+// Key length is dependent on the algorithm. In this case for aes192, it is
+// 24 bytes (192 bits).
+// Use the async `crypto.scrypt()` instead.
+const key = crypto.scryptSync(password, 'salt', 24);
+// The IV is usually passed along with the ciphertext.
+const iv = Buffer.alloc(16, 0); // Initialization vector.
+
+const decipher = crypto.createDecipheriv(algorithm, key, iv);
 
 let decrypted = '';
 decipher.on('readable', () => {
@@ -353,8 +392,9 @@ decipher.on('end', () => {
   // Prints: some clear text data
 });
 
+// Encrypted with same algorithm, key and iv.
 const encrypted =
-    'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
+  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
 decipher.write(encrypted, 'hex');
 decipher.end();
 ```
@@ -364,7 +404,15 @@ Example: Using `Decipher` and piped streams:
 ```js
 const crypto = require('crypto');
 const fs = require('fs');
-const decipher = crypto.createDecipher('aes192', 'a password');
+
+const algorithm = 'aes-192-cbc';
+const password = 'Password used to generate key';
+// Use the async `crypto.scrypt()` instead.
+const key = crypto.scryptSync(password, 'salt', 24);
+// The IV is usually passed along with the ciphertext.
+const iv = Buffer.alloc(16, 0); // Initialization vector.
+
+const decipher = crypto.createDecipheriv(algorithm, key, iv);
 
 const input = fs.createReadStream('test.enc');
 const output = fs.createWriteStream('test.js');
@@ -376,10 +424,19 @@ Example: Using the [`decipher.update()`][] and [`decipher.final()`][] methods:
 
 ```js
 const crypto = require('crypto');
-const decipher = crypto.createDecipher('aes192', 'a password');
 
+const algorithm = 'aes-192-cbc';
+const password = 'Password used to generate key';
+// Use the async `crypto.scrypt()` instead.
+const key = crypto.scryptSync(password, 'salt', 24);
+// The IV is usually passed along with the ciphertext.
+const iv = Buffer.alloc(16, 0); // Initialization vector.
+
+const decipher = crypto.createDecipheriv(algorithm, key, iv);
+
+// Encrypted using same algorithm, key and iv.
 const encrypted =
-    'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
+  'e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa';
 let decrypted = decipher.update(encrypted, 'hex', 'utf8');
 decrypted += decipher.final('utf8');
 console.log(decrypted);