crypto: refactor the crypto module

* Split single monolithic file into multiple
* Make Certificate methods static
* Allow randomFill(Sync) to use any ArrayBufferView
* Use internal/errors throughout
* Improve arg validation in Hash/Hmac
* Doc updates

PR-URL: #15231
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Fedor Indutny <[email protected]>

Author: jasnell

doc/api/crypto.md

@@ -48,7 +48,60 @@ The `crypto` module provides the `Certificate` class for working with SPKAC
 data. The most common usage is handling output generated by the HTML5
 `<keygen>` element. Node.js uses [OpenSSL's SPKAC implementation][] internally.
 
-### new crypto.Certificate()
+### Certificate.exportChallenge(spkac)
+<!-- YAML
+added: REPLACEME
+-->
+- `spkac` {string | Buffer | TypedArray | DataView}
+- Returns {Buffer} The challenge component of the `spkac` data structure, which
+includes a public key and a challenge.
+
+```js
+const { Certificate } = require('crypto');
+const spkac = getSpkacSomehow();
+const challenge = Certificate.exportChallenge(spkac);
+console.log(challenge.toString('utf8'));
+// Prints: the challenge as a UTF8 string
+```
+
+### Certificate.exportPublicKey(spkac)
+<!-- YAML
+added: REPLACEME
+-->
+- `spkac` {string | Buffer | TypedArray | DataView}
+- Returns {Buffer} The public key component of the `spkac` data structure,
+which includes a public key and a challenge.
+
+```js
+const { Certificate } = require('crypto');
+const spkac = getSpkacSomehow();
+const publicKey = Certificate.exportPublicKey(spkac);
+console.log(publicKey);
+// Prints: the public key as <Buffer ...>
+```
+
+### Certificate.verifySpkac(spkac)
+<!-- YAML
+added: REPLACEME
+-->
+- `spkac` {Buffer | TypedArray | DataView}
+- Returns {boolean} `true` if the given `spkac` data structure is valid, `false`
+otherwise.
+
+```js
+const { Certificate } = require('crypto');
+const spkac = getSpkacSomehow();
+console.log(Certificate.verifySpkac(Buffer.from(spkac)));
+// Prints: true or false
+```
+
+### Legacy API
+
+As a still supported legacy interface, it is possible (but not recommended) to
+create new instances of the `crypto.Certificate` class as illustrated in the
+examples below.
+
+#### new crypto.Certificate()
 
 Instances of the `Certificate` class can be created using the `new` keyword
 or by calling `crypto.Certificate()` as a function:
@@ -60,7 +113,7 @@ const cert1 = new crypto.Certificate();
 const cert2 = crypto.Certificate();
 ```
 
-### certificate.exportChallenge(spkac)
+#### certificate.exportChallenge(spkac)
 <!-- YAML
 added: v0.11.8
 -->
@@ -76,7 +129,7 @@ console.log(challenge.toString('utf8'));
 // Prints: the challenge as a UTF8 string
 ```
 
-### certificate.exportPublicKey(spkac)
+#### certificate.exportPublicKey(spkac)
 <!-- YAML
 added: v0.11.8
 -->
@@ -92,7 +145,7 @@ console.log(publicKey);
 // Prints: the public key as <Buffer ...>
 ```
 
-### certificate.verifySpkac(spkac)
+#### certificate.verifySpkac(spkac)
 <!-- YAML
 added: v0.11.8
 -->
@@ -1747,9 +1800,13 @@ negative performance implications for some applications, see the
 ### crypto.randomFillSync(buffer[, offset][, size])
 <!-- YAML
 added: v7.10.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/15231
+    description: The `buffer` argument may be any ArrayBufferView
 -->
 
-* `buffer` {Buffer|Uint8Array} Must be supplied.
+* `buffer` {Buffer|Uint8Array|ArrayBufferView} Must be supplied.
 * `offset` {number} Defaults to `0`.
 * `size` {number} Defaults to `buffer.length - offset`.
 
@@ -1769,12 +1826,29 @@ crypto.randomFillSync(buf, 5, 5);
 console.log(buf.toString('hex'));
 ```
 
+Any `TypedArray` or `DataView` instance may be passed as `buffer`.
+
+```js
+const a = new Uint32Array(10);
+console.log(crypto.randomFillSync(a).toString('hex'));
+
+const b = new Float64Array(10);
+console.log(crypto.randomFillSync(a).toString('hex'));
+
+const c = new DataView(new ArrayBuffer(10));
+console.log(crypto.randomFillSync(a).toString('hex'));
+```
+
 ### crypto.randomFill(buffer[, offset][, size], callback)
 <!-- YAML
 added: v7.10.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/15231
+    description: The `buffer` argument may be any ArrayBufferView
 -->
 
-* `buffer` {Buffer|Uint8Array} Must be supplied.
+* `buffer` {Buffer|Uint8Array|ArrayBufferView} Must be supplied.
 * `offset` {number} Defaults to `0`.
 * `size` {number} Defaults to `buffer.length - offset`.
 * `callback` {Function} `function(err, buf) {}`.
@@ -1804,6 +1878,28 @@ crypto.randomFill(buf, 5, 5, (err, buf) => {
 });
 ```
 
+Any `TypedArray` or `DataView` instance may be passed as `buffer`.
+
+```js
+const a = new Uint32Array(10);
+crypto.randomFill(a, (err, buf) => {
+  if (err) throw err;
+  console.log(buf.toString('hex'));
+});
+
+const b = new Float64Array(10);
+crypto.randomFill(b, (err, buf) => {
+  if (err) throw err;
+  console.log(buf.toString('hex'));
+});
+
+const c = new DataView(new ArrayBuffer(10));
+crypto.randomFill(c, (err, buf) => {
+  if (err) throw err;
+  console.log(buf.toString('hex'));
+});
+```
+
 Note that this API uses libuv's threadpool, which can have surprising and
 negative performance implications for some applications, see the
 [`UV_THREADPOOL_SIZE`][] documentation for more information.

doc/api/errors.md

@@ -621,6 +621,12 @@ Used when `Console` is instantiated without `stdout` stream or when `stdout` or
 
 Used when the native call from `process.cpuUsage` cannot be processed properly.
 
+<a id="ERR_CRYPTO_ECDH_INVALID_FORMAT"></a>
+### ERR_CRYPTO_ECDH_INVALID_FORMAT
+
+Used when an invalid value for the `format` argument has been passed to the
+`crypto.ECDH()` class `getPublicKey()` method.
+
 <a id="ERR_DNS_SET_SERVERS_FAILED"></a>
 ### ERR_DNS_SET_SERVERS_FAILED