From e40ac30e05be0f086e7a0dba18435af3f6386a0f Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Wed, 22 Mar 2017 07:33:31 +0100 Subject: [PATCH] doc: document extent of crypto Uint8Array support PR-URL: https://github.com/nodejs/node/pull/11982 Reviewed-By: Colin Ihrig Reviewed-By: James M Snell Reviewed-By: Luigi Pinca --- doc/api/crypto.md | 116 ++++++++++++++++++++++++---------------------- 1 file 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(); -- `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')); -- `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); -- `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')); -- `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. -- `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]) -- `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 -- `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. -- `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) - `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]) - `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 -- `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