1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: clarify allowed encoding parameter types

Browse Source 
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 <tniessen@tnie.de>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
This commit is contained in:
Sam Roberts 2018-11-07 12:27:47 -08:00 committed by Rich Trott
parent 1698fc96af
commit 426ca0837a
2 changed files with 91 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
doc/api/crypto.md
View File

@ -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);
<!-- YAML
added: v0.1.94
-->
* `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);
<!-- YAML
added: v0.1.94
-->
* `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
<!-- YAML
added: v0.5.0
-->
* `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])
<!-- YAML
added: v0.5.0
-->
* `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])
<!-- YAML
added: v0.5.0
-->
* `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])
<!-- YAML
added: v0.5.0
-->
* `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])
<!-- YAML
added: v0.5.0
-->
* `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.
<!-- YAML
added: v0.11.14
-->
* `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])
<!-- YAML
added: v0.11.14
-->
* `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])
<!-- YAML
added: v0.11.14
-->
* `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'));
<!-- YAML
added: v0.1.92
-->
* `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'));
<!-- YAML
added: v0.1.94
-->
* `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])
<!-- YAML
added: v0.1.92
changes:
@ -1123,7 +1121,7 @@ changes:
- `passphrase` {string}
- `padding` {integer}
- `saltLength` {integer}
* `outputFormat` {string}
* `outputEncoding` {string} The [encoding][] of the return value.
* Returns: {Buffer | string}
Calculates the signature on all the data passed through using either
@ -1147,9 +1145,8 @@ object, it must contain one or more of the following properties:
size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the
maximum permissible value.
The `outputFormat` can specify one of `'latin1'`, `'hex'` or `'base64'`. If
`outputFormat` is provided a string is returned; otherwise a [`Buffer`][] is
returned.
If `outputEncoding` is provided a string is returned; otherwise a [`Buffer`][]
is returned.
The `Sign` object can not be again used after `sign.sign()` method has been
called. Multiple calls to `sign.sign()` will result in an error being thrown.
@ -1163,11 +1160,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 `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])
<!-- YAML
added: v0.1.92
changes:
@ -1247,7 +1244,7 @@ changes:
-->
* `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

2
doc/api/errors.md
View File

@ -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