doc: add and unify return statements in crypto.md

Conform return statements to the style guide and tool parsers.

Also bring back a description fragment
that seems to be erroneously deleted in
1e07acd476

PR-URL: https://github.com/nodejs/node/pull/19853
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
This commit is contained in:
Vse Mozhet Byt 2018-04-06 18:28:20 +03:00
parent c529168249
commit 0bd3da15a0
2 changed files with 82 additions and 56 deletions

View File

@ -56,7 +56,7 @@ data. The most common usage is handling output generated by the HTML5
added: v9.0.0
-->
- `spkac` {string | Buffer | TypedArray | DataView}
- Returns {Buffer} The challenge component of the `spkac` data structure, which
- Returns: {Buffer} The challenge component of the `spkac` data structure, which
includes a public key and a challenge.
```js
@ -73,7 +73,7 @@ added: v9.0.0
-->
- `spkac` {string | Buffer | TypedArray | DataView}
- `encoding` {string}
- Returns {Buffer} The public key component of the `spkac` data structure,
- Returns: {Buffer} The public key component of the `spkac` data structure,
which includes a public key and a challenge.
```js
@ -89,8 +89,8 @@ console.log(publicKey);
added: v9.0.0
-->
- `spkac` {Buffer | TypedArray | DataView}
- Returns {boolean} `true` if the given `spkac` data structure is valid, `false`
otherwise.
- Returns: {boolean} `true` if the given `spkac` data structure is valid,
`false` otherwise.
```js
const { Certificate } = require('crypto');
@ -122,7 +122,7 @@ const cert2 = crypto.Certificate();
added: v0.11.8
-->
- `spkac` {string | Buffer | TypedArray | DataView}
- Returns {Buffer} The challenge component of the `spkac` data structure, which
- Returns: {Buffer} The challenge component of the `spkac` data structure, which
includes a public key and a challenge.
```js
@ -138,7 +138,7 @@ console.log(challenge.toString('utf8'));
added: v0.11.8
-->
- `spkac` {string | Buffer | TypedArray | DataView}
- Returns {Buffer} The public key component of the `spkac` data structure,
- Returns: {Buffer} The public key component of the `spkac` data structure,
which includes a public key and a challenge.
```js
@ -154,8 +154,8 @@ console.log(publicKey);
added: v0.11.8
-->
- `spkac` {Buffer | TypedArray | DataView}
- Returns {boolean} `true` if the given `spkac` data structure is valid, `false`
otherwise.
- Returns: {boolean} `true` if the given `spkac` data structure is valid,
`false` otherwise.
```js
const cert = require('crypto').Certificate();
@ -232,10 +232,10 @@ console.log(encrypted);
added: v0.1.94
-->
- `outputEncoding` {string}
Returns any remaining enciphered contents. If `outputEncoding`
parameter is one of `'latin1'`, `'base64'` or `'hex'`, a string is returned.
If an `outputEncoding` is not provided, a [`Buffer`][] is returned.
- Returns: {Buffer | string} Any remaining enciphered contents.
If `outputEncoding` parameter is one of `'latin1'`, `'base64'` or `'hex'`,
a string is returned. If an `outputEncoding` is not provided, a [`Buffer`][]
is returned.
Once the `cipher.final()` method has been called, the `Cipher` object can no
longer be used to encrypt data. Attempts to call `cipher.final()` more than
@ -246,8 +246,8 @@ once will result in an error being thrown.
added: v1.0.0
-->
- `buffer` {Buffer}
- `options` {object}
- Returns the {Cipher} for method chaining.
- `options` {Object}
- Returns: {Cipher} for method chaining.
When using an authenticated encryption mode (only `GCM` and `CCM` are currently
supported), the `cipher.setAAD()` method sets the value used for the
@ -263,10 +263,10 @@ The `cipher.setAAD()` method must be called before [`cipher.update()`][].
<!-- YAML
added: v1.0.0
-->
When using an authenticated encryption mode (only `GCM` is currently
supported), the `cipher.getAuthTag()` method returns a [`Buffer`][] containing
the _authentication tag_ that has been computed from the given data.
- Returns: {Buffer} When using an authenticated encryption mode (only `GCM` is
currently supported), the `cipher.getAuthTag()` method returns a [`Buffer`][]
containing the _authentication tag_ that has been computed from the given
data.
The `cipher.getAuthTag()` method should only be called after encryption has
been completed using the [`cipher.final()`][] method.
@ -276,7 +276,7 @@ been completed using the [`cipher.final()`][] method.
added: v0.7.1
-->
- `autoPadding` {boolean} **Default:** `true`
- Returns the {Cipher} for method chaining.
- Returns: {Cipher} for method chaining.
When using block encryption algorithms, the `Cipher` class will automatically
add padding to the input data to the appropriate block size. To disable the
@ -301,6 +301,7 @@ changes:
- `data` {string | Buffer | TypedArray | DataView}
- `inputEncoding` {string}
- `outputEncoding` {string}
- Returns: {Buffer | string}
Updates the cipher with `data`. If the `inputEncoding` argument is given,
its value must be one of `'utf8'`, `'ascii'`, or `'latin1'` and the `data`
@ -390,10 +391,10 @@ console.log(decrypted);
added: v0.1.94
-->
- `outputEncoding` {string}
Returns any remaining deciphered contents. If `outputEncoding`
parameter is one of `'latin1'`, `'ascii'` or `'utf8'`, a string is returned.
If an `outputEncoding` is not provided, a [`Buffer`][] is returned.
- Returns: {Buffer | string} Any remaining deciphered contents.
If `outputEncoding` parameter is one of `'latin1'`, `'ascii'` or `'utf8'`,
a string is returned. If an `outputEncoding` is not provided, a [`Buffer`][]
is returned.
Once the `decipher.final()` method has been called, the `Decipher` object can
no longer be used to decrypt data. Attempts to call `decipher.final()` more
@ -408,7 +409,7 @@ changes:
description: This method now returns a reference to `decipher`.
-->
- `buffer` {Buffer | TypedArray | DataView}
- Returns the {Cipher} for method chaining.
- Returns: {Cipher} for method chaining.
When using an authenticated encryption mode (only `GCM` is currently
supported), the `decipher.setAAD()` method sets the value used for the
@ -425,7 +426,7 @@ changes:
description: This method now returns a reference to `decipher`.
-->
- `buffer` {Buffer | TypedArray | DataView}
- Returns the {Cipher} for method chaining.
- Returns: {Cipher} for method chaining.
When using an authenticated encryption mode (only `GCM` is currently
supported), the `decipher.setAuthTag()` method is used to pass in the
@ -449,7 +450,7 @@ The `decipher.setAuthTag()` method must be called before
added: v0.7.1
-->
- `autoPadding` {boolean} **Default:** `true`
- Returns the {Cipher} for method chaining.
- Returns: {Cipher} for method chaining.
When data has been encrypted without standard block padding, calling
`decipher.setAutoPadding(false)` will disable automatic padding to prevent
@ -472,6 +473,7 @@ changes:
- `data` {string | Buffer | TypedArray | DataView}
- `inputEncoding` {string}
- `outputEncoding` {string}
- Returns: {Buffer | string}
Updates the decipher with `data`. If the `inputEncoding` argument is given,
its value must be one of `'latin1'`, `'base64'`, or `'hex'` and the `data`
@ -526,6 +528,7 @@ added: v0.5.0
- `otherPublicKey` {string | Buffer | TypedArray | DataView}
- `inputEncoding` {string}
- `outputEncoding` {string}
- Returns: {Buffer | string}
Computes the shared secret using `otherPublicKey` as the other
party's public key and returns the computed shared secret. The supplied
@ -543,6 +546,7 @@ If `outputEncoding` is given a string is returned; otherwise, a
added: v0.5.0
-->
- `encoding` {string}
- Returns: {Buffer | string}
Generates private and public Diffie-Hellman key values, and returns
the public key in the specified `encoding`. This key should be
@ -555,6 +559,7 @@ or `'base64'`. If `encoding` is provided a string is returned; otherwise a
added: v0.5.0
-->
- `encoding` {string}
- Returns: {Buffer | string}
Returns the Diffie-Hellman generator in the specified `encoding`, which can
be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is
@ -565,6 +570,7 @@ returned; otherwise a [`Buffer`][] is returned.
added: v0.5.0
-->
- `encoding` {string}
- Returns: {Buffer | string}
Returns the Diffie-Hellman prime in the specified `encoding`, which can
be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a string is
@ -575,6 +581,7 @@ returned; otherwise a [`Buffer`][] is returned.
added: v0.5.0
-->
- `encoding` {string}
- Returns: {Buffer | string}
Returns the Diffie-Hellman private key in the specified `encoding`,
which can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a
@ -585,6 +592,7 @@ string is returned; otherwise a [`Buffer`][] is returned.
added: v0.5.0
-->
- `encoding` {string}
- Returns: {Buffer | string}
Returns the Diffie-Hellman public key in the specified `encoding`, which
can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided a
@ -671,6 +679,7 @@ added: REPLACEME
- `inputEncoding` {string}
- `outputEncoding` {string}
- `format` {string} **Default:** `uncompressed`
- Returns: {Buffer | string}
Converts the EC Diffie-Hellman public key specified by `key` and `curve` to the
format specified by `format`. The `format` argument specifies point encoding
@ -724,6 +733,7 @@ changes:
- `otherPublicKey` {string | Buffer | TypedArray | DataView}
- `inputEncoding` {string}
- `outputEncoding` {string}
- Returns: {Buffer | string}
Computes the shared secret using `otherPublicKey` as the other
party's public key and returns the computed shared secret. The supplied
@ -748,6 +758,7 @@ added: v0.11.14
-->
- `encoding` {string}
- `format` {string} **Default:** `uncompressed`
- Returns: {Buffer | string}
Generates private and public EC Diffie-Hellman key values, and returns
the public key in the specified `format` and `encoding`. This key should be
@ -766,10 +777,9 @@ is returned.
added: v0.11.14
-->
- `encoding` {string}
Returns the EC Diffie-Hellman private key in the specified `encoding`,
which can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding` is provided
a string is returned; otherwise a [`Buffer`][] is returned.
- Returns: {Buffer | string} The EC Diffie-Hellman private key in the specified
`encoding`, which can be `'latin1'`, `'hex'`, or `'base64'`. If `encoding`
is provided a string is returned; otherwise a [`Buffer`][] is returned.
### ecdh.getPublicKey([encoding][, format])
<!-- YAML
@ -777,9 +787,8 @@ added: v0.11.14
-->
- `encoding` {string}
- `format` {string} **Default:** `uncompressed`
Returns the EC Diffie-Hellman public key in the specified `encoding` and
`format`.
- Returns: {Buffer | string} The EC Diffie-Hellman public key in the specified
`encoding` and `format`.
The `format` argument specifies point encoding and can be `'compressed'` or
`'uncompressed'`. If `format` is not specified the point will be returned in
@ -915,6 +924,7 @@ console.log(hash.digest('hex'));
added: v0.1.92
-->
- `encoding` {string}
- Returns: {Buffer | string}
Calculates the digest of all of the data passed to be hashed (using the
[`hash.update()`][] method). The `encoding` can be `'hex'`, `'latin1'` or
@ -1006,6 +1016,7 @@ console.log(hmac.digest('hex'));
added: v0.1.94
-->
- `encoding` {string}
- Returns: {Buffer | string}
Calculates the HMAC digest of all of the data passed using [`hmac.update()`][].
The `encoding` can be `'hex'`, `'latin1'` or `'base64'`. If `encoding` is
@ -1109,6 +1120,7 @@ changes:
- `key` {string}
- `passphrase` {string}
- `outputFormat` {string}
- Returns: {Buffer | string}
Calculates the signature on all the data passed through using either
[`sign.update()`][] or [`sign.write()`][stream-writable-write].
@ -1232,6 +1244,8 @@ changes:
- `object` {string | Object}
- `signature` {string | Buffer | TypedArray | DataView}
- `signatureFormat` {string}
- Returns: {boolean} `true` or `false` depending on the validity of the
signature for the data and public key.
Verifies the provided data using the given `object` and `signature`.
The `object` argument can be either a string containing a PEM encoded object,
@ -1257,9 +1271,6 @@ If a `signatureFormat` is specified, the `signature` is expected to be a
string; otherwise `signature` is expected to be a [`Buffer`][],
`TypedArray`, or `DataView`.
Returns `true` or `false` depending on the validity of the signature for
the data and public key.
The `verify` object can not be used again after `verify.verify()` has been
called. Multiple calls to `verify.verify()` will result in an error being
thrown.
@ -1270,10 +1281,9 @@ thrown.
<!-- YAML
added: v6.3.0
-->
Returns an object containing commonly used constants for crypto and security
related operations. The specific constants currently defined are described in
[Crypto Constants][].
- Returns: {Object} An object containing commonly used constants for crypto and
security related operations. The specific constants currently defined are
described in [Crypto Constants][].
### crypto.DEFAULT_ENCODING
<!-- YAML
@ -1315,6 +1325,7 @@ deprecated: REPLACEME
- `algorithm` {string}
- `password` {string | Buffer | TypedArray | DataView}
- `options` {Object} [`stream.transform` options][]
- Returns: {Cipher}
Creates and returns a `Cipher` object that uses the given `algorithm` and
`password`.
@ -1361,8 +1372,11 @@ changes:
- `key` {string | Buffer | TypedArray | DataView}
- `iv` {string | Buffer | TypedArray | DataView}
- `options` {Object} [`stream.transform` options][]
- Returns: {Cipher}
Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
initialization vector (`iv`).
The `options` argument controls stream behavior and is optional except when a
cipher in CCM mode is used (e.g. `'aes-128-ccm'`). In that case, the
`authTagLength` option is required and specifies the length of the
@ -1413,6 +1427,7 @@ deprecated: REPLACEME
- `algorithm` {string}
- `password` {string | Buffer | TypedArray | DataView}
- `options` {Object} [`stream.transform` options][]
- Returns: {Decipher}
Creates and returns a `Decipher` object that uses the given `algorithm` and
`password` (key).
@ -1447,6 +1462,7 @@ changes:
- `key` {string | Buffer | TypedArray | DataView}
- `iv` {string | Buffer | TypedArray | DataView}
- `options` {Object} [`stream.transform` options][]
- Returns: {Decipher}
Creates and returns a `Decipher` object that uses the given `algorithm`, `key`
and initialization vector (`iv`).
@ -1538,6 +1554,7 @@ added: v0.1.92
-->
- `algorithm` {string}
- `options` {Object} [`stream.transform` options][]
- Returns: {Hash}
Creates and returns a `Hash` object that can be used to generate hash digests
using the given `algorithm`. Optional `options` argument controls stream
@ -1575,6 +1592,7 @@ added: v0.1.94
- `algorithm` {string}
- `key` {string | Buffer | TypedArray | DataView}
- `options` {Object} [`stream.transform` options][]
- Returns: {Hmac}
Creates and returns an `Hmac` object that uses the given `algorithm` and `key`.
Optional `options` argument controls stream behavior.
@ -1612,6 +1630,7 @@ added: v0.1.92
-->
- `algorithm` {string}
- `options` {Object} [`stream.Writable` options][]
- Returns: {Sign}
Creates and returns a `Sign` object that uses the given `algorithm`.
Use [`crypto.getHashes()`][] to obtain an array of names of the available
@ -1624,6 +1643,7 @@ added: v0.1.92
-->
- `algorithm` {string}
- `options` {Object} [`stream.Writable` options][]
- Returns: {Verify}
Creates and returns a `Verify` object that uses the given algorithm.
Use [`crypto.getHashes()`][] to obtain an array of names of the available
@ -1634,8 +1654,8 @@ signing algorithms. Optional `options` argument controls the
<!-- YAML
added: v0.9.3
-->
Returns an array with the names of the supported cipher algorithms.
- Returns: {string[]} An array with the names of the supported cipher
algorithms.
Example:
@ -1648,8 +1668,7 @@ console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...]
<!-- YAML
added: v2.3.0
-->
Returns an array with the names of the supported elliptic curves.
- Returns: {string[]} An array with the names of the supported elliptic curves.
Example:
@ -1663,6 +1682,7 @@ console.log(curves); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...]
added: v0.7.5
-->
- `groupName` {string}
- Returns: {Object}
Creates a predefined `DiffieHellman` key exchange object. The
supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in
@ -1696,17 +1716,15 @@ console.log(aliceSecret === bobSecret);
<!-- YAML
added: REPLACEME
-->
Returns `true` if and only if a FIPS compliant crypto provider is
- Returns: {boolean} `true` if and only if a FIPS compliant crypto provider is
currently in use.
### crypto.getHashes()
<!-- YAML
added: v0.9.3
-->
Returns an array of the names of the supported hash algorithms,
such as `RSA-SHA256`.
- Returns: {string[]} An array of the names of the supported hash algorithms,
such as `'RSA-SHA256'`.
Example:
@ -1807,6 +1825,7 @@ changes:
- `iterations` {number}
- `keylen` {number}
- `digest` {string}
- Returns: {Buffer}
Provides a synchronous Password-Based Key Derivation Function 2 (PBKDF2)
implementation. A selected HMAC digest algorithm specified by `digest` is
@ -1938,6 +1957,7 @@ changes:
- `callback` {Function}
- `err` {Error}
- `buf` {Buffer}
- Returns: {Buffer} if the `callback` function is not provided.
Generates cryptographically strong pseudo-random data. The `size` argument
is a number indicating the number of bytes to generate.
@ -1994,11 +2014,10 @@ changes:
* `buffer` {Buffer|TypedArray|DataView} Must be supplied.
* `offset` {number} **Default:** `0`
* `size` {number} **Default:** `buffer.length - offset`
* Returns: {Buffer}
Synchronous version of [`crypto.randomFill()`][].
Returns `buffer`
```js
const buf = Buffer.alloc(10);
console.log(crypto.randomFillSync(buf).toString('hex'));
@ -2138,6 +2157,7 @@ added: v6.6.0
-->
- `a` {Buffer | TypedArray | DataView}
- `b` {Buffer | TypedArray | DataView}
- Returns: {boolean}
This function is based on a constant-time algorithm.
Returns true if `a` is equal to `b`, without leaking timing information that

View File

@ -40,6 +40,12 @@ const customTypesMap = {
'cluster.Worker': 'cluster.html#cluster_class_worker',
'Cipher': 'crypto.html#crypto_class_cipher',
'Decipher': 'crypto.html#crypto_class_decipher',
'Hash': 'crypto.html#crypto_class_hash',
'Hmac': 'crypto.html#crypto_class_hmac',
'Sign': 'crypto.html#crypto_class_sign',
'Verify': 'crypto.html#crypto_class_verify',
'crypto.constants': 'crypto.html#crypto_crypto_constants_1',
'dgram.Socket': 'dgram.html#dgram_class_dgram_socket',