diff --git a/doc/api/crypto.md b/doc/api/crypto.md index e43f3fa5dafc43..a703552d7a15ff 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1961,6 +1961,48 @@ is currently in use. Setting to true requires a FIPS build of Node.js. This property is deprecated. Please use `crypto.setFips()` and `crypto.getFips()` instead. +### `crypto.checkPrime(candidate[, options, [callback]])` + + +* `candidate` {ArrayBuffer|SharedArrayBuffer|TypedArray|Buffer|DataView|bigint} + A possible prime encoded as a sequence of big endian octets of arbitrary + length. +* `options` {Object} + * `checks` {number} The number of primality checks to perform. When the + value is `0` (zero), a number of checks is used that yields a false + positive rate of at most 2^-64 for random input. Care must be used + when selecting a number of checks. Refer to the OpenSSL documentation + for the [`BN_is_prime_ex`][] function `nchecks` options for more details. + **Defaults**: `0` +* `callback` {Function} + * `err` {Error} Set to an {Error} object if an error occured during check. + * `result` {boolean} `true` if the candidate is a prime with an error + probability less than `0.25^options.checks`. + +Checks the primality of the `candidate`. + +### `crypto.checkPrimeSync(candidate[, options])` + + +* `candidate` {ArrayBuffer|SharedArrayBuffer|TypedArray|Buffer|DataView|bigint} + A possible prime encoded as a sequence of big endian octets of arbitrary + length. +* `options` {Object} + * `checks` {number} The number of primality checks to perform. When the + value is `0` (zero), a number of checks is used that yields a false + positive rate of at most 2^-64 for random input. Care must be used + when selecting a number of checks. Refer to the OpenSSL documentation + for the [`BN_is_prime_ex`][] function `nchecks` options for more details. + **Defaults**: `0` +* Returns: {boolean} `true` if the candidate is a prime with an error + probability less than `0.25^options.checks`. + +Checks the primality of the `candidate`. + ### `crypto.createCipher(algorithm, password[, options])` + +* `size` {number} The size (in bits) of the prime to generate. +* `options` {Object} + * `add` {ArrayBuffer|SharedArrayBuffer|TypedArray|Buffer|DataView} + * `rem` {ArrayBuffer|SharedArrayBuffer|TypedArray|Buffer|DataView} + * `safe` {boolean} + * `bigint` {boolean} When `true`, the generated prime is returned + as a `bigint`. +* `callback` {Function} + * `err` {Error} + * `prime` {ArrayBuffer|bigint} + +Generates a pseudo-random prime of `size` bits. + +If `options.safe` is true, the prime will be a safe prime -- that is, +`(prime - 1) / 2` will also be a prime. + +If `options.add` and `options.rem` are set, the prime will satisfy the +condition that prime % add = rem. The `options.rem` is ignored if +`options.add` is not given. If `options.safe` is `true`, `options.add` +is given, and `options.rem` is `undefined`, then th prime generated +will satisfy the condition `prime % add = 3`. Otherwise if `options.safe` +is `false` and `options.rem` is `undefined`, `options.add` will be +ignored. + +The prime is encoded as a big-endian sequence of octets in an {ArrayBuffer}. + +### `crypto.randomPrimeSync(size[, options])` + + +* `size` {number} The size (in bits) of the prime to generate. +* `options` {Object} + * `add` {ArrayBuffer|SharedArrayBuffer|TypedArray|Buffer|DataView} + * `rem` {ArrayBuffer|SharedArrayBuffer|TypedArray|Buffer|DataView} + * `safe` {boolean} + * `bigint` {boolean} When `true`, the generated prime is returned + as a `bigint`. +* Returns: {ArrayBuffer|bigint} + +Generates a pseudo-random prime of `size` bits. + +If `options.safe` is true, the prime will be a safe prime -- that is, +`(prime - 1)` / 2 will also be a prime. + +If `options.add` and `options.rem` are set, the prime will satisfy the +condition that prime % add = rem. The `options.rem` is ignored if +`options.add` is not given. If `options.safe` is `true`, `options.add` +is given, and `options.rem` is `undefined`, then th prime generated +will satisfy the condition `prime % add = 3`. Otherwise if `options.safe` +is `false` and `options.rem` is `undefined`, `options.add` will be +ignored. + +The prime is encoded as a big-endian sequence of octets in an {ArrayBuffer}. + ### `crypto.randomUUID([options])`