From cf8563ea63fb1fa13080fa75647d1a2a10167d43 Mon Sep 17 00:00:00 2001 From: Mayank Asthana 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);