From 526c6f67f7dcb7d301503ad670bcedfe7596124c Mon Sep 17 00:00:00 2001 From: Adina Shanholtz Date: Tue, 15 Aug 2017 16:16:14 -0400 Subject: [PATCH 1/4] Updated crypto docs to include options argument Fixes: https://github.com/nodejs/node/issues/14804 --- doc/api/crypto.md | 40 ++++++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 07245e8cdc1075..a665d8f6007b59 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1170,15 +1170,16 @@ added: v6.0.0 Property for checking and controlling whether a FIPS compliant crypto provider is currently in use. Setting to true requires a FIPS build of Node.js. -### crypto.createCipher(algorithm, password) +### crypto.createCipher(algorithm, password, options) - `algorithm` {string} - `password` {string | Buffer | TypedArray | DataView} +- `options` {string} Creates and returns a `Cipher` object that uses the given `algorithm` and -`password`. +`password`. Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On recent OpenSSL releases, `openssl list-cipher-algorithms` will display the @@ -1200,13 +1201,14 @@ In line with OpenSSL's recommendation to use pbkdf2 instead of their own using [`crypto.pbkdf2()`][] and to use [`crypto.createCipheriv()`][] to create the `Cipher` object. -### crypto.createCipheriv(algorithm, key, iv) +### crypto.createCipheriv(algorithm, key, iv, options) - `algorithm` {string} - `key` {string | Buffer | TypedArray | DataView} - `iv` {string | Buffer | TypedArray | DataView} +- `options` {string} Creates and returns a `Cipher` object, with the given `algorithm`, `key` and -initialization vector (`iv`). +initialization vector (`iv`). Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On recent OpenSSL releases, `openssl list-cipher-algorithms` will display the @@ -1234,15 +1236,16 @@ value. Returns a `tls.SecureContext`, as-if [`tls.createSecureContext()`][] had been called. -### crypto.createDecipher(algorithm, password) +### crypto.createDecipher(algorithm, password, options) - `algorithm` {string} - `password` {string | Buffer | TypedArray | DataView} +- `options` {string} Creates and returns a `Decipher` object that uses the given `algorithm` and -`password` (key). +`password` (key). Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). The implementation of `crypto.createDecipher()` derives keys using the OpenSSL function [`EVP_BytesToKey`][] with the digest algorithm set to MD5, one @@ -1256,16 +1259,17 @@ In line with OpenSSL's recommendation to use pbkdf2 instead of their own using [`crypto.pbkdf2()`][] and to use [`crypto.createDecipheriv()`][] to create the `Decipher` object. -### crypto.createDecipheriv(algorithm, key, iv) +### crypto.createDecipheriv(algorithm, key, iv, options) - `algorithm` {string} - `key` {string | Buffer | TypedArray | DataView} - `iv` {string | Buffer | TypedArray | DataView} +- `options` {string} Creates and returns a `Decipher` object that uses the given `algorithm`, `key` -and initialization vector (`iv`). +and initialization vector (`iv`). Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On recent OpenSSL releases, `openssl list-cipher-algorithms` will display the @@ -1333,14 +1337,15 @@ predefined curve specified by the `curveName` string. Use OpenSSL releases, `openssl ecparam -list_curves` will also display the name and description of each available elliptic curve. -### crypto.createHash(algorithm) +### crypto.createHash(algorithm, options) - `algorithm` {string} +- `options` {string} Creates and returns a `Hash` object that can be used to generate hash digests -using the given `algorithm`. +using the given `algorithm`. Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). The `algorithm` is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc. @@ -1367,14 +1372,15 @@ input.on('readable', () => { }); ``` -### crypto.createHmac(algorithm, key) +### crypto.createHmac(algorithm, key, options) - `algorithm` {string} - `key` {string | Buffer | TypedArray | DataView} +- `options` {string} -Creates and returns an `Hmac` object that uses the given `algorithm` and `key`. +Creates and returns an `Hmac` object that uses the given `algorithm` and `key`. Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). The `algorithm` is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc. @@ -1403,25 +1409,27 @@ input.on('readable', () => { }); ``` -### crypto.createSign(algorithm) +### crypto.createSign(algorithm, options) - `algorithm` {string} +- `options` {string} Creates and returns a `Sign` object that uses the given `algorithm`. Use [`crypto.getHashes()`][] to obtain an array of names of the available -signing algorithms. +signing algorithms. Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). -### crypto.createVerify(algorithm) +### crypto.createVerify(algorithm, options) - `algorithm` {string} +- `options` {string} Creates and returns a `Verify` object that uses the given algorithm. Use [`crypto.getHashes()`][] to obtain an array of names of the available -signing algorithms. +signing algorithms. Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). ### crypto.getCiphers() - `algorithm` {string} - `password` {string | Buffer | TypedArray | DataView} -- `options` {string} +- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] Creates and returns a `Cipher` object that uses the given `algorithm` and -`password`. Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). +`password`. Optional `options` argument controls stream behavior. The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On recent OpenSSL releases, `openssl list-cipher-algorithms` will display the @@ -1201,14 +1201,14 @@ In line with OpenSSL's recommendation to use pbkdf2 instead of their own using [`crypto.pbkdf2()`][] and to use [`crypto.createCipheriv()`][] to create the `Cipher` object. -### crypto.createCipheriv(algorithm, key, iv, options) +### crypto.createCipheriv(algorithm, key, iv[, options]) - `algorithm` {string} - `key` {string | Buffer | TypedArray | DataView} - `iv` {string | Buffer | TypedArray | DataView} -- `options` {string} +- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] Creates and returns a `Cipher` object, with the given `algorithm`, `key` and -initialization vector (`iv`). Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). +initialization vector (`iv`). Optional `options` argument controls stream behavior. The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On recent OpenSSL releases, `openssl list-cipher-algorithms` will display the @@ -1236,16 +1236,16 @@ value. Returns a `tls.SecureContext`, as-if [`tls.createSecureContext()`][] had been called. -### crypto.createDecipher(algorithm, password, options) +### crypto.createDecipher(algorithm, password[, options]) - `algorithm` {string} - `password` {string | Buffer | TypedArray | DataView} -- `options` {string} +- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] Creates and returns a `Decipher` object that uses the given `algorithm` and -`password` (key). Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). +`password` (key). Optional `options` argument controls stream behavior. The implementation of `crypto.createDecipher()` derives keys using the OpenSSL function [`EVP_BytesToKey`][] with the digest algorithm set to MD5, one @@ -1259,17 +1259,18 @@ In line with OpenSSL's recommendation to use pbkdf2 instead of their own using [`crypto.pbkdf2()`][] and to use [`crypto.createDecipheriv()`][] to create the `Decipher` object. -### crypto.createDecipheriv(algorithm, key, iv, options) +### crypto.createDecipheriv(algorithm, key, iv[, options]) - `algorithm` {string} - `key` {string | Buffer | TypedArray | DataView} - `iv` {string | Buffer | TypedArray | DataView} -- `options` {string} +- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] Creates and returns a `Decipher` object that uses the given `algorithm`, `key` -and initialization vector (`iv`). Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). +and initialization vector (`iv`). Optional `options` argument controls stream +behavior. The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On recent OpenSSL releases, `openssl list-cipher-algorithms` will display the @@ -1337,15 +1338,16 @@ predefined curve specified by the `curveName` string. Use OpenSSL releases, `openssl ecparam -list_curves` will also display the name and description of each available elliptic curve. -### crypto.createHash(algorithm, options) +### crypto.createHash(algorithm[, options]) - `algorithm` {string} -- `options` {string} +- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] Creates and returns a `Hash` object that can be used to generate hash digests -using the given `algorithm`. Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). +using the given `algorithm`. Optional `options` argument controls stream +behavior. The `algorithm` is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc. @@ -1372,15 +1374,16 @@ input.on('readable', () => { }); ``` -### crypto.createHmac(algorithm, key, options) +### crypto.createHmac(algorithm, key[, options]) - `algorithm` {string} - `key` {string | Buffer | TypedArray | DataView} -- `options` {string} +- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] -Creates and returns an `Hmac` object that uses the given `algorithm` and `key`. Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). +Creates and returns an `Hmac` object that uses the given `algorithm` and `key`. +Optional `options` argument controls stream behavior. The `algorithm` is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are `'sha256'`, `'sha512'`, etc. @@ -1409,27 +1412,27 @@ input.on('readable', () => { }); ``` -### crypto.createSign(algorithm, options) +### crypto.createSign(algorithm[, options]) - `algorithm` {string} -- `options` {string} +- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] Creates and returns a `Sign` object that uses the given `algorithm`. Use [`crypto.getHashes()`][] to obtain an array of names of the available -signing algorithms. Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). +signing algorithms. Optional `options` argument controls stream behavior. -### crypto.createVerify(algorithm, options) +### crypto.createVerify(algorithm[, options]) - `algorithm` {string} -- `options` {string} +- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] Creates and returns a `Verify` object that uses the given algorithm. Use [`crypto.getHashes()`][] to obtain an array of names of the available -signing algorithms. Optional `options` argument controls stream behavior via [OpenSSL Options](#openssl-options). +signing algorithms. Optional `options` argument controls stream behavior. ### crypto.getCiphers() - `algorithm` {string} - `password` {string | Buffer | TypedArray | DataView} -- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] +- `options` {Object} [`stream.transform` options][] Creates and returns a `Cipher` object that uses the given `algorithm` and `password`. Optional `options` argument controls stream behavior. @@ -1205,7 +1205,7 @@ to create the `Cipher` object. - `algorithm` {string} - `key` {string | Buffer | TypedArray | DataView} - `iv` {string | Buffer | TypedArray | DataView} -- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] +- `options` {Object} [`stream.transform` options][] Creates and returns a `Cipher` object, with the given `algorithm`, `key` and initialization vector (`iv`). Optional `options` argument controls stream behavior. @@ -1242,7 +1242,7 @@ added: v0.1.94 --> - `algorithm` {string} - `password` {string | Buffer | TypedArray | DataView} -- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] +- `options` {Object} [`stream.transform` options][] Creates and returns a `Decipher` object that uses the given `algorithm` and `password` (key). Optional `options` argument controls stream behavior. @@ -1266,7 +1266,7 @@ added: v0.1.94 - `algorithm` {string} - `key` {string | Buffer | TypedArray | DataView} - `iv` {string | Buffer | TypedArray | DataView} -- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] +- `options` {Object} [`stream.transform` options][] Creates and returns a `Decipher` object that uses the given `algorithm`, `key` and initialization vector (`iv`). Optional `options` argument controls stream @@ -1343,7 +1343,7 @@ and description of each available elliptic curve. added: v0.1.92 --> - `algorithm` {string} -- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] +- `options` {Object} [`stream.transform` options][] Creates and returns a `Hash` object that can be used to generate hash digests using the given `algorithm`. Optional `options` argument controls stream @@ -1380,7 +1380,7 @@ added: v0.1.94 --> - `algorithm` {string} - `key` {string | Buffer | TypedArray | DataView} -- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] +- `options` {Object} [`stream.transform` options][] Creates and returns an `Hmac` object that uses the given `algorithm` and `key`. Optional `options` argument controls stream behavior. @@ -1417,22 +1417,24 @@ input.on('readable', () => { added: v0.1.92 --> - `algorithm` {string} -- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] +- `options` {Object} [`stream.Writable` options][] Creates and returns a `Sign` object that uses the given `algorithm`. Use [`crypto.getHashes()`][] to obtain an array of names of the available -signing algorithms. Optional `options` argument controls stream behavior. +signing algorithms. Optional `options` argument controls the +`stream.Writable` behavior. ### crypto.createVerify(algorithm[, options]) - `algorithm` {string} -- `options` {object} combined [OpenSSL options][] and [`stream.transform` options][] +- `options` {Object} [`stream.Writable` options][] Creates and returns a `Verify` object that uses the given algorithm. Use [`crypto.getHashes()`][] to obtain an array of names of the available -signing algorithms. Optional `options` argument controls stream behavior. +signing algorithms. Optional `options` argument controls the +`stream.Writable` behavior. ### crypto.getCiphers()