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>

1 files changed, 60 insertions, 56 deletions

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 9557273a9b7..077c244c431 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -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