From 426ca0837a41501e5477cd381ec562349e010a3f Mon Sep 17 00:00:00 2001 From: Sam Roberts Date: Wed, 7 Nov 2018 12:27:47 -0800 Subject: [PATCH] doc: clarify allowed encoding parameter types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This fixes the incorrect enumerations of their possible values, which weren't up to date with the values actually supported. Also renamed two arguments that used "format" when they meant "encoding". PR-URL: https://github.com/nodejs/node/pull/24230 Reviewed-By: Tobias Nießen Reviewed-By: Refael Ackermann Reviewed-By: Vse Mozhet Byt --- doc/api/crypto.md | 185 ++++++++++++++++++++++------------------------ doc/api/errors.md | 2 +- 2 files changed, 91 insertions(+), 96 deletions(-) diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 81706157e62cac..f592f36e241f6c 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -72,7 +72,7 @@ console.log(challenge.toString('utf8')); added: v9.0.0 --> * `spkac` {string | Buffer | TypedArray | DataView} -* `encoding` {string} +* `encoding` {string} The [encoding][] of the `spkac` string. * Returns: {Buffer} The public key component of the `spkac` data structure, which includes a public key and a challenge. @@ -231,9 +231,9 @@ console.log(encrypted); -* `outputEncoding` {string} +* `outputEncoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} Any remaining enciphered contents. - If `outputEncoding` is one of `'latin1'`, `'base64'` or `'hex'`, a string is + If `outputEncoding` is specified, a string is returned. If an `outputEncoding` is not provided, a [`Buffer`][] is returned. Once the `cipher.final()` method has been called, the `Cipher` object can no @@ -299,19 +299,19 @@ changes: description: The default `inputEncoding` changed from `binary` to `utf8`. --> * `data` {string | Buffer | TypedArray | DataView} -* `inputEncoding` {string} -* `outputEncoding` {string} +* `inputEncoding` {string} The [encoding][] of the data. +* `outputEncoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} Updates the cipher with `data`. If the `inputEncoding` argument is given, -its value must be one of `'utf8'`, `'ascii'`, or `'latin1'` and the `data` +the `data` argument is a string using the specified encoding. If the `inputEncoding` argument is not given, `data` must be a [`Buffer`][], `TypedArray`, or `DataView`. If `data` is a [`Buffer`][], `TypedArray`, or `DataView`, then `inputEncoding` is ignored. The `outputEncoding` specifies the output format of the enciphered -data, and can be `'latin1'`, `'base64'` or `'hex'`. If the `outputEncoding` +data. If the `outputEncoding` is specified, a string using the specified encoding is returned. If no `outputEncoding` is provided, a [`Buffer`][] is returned. @@ -390,9 +390,9 @@ console.log(decrypted); -* `outputEncoding` {string} +* `outputEncoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} Any remaining deciphered contents. - If `outputEncoding` is one of `'latin1'`, `'ascii'` or `'utf8'`, a string is + If `outputEncoding` is specified, a string is returned. If an `outputEncoding` is not provided, a [`Buffer`][] is returned. Once the `decipher.final()` method has been called, the `Decipher` object can @@ -473,18 +473,18 @@ changes: description: The default `inputEncoding` changed from `binary` to `utf8`. --> * `data` {string | Buffer | TypedArray | DataView} -* `inputEncoding` {string} -* `outputEncoding` {string} +* `inputEncoding` {string} The [encoding][] of the `data` string. +* `outputEncoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} Updates the decipher with `data`. If the `inputEncoding` argument is given, -its value must be one of `'latin1'`, `'base64'`, or `'hex'` and the `data` +the `data` argument is a string using the specified encoding. If the `inputEncoding` argument is not given, `data` must be a [`Buffer`][]. If `data` is a [`Buffer`][] then `inputEncoding` is ignored. The `outputEncoding` specifies the output format of the enciphered -data, and can be `'latin1'`, `'ascii'` or `'utf8'`. If the `outputEncoding` +data. If the `outputEncoding` is specified, a string using the specified encoding is returned. If no `outputEncoding` is provided, a [`Buffer`][] is returned. @@ -528,15 +528,15 @@ assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex')); added: v0.5.0 --> * `otherPublicKey` {string | Buffer | TypedArray | DataView} -* `inputEncoding` {string} -* `outputEncoding` {string} +* `inputEncoding` {string} The [encoding][] of an `otherPublicKey` string. +* `outputEncoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} Computes the shared secret using `otherPublicKey` as the other party's public key and returns the computed shared secret. The supplied key is interpreted using the specified `inputEncoding`, and secret is -encoded using specified `outputEncoding`. Encodings can be -`'latin1'`, `'hex'`, or `'base64'`. If the `inputEncoding` is not +encoded using specified `outputEncoding`. +If the `inputEncoding` is not provided, `otherPublicKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. @@ -547,57 +547,57 @@ If `outputEncoding` is given a string is returned; otherwise, a -* `encoding` {string} +* `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} Generates private and public Diffie-Hellman key values, and returns the public key in the specified `encoding`. This key should be -transferred to the other party. Encoding can be `'latin1'`, `'hex'`, -or `'base64'`. If `encoding` is provided a string is returned; otherwise a +transferred to the other party. +If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getGenerator([encoding]) -* `encoding` {string} +* `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} -Returns the Diffie-Hellman generator in the specified `encoding`, which can -be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is +Returns the Diffie-Hellman generator in the specified `encoding`. +If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getPrime([encoding]) -* `encoding` {string} +* `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} -Returns the Diffie-Hellman prime in the specified `encoding`, which can -be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is +Returns the Diffie-Hellman prime in the specified `encoding`. +If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getPrivateKey([encoding]) -* `encoding` {string} +* `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} -Returns the Diffie-Hellman private key in the specified `encoding`, -which can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a +Returns the Diffie-Hellman private key in the specified `encoding`. +If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.getPublicKey([encoding]) -* `encoding` {string} +* `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} -Returns the Diffie-Hellman public key in the specified `encoding`, which -can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a +Returns the Diffie-Hellman public key in the specified `encoding`. +If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### diffieHellman.setPrivateKey(privateKey[, encoding]) @@ -605,10 +605,10 @@ string is returned; otherwise a [`Buffer`][] is returned. added: v0.5.0 --> * `privateKey` {string | Buffer | TypedArray | DataView} -* `encoding` {string} +* `encoding` {string} The [encoding][] of the `privateKey` string. -Sets the Diffie-Hellman private key. If the `encoding` argument is provided -and is either `'latin1'`, `'hex'`, or `'base64'`, `privateKey` is expected +Sets the Diffie-Hellman private key. If the `encoding` argument is provided, +`privateKey` is expected to be a string. If no `encoding` is provided, `privateKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. @@ -617,10 +617,10 @@ to be a [`Buffer`][], `TypedArray`, or `DataView`. added: v0.5.0 --> * `publicKey` {string | Buffer | TypedArray | DataView} -* `encoding` {string} +* `encoding` {string} The [encoding][] of the `publicKey` string. -Sets the Diffie-Hellman public key. If the `encoding` argument is provided -and is either `'latin1'`, `'hex'` or `'base64'`, `publicKey` is expected +Sets the Diffie-Hellman public key. If the `encoding` argument is provided, +`publicKey` is expected to be a string. If no `encoding` is provided, `publicKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. @@ -678,8 +678,8 @@ added: v10.0.0 * `key` {string | Buffer | TypedArray | DataView} * `curve` {string} -* `inputEncoding` {string} -* `outputEncoding` {string} +* `inputEncoding` {string} The [encoding][] of the `key` string. +* `outputEncoding` {string} The [encoding][] of the return value. * `format` {string} **Default:** `'uncompressed'` * Returns: {Buffer | string} @@ -687,8 +687,7 @@ Converts the EC Diffie-Hellman public key specified by `key` and `curve` to the format specified by `format`. The `format` argument specifies point encoding and can be `'compressed'`, `'uncompressed'` or `'hybrid'`. The supplied key is interpreted using the specified `inputEncoding`, and the returned key is encoded -using the specified `outputEncoding`. Encodings can be `'latin1'`, `'hex'`, -or `'base64'`. +using the specified `outputEncoding`. Use [`crypto.getCurves()`][] to obtain a list of available curve names. On recent OpenSSL releases, `openssl ecparam -list_curves` will also display @@ -733,15 +732,15 @@ changes: error --> * `otherPublicKey` {string | Buffer | TypedArray | DataView} -* `inputEncoding` {string} -* `outputEncoding` {string} +* `inputEncoding` {string} The [encoding][] of the `otherPublicKey` string. +* `outputEncoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} Computes the shared secret using `otherPublicKey` as the other party's public key and returns the computed shared secret. The supplied key is interpreted using specified `inputEncoding`, and the returned secret -is encoded using the specified `outputEncoding`. Encodings can be -`'latin1'`, `'hex'`, or `'base64'`. If the `inputEncoding` is not +is encoded using the specified `outputEncoding`. +If the `inputEncoding` is not provided, `otherPublicKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. @@ -758,7 +757,7 @@ its recommended for developers to handle this exception accordingly. -* `encoding` {string} +* `encoding` {string} The [encoding][] of the return value. * `format` {string} **Default:** `'uncompressed'` * Returns: {Buffer | string} @@ -770,24 +769,24 @@ The `format` argument specifies point encoding and can be `'compressed'` or `'uncompressed'`. If `format` is not specified, the point will be returned in `'uncompressed'` format. -The `encoding` argument can be `'latin1'`, `'hex'`, or `'base64'`. If -`encoding` is provided a string is returned; otherwise a [`Buffer`][] +If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. ### ecdh.getPrivateKey([encoding]) -* `encoding` {string} -* Returns: {Buffer | string} The EC Diffie-Hellman private key in the specified - `encoding`, which can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` - is provided a string is returned; otherwise a [`Buffer`][] is returned. +* `encoding` {string} The [encoding][] of the return value. +* Returns: {Buffer | string} The EC Diffie-Hellman in the specified `encoding`. + +If `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is +returned. ### ecdh.getPublicKey([encoding][, format]) -* `encoding` {string} +* `encoding` {string} The [encoding][] of the return value. * `format` {string} **Default:** `'uncompressed'` * Returns: {Buffer | string} The EC Diffie-Hellman public key in the specified `encoding` and `format`. @@ -796,8 +795,7 @@ The `format` argument specifies point encoding and can be `'compressed'` or `'uncompressed'`. If `format` is not specified the point will be returned in `'uncompressed'` format. -The `encoding` argument can be `'latin1'`, `'hex'`, or `'base64'`. If -`encoding` is specified, a string is returned; otherwise a [`Buffer`][] is +If `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is returned. ### ecdh.setPrivateKey(privateKey[, encoding]) @@ -805,10 +803,10 @@ returned. added: v0.11.14 --> * `privateKey` {string | Buffer | TypedArray | DataView} -* `encoding` {string} +* `encoding` {string} The [encoding][] of the `privateKey` string. -Sets the EC Diffie-Hellman private key. The `encoding` can be `'latin1'`, -`'hex'` or `'base64'`. If `encoding` is provided, `privateKey` is expected +Sets the EC Diffie-Hellman private key. +If `encoding` is provided, `privateKey` is expected to be a string; otherwise `privateKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. @@ -825,10 +823,10 @@ deprecated: v5.2.0 > Stability: 0 - Deprecated * `publicKey` {string | Buffer | TypedArray | DataView} -* `encoding` {string} +* `encoding` {string} The [encoding][] of the `publicKey` string. -Sets the EC Diffie-Hellman public key. Key encoding can be `'latin1'`, -`'hex'` or `'base64'`. If `encoding` is provided `publicKey` is expected to +Sets the EC Diffie-Hellman public key. +If `encoding` is provided `publicKey` is expected to be a string; otherwise a [`Buffer`][], `TypedArray`, or `DataView` is expected. Note that there is not normally a reason to call this method because `ECDH` @@ -925,12 +923,12 @@ console.log(hash.digest('hex')); -* `encoding` {string} +* `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} Calculates the digest of all of the data passed to be hashed (using the -[`hash.update()`][] method). The `encoding` can be `'hex'`, `'latin1'` or -`'base64'`. If `encoding` is provided a string will be returned; otherwise +[`hash.update()`][] method). +If `encoding` is provided a string will be returned; otherwise a [`Buffer`][] is returned. The `Hash` object can not be used again after `hash.digest()` method has been @@ -945,11 +943,11 @@ changes: description: The default `inputEncoding` changed from `binary` to `utf8`. --> * `data` {string | Buffer | TypedArray | DataView} -* `inputEncoding` {string} +* `inputEncoding` {string} The [encoding][] of the `data` string. Updates the hash content with the given `data`, the encoding of which -is given in `inputEncoding` and can be `'utf8'`, `'ascii'` or -`'latin1'`. If `encoding` is not provided, and the `data` is a string, an +is given in `inputEncoding`. +If `encoding` is not provided, and the `data` is a string, an encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or `DataView`, then `inputEncoding` is ignored. @@ -1017,11 +1015,11 @@ console.log(hmac.digest('hex')); -* `encoding` {string} +* `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} Calculates the HMAC digest of all of the data passed using [`hmac.update()`][]. -The `encoding` can be `'hex'`, `'latin1'` or `'base64'`. If `encoding` is +If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned; The `Hmac` object can not be used again after `hmac.digest()` has been @@ -1036,11 +1034,11 @@ changes: description: The default `inputEncoding` changed from `binary` to `utf8`. --> * `data` {string | Buffer | TypedArray | DataView} -* `inputEncoding` {string} +* `inputEncoding` {string} The [encoding][] of the `data` string. Updates the `Hmac` content with the given `data`, the encoding of which -is given in `inputEncoding` and can be `'utf8'`, `'ascii'` or -`'latin1'`. If `encoding` is not provided, and the `data` is a string, an +is given in `inputEncoding`. +If `encoding` is not provided, and the `data` is a string, an encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or `DataView`, then `inputEncoding` is ignored. @@ -1110,7 +1108,7 @@ console.log(sign.sign(privateKey, 'hex')); // Prints: the calculated signature ``` -### sign.sign(privateKey[, outputFormat]) +### sign.sign(privateKey[, outputEncoding]) * `data` {string | Buffer | TypedArray | DataView} -* `inputEncoding` {string} +* `inputEncoding` {string} The [encoding][] of the `data` string. Updates the `Sign` content with the given `data`, the encoding of which -is given in `inputEncoding` and can be `'utf8'`, `'ascii'` or -`'latin1'`. If `encoding` is not provided, and the `data` is a string, an +is given in `inputEncoding`. +If `encoding` is not provided, and the `data` is a string, an encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or `DataView`, then `inputEncoding` is ignored. @@ -1227,17 +1224,17 @@ changes: description: The default `inputEncoding` changed from `binary` to `utf8`. --> * `data` {string | Buffer | TypedArray | DataView} -* `inputEncoding` {string} +* `inputEncoding` {string} The [encoding][] of the `data` string. Updates the `Verify` content with the given `data`, the encoding of which -is given in `inputEncoding` and can be `'utf8'`, `'ascii'` or -`'latin1'`. If `encoding` is not provided, and the `data` is a string, an +is given in `inputEncoding`. +If `inputEncoding` is not provided, and the `data` is a string, an encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][], `TypedArray`, or `DataView`, then `inputEncoding` is ignored. This can be called many times with new data as it is streamed. -### verify.verify(object, signature[, signatureFormat]) +### verify.verify(object, signature[, signatureEncoding]) * `object` {string | Object} * `signature` {string | Buffer | TypedArray | DataView} -* `signatureFormat` {string} +* `signatureEncoding` {string} The [encoding][] of the `signature` string. * Returns: {boolean} `true` or `false` depending on the validity of the signature for the data and public key. @@ -1270,8 +1267,8 @@ or an object with one or more of the following properties: determined automatically. The `signature` argument is the previously calculated signature for the data, in -the `signatureFormat` which can be `'latin1'`, `'hex'` or `'base64'`. -If a `signatureFormat` is specified, the `signature` is expected to be a +the `signatureEncoding`. +If a `signatureEncoding` is specified, the `signature` is expected to be a string; otherwise `signature` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. @@ -1535,10 +1532,10 @@ changes: from `binary` to `utf8`. --> * `prime` {string | Buffer | TypedArray | DataView} -* `primeEncoding` {string} +* `primeEncoding` {string} The [encoding][] of the `prime` string. * `generator` {number | string | Buffer | TypedArray | DataView} **Default:** `2` -* `generatorEncoding` {string} +* `generatorEncoding` {string} The [encoding][] of the `generator` string. * Returns: {DiffieHellman} Creates a `DiffieHellman` key exchange object using the supplied `prime` and an @@ -1547,9 +1544,6 @@ optional specific `generator`. The `generator` argument can be a number, string, or [`Buffer`][]. If `generator` is not specified, the value `2` is used. -The `primeEncoding` and `generatorEncoding` arguments can be `'latin1'`, -`'hex'`, or `'base64'`. - If `primeEncoding` is specified, `prime` is expected to be a string; otherwise a [`Buffer`][], `TypedArray`, or `DataView` is expected. @@ -2894,13 +2888,13 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. [`hash.update()`]: #crypto_hash_update_data_inputencoding [`hmac.digest()`]: #crypto_hmac_digest_encoding [`hmac.update()`]: #crypto_hmac_update_data_inputencoding -[`sign.sign()`]: #crypto_sign_sign_privatekey_outputformat +[`sign.sign()`]: #crypto_sign_sign_privatekey_outputencoding [`sign.update()`]: #crypto_sign_update_data_inputencoding [`stream.transform` options]: stream.html#stream_new_stream_transform_options [`stream.Writable` options]: stream.html#stream_constructor_new_stream_writable_options [`util.promisify()`]: util.html#util_util_promisify_original [`verify.update()`]: #crypto_verify_update_data_inputencoding -[`verify.verify()`]: #crypto_verify_verify_object_signature_signatureformat +[`verify.verify()`]: #crypto_verify_verify_object_signature_signatureencoding [AEAD algorithms]: https://en.wikipedia.org/wiki/Authenticated_encryption [Caveats]: #crypto_support_for_weak_or_compromised_algorithms [CCM mode]: #crypto_ccm_mode @@ -2916,6 +2910,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL. [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt [RFC 3610]: https://www.rfc-editor.org/rfc/rfc3610.txt [RFC 4055]: https://www.rfc-editor.org/rfc/rfc4055.txt +[encoding]: buffer.html#buffer_buffers_and_character_encodings [initialization vector]: https://en.wikipedia.org/wiki/Initialization_vector [scrypt]: https://en.wikipedia.org/wiki/Scrypt [stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback diff --git a/doc/api/errors.md b/doc/api/errors.md index 82c4e790e6b84b..500fb7801b61fd 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -2159,7 +2159,7 @@ such as `process.stdout.on('data')`. [`require()`]: modules.html#modules_require [`server.close()`]: net.html#net_server_close_callback [`server.listen()`]: net.html#net_server_listen -[`sign.sign()`]: crypto.html#crypto_sign_sign_privatekey_outputformat +[`sign.sign()`]: crypto.html#crypto_sign_sign_privatekey_outputencoding [`stream.pipe()`]: stream.html#stream_readable_pipe_destination_options [`stream.push()`]: stream.html#stream_readable_push_chunk_encoding [`stream.unshift()`]: stream.html#stream_readable_unshift_chunk