diff --git a/benchmark/crypto/cipher-stream.js b/benchmark/crypto/cipher-stream.js index 9fd88f1d864dff..0247f49b5e0df7 100644 --- a/benchmark/crypto/cipher-stream.js +++ b/benchmark/crypto/cipher-stream.js @@ -33,8 +33,11 @@ function main(conf) { // alice_secret and bob_secret should be the same assert(alice_secret === bob_secret); - var alice_cipher = crypto.createCipher(conf.cipher, alice_secret); - var bob_cipher = crypto.createDecipher(conf.cipher, bob_secret); + const key = crypto.generateLegacyKey(conf.cipher, alice_secret); + const iv = crypto.generateLegacyIV(conf.cipher, alice_secret); + + const alice_cipher = crypto.createCipheriv(conf.cipher, key, iv); + const bob_cipher = crypto.createDecipheriv(conf.cipher, key, iv); var message; var encoding; diff --git a/doc/api/crypto.md b/doc/api/crypto.md index c4a1cad106c3d6..cd7f38b3cd3196 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1171,7 +1171,11 @@ currently in use. Setting to true requires a FIPS build of Node.js. ### crypto.createCipher(algorithm, password) + +> Stability: 0 - Deprecated: Use [`crypto.createCipheriv()`][] instead. + - `algorithm` {string} - `password` {string | Buffer | TypedArray | DataView} @@ -1204,16 +1208,64 @@ to create the `Cipher` object. - `iv` {string | Buffer | TypedArray | DataView} Creates and returns a `Cipher` object, with the given `algorithm`, `key` and -initialization vector (`iv`). +initialization vector (`iv`). The initialization vector is optional if the +algorithm does not use one. The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On recent OpenSSL releases, `openssl list-cipher-algorithms` will display the available cipher algorithms. -The `key` is the raw key used by the `algorithm` and `iv` is an -[initialization vector][]. Both arguments must be `'utf8'` encoded strings, +The `key` is the raw key used by the `algorithm` and `iv` is an [initialization +vector][]. When provided, both arguments must be `'utf8'` encoded strings, [Buffers][`Buffer`], `TypedArray`, or `DataView`s. +### crypto.generateLegacyKey(algorithm, key) +- `algorithm` {string} +- `key` {string | Buffer | TypedArray | DataView} + +Generates the symmetric encryption key previously internally generated by +[`crypto.createCipher()`][] and returns it as a [Buffer][`Buffer`]. + +The function used to derive this key is a single round of MD5, and is +**insecure**. Use a proper key derivation function such as [`crypto.pbkdf2()`][] +with strong parameters. This function requires minimal compute time to generate +a key from an input, which is typically unsafe. + +This function's return value can be passed to [`crypto.createCipheriv()`][] as +the `key`. + +The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On recent +OpenSSL releases, `openssl list-cipher-algorithms` will display the available +cipher algorithms. + +The `key` must be a `'utf8'` encoded string, [Buffer][`Buffer`], `TypedArray`, +or `DataView`. + +### crypto.generateLegacyIV(algorithm, iv) +- `algorithm` {string} +- `iv` {string | Buffer | TypedArray | DataView} + +Generates the initialization vector previously internally generated by +[`crypto.createCipher()`][] and returns it as a [Buffer][`Buffer`]. + +The function used to derive this key is a single round of MD5, and is +**insecure**. Use a securely random source of entropy such as +[`crypto.randomBytes()`][] to create the initialization vector. It is almost +always unsafe to deterministically generate the initialization vector, as this +function does. + +This function's return value can be passed to [`crypto.createCipheriv()`][] as +the `iv`. + +The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On +recent OpenSSL releases, `openssl list-cipher-algorithms` will display the +available cipher algorithms. + +This function will throw an error if a cipher without an IV is passed. + +The `iv` must be a `'utf8'` encoded string, [Buffer][`Buffer`], `TypedArray`, +or `DataView`. + ### crypto.createCredentials(details)