doc: document extent of crypto Uint8Array support
PR-URL: https://github.com/nodejs/node/pull/11982 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
This commit is contained in:
Anna Henningsen
James M Snell
parent
4929d12e99
commit
e40ac30e05
@ -62,7 +62,7 @@ const cert2 = crypto.Certificate();
|
||||
<!-- YAML
|
||||
added: v0.11.8
|
||||
-->
|
||||
- `spkac` {string | Buffer}
|
||||
- `spkac` {string | Buffer | Uint8Array}
|
||||
- Returns {Buffer} The challenge component of the `spkac` data structure, which
|
||||
includes a public key and a challenge.
|
||||
|
||||
@ -78,7 +78,7 @@ console.log(challenge.toString('utf8'));
|
||||
<!-- YAML
|
||||
added: v0.11.8
|
||||
-->
|
||||
- `spkac` {string | Buffer}
|
||||
- `spkac` {string | Buffer | Uint8Array}
|
||||
- Returns {Buffer} The public key component of the `spkac` data structure,
|
||||
which includes a public key and a challenge.
|
||||
|
||||
@ -94,7 +94,7 @@ console.log(publicKey);
|
||||
<!-- YAML
|
||||
added: v0.11.8
|
||||
-->
|
||||
- `spkac` {Buffer}
|
||||
- `spkac` {Buffer | Uint8Array}
|
||||
- Returns {boolean} `true` if the given `spkac` data structure is valid, `false`
|
||||
otherwise.
|
||||
|
||||
@ -234,15 +234,15 @@ changes:
|
||||
pr-url: https://github.com/nodejs/node/pull/5522
|
||||
description: The default `input_encoding` changed from `binary` to `utf8`.
|
||||
-->
|
||||
- `data` {string | Buffer}
|
||||
- `data` {string | Buffer | Uint8Array}
|
||||
- `input_encoding` {string}
|
||||
- `output_encoding` {string}
|
||||
|
||||
Updates the cipher with `data`. If the `input_encoding` argument is given,
|
||||
its value must be one of `'utf8'`, `'ascii'`, or `'latin1'` and the `data`
|
||||
argument is a string using the specified encoding. If the `input_encoding`
|
||||
argument is not given, `data` must be a [`Buffer`][]. If `data` is a
|
||||
[`Buffer`][] then `input_encoding` is ignored.
|
||||
argument is not given, `data` must be a [`Buffer`][] or `Uint8Array`.
|
||||
If `data` is a [`Buffer`][] or `Uint8Array`, then `input_encoding` is ignored.
|
||||
|
||||
The `output_encoding` specifies the output format of the enciphered
|
||||
data, and can be `'latin1'`, `'base64'` or `'hex'`. If the `output_encoding`
|
||||
@ -340,7 +340,7 @@ changes:
|
||||
pr-url: https://github.com/nodejs/node/pull/9398
|
||||
description: This method now returns a reference to `decipher`.
|
||||
-->
|
||||
- `buffer` {Buffer}
|
||||
- `buffer` {Buffer | Uint8Array}
|
||||
- Returns the {Cipher} for method chaining.
|
||||
|
||||
When using an authenticated encryption mode (only `GCM` is currently
|
||||
@ -357,7 +357,7 @@ changes:
|
||||
pr-url: https://github.com/nodejs/node/pull/9398
|
||||
description: This method now returns a reference to `decipher`.
|
||||
-->
|
||||
- `buffer` {Buffer}
|
||||
- `buffer` {Buffer | Uint8Array}
|
||||
- Returns the {Cipher} for method chaining.
|
||||
|
||||
When using an authenticated encryption mode (only `GCM` is currently
|
||||
@ -394,7 +394,7 @@ changes:
|
||||
pr-url: https://github.com/nodejs/node/pull/5522
|
||||
description: The default `input_encoding` changed from `binary` to `utf8`.
|
||||
-->
|
||||
- `data` {string | Buffer}
|
||||
- `data` {string | Buffer | Uint8Array}
|
||||
- `input_encoding` {string}
|
||||
- `output_encoding` {string}
|
||||
|
||||
@ -448,7 +448,7 @@ assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex'));
|
||||
<!-- YAML
|
||||
added: v0.5.0
|
||||
-->
|
||||
- `other_public_key` {string | Buffer}
|
||||
- `other_public_key` {string | Buffer | Uint8Array}
|
||||
- `input_encoding` {string}
|
||||
- `output_encoding` {string}
|
||||
|
||||
@ -457,7 +457,7 @@ party's public key and returns the computed shared secret. The supplied
|
||||
key is interpreted using the specified `input_encoding`, and secret is
|
||||
encoded using specified `output_encoding`. Encodings can be
|
||||
`'latin1'`, `'hex'`, or `'base64'`. If the `input_encoding` is not
|
||||
provided, `other_public_key` is expected to be a [`Buffer`][].
|
||||
provided, `other_public_key` is expected to be a [`Buffer`][] or `Uint8Array`.
|
||||
|
||||
If `output_encoding` is given a string is returned; otherwise, a
|
||||
[`Buffer`][] is returned.
|
||||
@ -518,25 +518,25 @@ string is returned; otherwise a [`Buffer`][] is returned.
|
||||
<!-- YAML
|
||||
added: v0.5.0
|
||||
-->
|
||||
- `private_key` {string | Buffer}
|
||||
- `private_key` {string | Buffer | Uint8Array}
|
||||
- `encoding` {string}
|
||||
|
||||
Sets the Diffie-Hellman private key. If the `encoding` argument is provided
|
||||
and is either `'latin1'`, `'hex'`, or `'base64'`, `private_key` is expected
|
||||
to be a string. If no `encoding` is provided, `private_key` is expected
|
||||
to be a [`Buffer`][].
|
||||
to be a [`Buffer`][] or `Uint8Array`.
|
||||
|
||||
### diffieHellman.setPublicKey(public_key[, encoding])
|
||||
<!-- YAML
|
||||
added: v0.5.0
|
||||
-->
|
||||
- `public_key` {string | Buffer}
|
||||
- `public_key` {string | Buffer | Uint8Array}
|
||||
- `encoding` {string}
|
||||
|
||||
Sets the Diffie-Hellman public key. If the `encoding` argument is provided
|
||||
and is either `'latin1'`, `'hex'` or `'base64'`, `public_key` is expected
|
||||
to be a string. If no `encoding` is provided, `public_key` is expected
|
||||
to be a [`Buffer`][].
|
||||
to be a [`Buffer`][] or `Uint8Array`.
|
||||
|
||||
### diffieHellman.verifyError
|
||||
<!-- YAML
|
||||
@ -593,7 +593,7 @@ changes:
|
||||
pr-url: https://github.com/nodejs/node/pull/5522
|
||||
description: The default `input_encoding` changed from `binary` to `utf8`.
|
||||
-->
|
||||
- `other_public_key` {string | Buffer}
|
||||
- `other_public_key` {string | Buffer | Uint8Array}
|
||||
- `input_encoding` {string}
|
||||
- `output_encoding` {string}
|
||||
|
||||
@ -602,7 +602,7 @@ party's public key and returns the computed shared secret. The supplied
|
||||
key is interpreted using specified `input_encoding`, and the returned secret
|
||||
is encoded using the specified `output_encoding`. Encodings can be
|
||||
`'latin1'`, `'hex'`, or `'base64'`. If the `input_encoding` is not
|
||||
provided, `other_public_key` is expected to be a [`Buffer`][].
|
||||
provided, `other_public_key` is expected to be a [`Buffer`][] or `Uint8Array`.
|
||||
|
||||
If `output_encoding` is given a string will be returned; otherwise a
|
||||
[`Buffer`][] is returned.
|
||||
@ -658,13 +658,14 @@ returned.
|
||||
<!-- YAML
|
||||
added: v0.11.14
|
||||
-->
|
||||
- `private_key` {string | Buffer}
|
||||
- `private_key` {string | Buffer | Uint8Array}
|
||||
- `encoding` {string}
|
||||
|
||||
Sets the EC Diffie-Hellman private key. The `encoding` can be `'latin1'`,
|
||||
`'hex'` or `'base64'`. If `encoding` is provided, `private_key` is expected
|
||||
to be a string; otherwise `private_key` is expected to be a [`Buffer`][]. If
|
||||
`private_key` is not valid for the curve specified when the `ECDH` object was
|
||||
to be a string; otherwise `private_key` is expected to be a [`Buffer`][]
|
||||
or `Uint8Array`.
|
||||
If `private_key` is not valid for the curve specified when the `ECDH` object was
|
||||
created, an error is thrown. Upon setting the private key, the associated
|
||||
public point (key) is also generated and set in the ECDH object.
|
||||
|
||||
@ -676,12 +677,12 @@ deprecated: v5.2.0
|
||||
|
||||
> Stability: 0 - Deprecated
|
||||
|
||||
- `public_key` {string | Buffer}
|
||||
- `public_key` {string | Buffer | Uint8Array}
|
||||
- `encoding` {string}
|
||||
|
||||
Sets the EC Diffie-Hellman public key. Key encoding can be `'latin1'`,
|
||||
`'hex'` or `'base64'`. If `encoding` is provided `public_key` is expected to
|
||||
be a string; otherwise a [`Buffer`][] is expected.
|
||||
be a string; otherwise a [`Buffer`][] or `Uint8Array` is expected.
|
||||
|
||||
Note that there is not normally a reason to call this method because `ECDH`
|
||||
only requires a private key and the other party's public key to compute the
|
||||
@ -794,14 +795,14 @@ changes:
|
||||
pr-url: https://github.com/nodejs/node/pull/5522
|
||||
description: The default `input_encoding` changed from `binary` to `utf8`.
|
||||
-->
|
||||
- `data` {string | Buffer}
|
||||
- `data` {string | Buffer | Uint8Array}
|
||||
- `input_encoding` {string}
|
||||
|
||||
Updates the hash content with the given `data`, the encoding of which
|
||||
is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
|
||||
`'latin1'`. If `encoding` is not provided, and the `data` is a string, an
|
||||
encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then
|
||||
`input_encoding` is ignored.
|
||||
encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] or `Uint8Array`
|
||||
then `input_encoding` is ignored.
|
||||
|
||||
This can be called many times with new data as it is streamed.
|
||||
|
||||
@ -883,14 +884,14 @@ changes:
|
||||
pr-url: https://github.com/nodejs/node/pull/5522
|
||||
description: The default `input_encoding` changed from `binary` to `utf8`.
|
||||
-->
|
||||
- `data` {string | Buffer}
|
||||
- `data` {string | Buffer | Uint8Array}
|
||||
- `input_encoding` {string}
|
||||
|
||||
Updates the `Hmac` content with the given `data`, the encoding of which
|
||||
is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
|
||||
`'latin1'`. If `encoding` is not provided, and the `data` is a string, an
|
||||
encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then
|
||||
`input_encoding` is ignored.
|
||||
encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] or `Uint8Array`
|
||||
then `input_encoding` is ignored.
|
||||
|
||||
This can be called many times with new data as it is streamed.
|
||||
|
||||
@ -994,14 +995,14 @@ changes:
|
||||
pr-url: https://github.com/nodejs/node/pull/5522
|
||||
description: The default `input_encoding` changed from `binary` to `utf8`.
|
||||
-->
|
||||
- `data` {string | Buffer}
|
||||
- `data` {string | Buffer | Uint8Array}
|
||||
- `input_encoding` {string}
|
||||
|
||||
Updates the `Sign` content with the given `data`, the encoding of which
|
||||
is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
|
||||
`'latin1'`. If `encoding` is not provided, and the `data` is a string, an
|
||||
encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then
|
||||
`input_encoding` is ignored.
|
||||
encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] or `Uint8Array`
|
||||
then `input_encoding` is ignored.
|
||||
|
||||
This can be called many times with new data as it is streamed.
|
||||
|
||||
@ -1058,14 +1059,14 @@ changes:
|
||||
pr-url: https://github.com/nodejs/node/pull/5522
|
||||
description: The default `input_encoding` changed from `binary` to `utf8`.
|
||||
-->
|
||||
- `data` {string | Buffer}
|
||||
- `data` {string | Buffer | Uint8Array}
|
||||
- `input_encoding` {string}
|
||||
|
||||
Updates the `Verify` content with the given `data`, the encoding of which
|
||||
is given in `input_encoding` and can be `'utf8'`, `'ascii'` or
|
||||
`'latin1'`. If `encoding` is not provided, and the `data` is a string, an
|
||||
encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] then
|
||||
`input_encoding` is ignored.
|
||||
encoding of `'utf8'` is enforced. If `data` is a [`Buffer`][] or `Uint8Array`
|
||||
then `input_encoding` is ignored.
|
||||
|
||||
This can be called many times with new data as it is streamed.
|
||||
|
||||
@ -1074,7 +1075,7 @@ This can be called many times with new data as it is streamed.
|
||||
added: v0.1.92
|
||||
-->
|
||||
- `object` {string}
|
||||
- `signature` {string | Buffer}
|
||||
- `signature` {string | Buffer | Uint8Array}
|
||||
- `signature_format` {string}
|
||||
|
||||
Verifies the provided data using the given `object` and `signature`.
|
||||
@ -1083,7 +1084,8 @@ an RSA public key, a DSA public key, or an X.509 certificate.
|
||||
The `signature` argument is the previously calculated signature for the data, in
|
||||
the `signature_format` which can be `'latin1'`, `'hex'` or `'base64'`.
|
||||
If a `signature_format` is specified, the `signature` is expected to be a
|
||||
string; otherwise `signature` is expected to be a [`Buffer`][].
|
||||
string; otherwise `signature` is expected to be a [`Buffer`][] or
|
||||
`Uint8Array`.
|
||||
|
||||
Returns `true` or `false` depending on the validity of the signature for
|
||||
the data and public key.
|
||||
@ -1131,7 +1133,7 @@ currently in use. Setting to true requires a FIPS build of Node.js.
|
||||
added: v0.1.94
|
||||
-->
|
||||
- `algorithm` {string}
|
||||
- `password` {string | Buffer}
|
||||
- `password` {string | Buffer | Uint8Array}
|
||||
|
||||
Creates and returns a `Cipher` object that uses the given `algorithm` and
|
||||
`password`.
|
||||
@ -1141,7 +1143,8 @@ recent OpenSSL releases, `openssl list-cipher-algorithms` will display the
|
||||
available cipher algorithms.
|
||||
|
||||
The `password` is used to derive the cipher key and initialization vector (IV).
|
||||
The value must be either a `'latin1'` encoded string or a [`Buffer`][].
|
||||
The value must be either a `'latin1'` encoded string, a [`Buffer`][] or a
|
||||
`Uint8Array`.
|
||||
|
||||
The implementation of `crypto.createCipher()` derives keys using the OpenSSL
|
||||
function [`EVP_BytesToKey`][] with the digest algorithm set to MD5, one
|
||||
@ -1157,8 +1160,8 @@ to create the `Cipher` object.
|
||||
|
||||
### crypto.createCipheriv(algorithm, key, iv)
|
||||
- `algorithm` {string}
|
||||
- `key` {string | Buffer}
|
||||
- `iv` {string | Buffer}
|
||||
- `key` {string | Buffer | Uint8Array}
|
||||
- `iv` {string | Buffer | Uint8Array}
|
||||
|
||||
Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
|
||||
initialization vector (`iv`).
|
||||
@ -1168,8 +1171,8 @@ 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 or
|
||||
[buffers][`Buffer`].
|
||||
[initialization vector][]. Both arguments must be `'utf8'` encoded strings,
|
||||
[Buffers][`Buffer`] or `Uint8Array`s.
|
||||
|
||||
### crypto.createCredentials(details)
|
||||
<!-- YAML
|
||||
@ -1194,7 +1197,7 @@ called.
|
||||
added: v0.1.94
|
||||
-->
|
||||
- `algorithm` {string}
|
||||
- `password` {string | Buffer}
|
||||
- `password` {string | Buffer | Uint8Array}
|
||||
|
||||
Creates and returns a `Decipher` object that uses the given `algorithm` and
|
||||
`password` (key).
|
||||
@ -1216,8 +1219,8 @@ to create the `Decipher` object.
|
||||
added: v0.1.94
|
||||
-->
|
||||
- `algorithm` {string}
|
||||
- `key` {string | Buffer}
|
||||
- `iv` {string | Buffer}
|
||||
- `key` {string | Buffer | Uint8Array}
|
||||
- `iv` {string | Buffer | Uint8Array}
|
||||
|
||||
Creates and returns a `Decipher` object that uses the given `algorithm`, `key`
|
||||
and initialization vector (`iv`).
|
||||
@ -1241,7 +1244,7 @@ changes:
|
||||
-->
|
||||
- `prime` {string | Buffer}
|
||||
- `prime_encoding` {string}
|
||||
- `generator` {number | string | Buffer} Defaults to `2`.
|
||||
- `generator` {number | string | Buffer | Uint8Array} Defaults to `2`.
|
||||
- `generator_encoding` {string}
|
||||
|
||||
Creates a `DiffieHellman` key exchange object using the supplied `prime` and an
|
||||
@ -1257,14 +1260,14 @@ If `prime_encoding` is specified, `prime` is expected to be a string; otherwise
|
||||
a [`Buffer`][] is expected.
|
||||
|
||||
If `generator_encoding` is specified, `generator` is expected to be a string;
|
||||
otherwise either a number or [`Buffer`][] is expected.
|
||||
otherwise either a number or [`Buffer`][] or `Uint8Array` is expected.
|
||||
|
||||
### crypto.createDiffieHellman(prime_length[, generator])
|
||||
<!-- YAML
|
||||
added: v0.5.0
|
||||
-->
|
||||
- `prime_length` {number}
|
||||
- `generator` {number | string | Buffer} Defaults to `2`.
|
||||
- `generator` {number | string | Buffer | Uint8Array} Defaults to `2`.
|
||||
|
||||
Creates a `DiffieHellman` key exchange object and generates a prime of
|
||||
`prime_length` bits using an optional specific numeric `generator`.
|
||||
@ -1321,7 +1324,7 @@ input.on('readable', () => {
|
||||
added: v0.1.94
|
||||
-->
|
||||
- `algorithm` {string}
|
||||
- `key` {string | Buffer}
|
||||
- `key` {string | Buffer | Uint8Array}
|
||||
|
||||
Creates and returns an `Hmac` object that uses the given `algorithm` and `key`.
|
||||
|
||||
@ -1560,7 +1563,7 @@ added: v0.11.14
|
||||
- `padding` {crypto.constants} An optional padding value defined in
|
||||
`crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`,
|
||||
`RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`.
|
||||
- `buffer` {Buffer}
|
||||
- `buffer` {Buffer | Uint8Array}
|
||||
|
||||
Decrypts `buffer` with `private_key`.
|
||||
|
||||
@ -1577,7 +1580,7 @@ added: v1.1.0
|
||||
- `padding` {crypto.constants} An optional padding value defined in
|
||||
`crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING` or
|
||||
`RSA_PKCS1_PADDING`.
|
||||
- `buffer` {Buffer}
|
||||
- `buffer` {Buffer | Uint8Array}
|
||||
|
||||
Encrypts `buffer` with `private_key`.
|
||||
|
||||
@ -1594,7 +1597,7 @@ added: v1.1.0
|
||||
- `padding` {crypto.constants} An optional padding value defined in
|
||||
`crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`,
|
||||
`RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`.
|
||||
- `buffer` {Buffer}
|
||||
- `buffer` {Buffer | Uint8Array}
|
||||
|
||||
Decrypts `buffer` with `public_key`.
|
||||
|
||||
@ -1614,7 +1617,7 @@ added: v0.11.14
|
||||
- `padding` {crypto.constants} An optional padding value defined in
|
||||
`crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`,
|
||||
`RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`.
|
||||
- `buffer` {Buffer}
|
||||
- `buffer` {Buffer | Uint8Array}
|
||||
|
||||
Encrypts `buffer` with `public_key`.
|
||||
|
||||
@ -1699,15 +1702,16 @@ is a bit field taking one of or a mix of the following flags (defined in
|
||||
<!-- YAML
|
||||
added: v6.6.0
|
||||
-->
|
||||
- `a` {Buffer}
|
||||
- `b` {Buffer}
|
||||
- `a` {Buffer | Uint8Array}
|
||||
- `b` {Buffer | Uint8Array}
|
||||
|
||||
Returns true if `a` is equal to `b`, without leaking timing information that
|
||||
would allow an attacker to guess one of the values. This is suitable for
|
||||
comparing HMAC digests or secret values like authentication cookies or
|
||||
[capability urls](https://www.w3.org/TR/capability-urls/).
|
||||
|
||||
`a` and `b` must both be `Buffer`s, and they must have the same length.
|
||||
`a` and `b` must both be `Buffer`s or `Uint8Array`s, and they must have the
|
||||
same length.
|
||||
|
||||
**Note**: Use of `crypto.timingSafeEqual` does not guarantee that the
|
||||
*surrounding* code is timing-safe. Care should be taken to ensure that the
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user