Skip to content

Commit

Permalink
crypto: refactor the crypto module
Browse files Browse the repository at this point in the history
* 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: nodejs#15231
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Fedor Indutny <[email protected]>
  • Loading branch information
jasnell committed Sep 18, 2017
1 parent 8fa5fcc commit c75f87c
Show file tree
Hide file tree
Showing 25 changed files with 1,712 additions and 1,030 deletions.
108 changes: 102 additions & 6 deletions doc/api/crypto.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -60,7 +113,7 @@ const cert1 = new crypto.Certificate();
const cert2 = crypto.Certificate();
```

### certificate.exportChallenge(spkac)
#### certificate.exportChallenge(spkac)
<!-- YAML
added: v0.11.8
-->
Expand All @@ -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
-->
Expand All @@ -92,7 +145,7 @@ console.log(publicKey);
// Prints: the public key as <Buffer ...>
```

### certificate.verifySpkac(spkac)
#### certificate.verifySpkac(spkac)
<!-- YAML
added: v0.11.8
-->
Expand Down Expand Up @@ -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`.

Expand All @@ -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) {}`.
Expand Down Expand Up @@ -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.
Expand Down
6 changes: 6 additions & 0 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading

0 comments on commit c75f87c

Please sign in to comment.