From 0bd3da15a080e9b363b37da53ca6cad4088d4aff Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Fri, 6 Apr 2018 18:28:20 +0300 Subject: [PATCH] doc: add and unify return statements in crypto.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Conform return statements to the style guide and tool parsers. Also bring back a description fragment that seems to be erroneously deleted in https://github.com/nodejs/node/commit/1e07acd476309e7ddc4981160b89731b61a31179 PR-URL: https://github.com/nodejs/node/pull/19853 Reviewed-By: James M Snell Reviewed-By: Rich Trott Reviewed-By: Luigi Pinca Reviewed-By: Gibson Fahnestock Reviewed-By: Trivikram Kamat Reviewed-By: Ruben Bridgewater Reviewed-By: Tobias Nießen --- doc/api/crypto.md | 132 ++++++++++++++++++++++----------------- tools/doc/type-parser.js | 6 ++ 2 files changed, 82 insertions(+), 56 deletions(-) diff --git a/doc/api/crypto.md b/doc/api/crypto.md index f00adf02ec835f..0b199c74317de5 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -56,8 +56,8 @@ 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 -includes a public key and a challenge. +- Returns: {Buffer} The challenge component of the `spkac` data structure, which + includes a public key and a challenge. ```js const { Certificate } = require('crypto'); @@ -73,8 +73,8 @@ added: v9.0.0 --> - `spkac` {string | Buffer | TypedArray | DataView} - `encoding` {string} -- Returns {Buffer} The public key component of the `spkac` data structure, -which includes a public key and a challenge. +- Returns: {Buffer} The public key component of the `spkac` data structure, + which includes a public key and a challenge. ```js const { Certificate } = require('crypto'); @@ -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,8 +122,8 @@ const cert2 = crypto.Certificate(); added: v0.11.8 --> - `spkac` {string | Buffer | TypedArray | DataView} -- Returns {Buffer} The challenge component of the `spkac` data structure, which -includes a public key and a challenge. +- Returns: {Buffer} The challenge component of the `spkac` data structure, which + includes a public key and a challenge. ```js const cert = require('crypto').Certificate(); @@ -138,8 +138,8 @@ 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, -which includes a public key and a challenge. +- Returns: {Buffer} The public key component of the `spkac` data structure, + which includes a public key and a challenge. ```js const cert = require('crypto').Certificate(); @@ -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()`][]. - -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]) - `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. - -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 - `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 - -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', ...] - -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); - -Returns `true` if and only if a FIPS compliant crypto provider is -currently in use. +- Returns: {boolean} `true` if and only if a FIPS compliant crypto provider is + currently in use. ### crypto.getHashes() - -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 diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js index 1cbd1a5552b00d..5386039b36709f 100644 --- a/tools/doc/type-parser.js +++ b/tools/doc/type-parser.js @@ -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',