From f16510fd32a511e1e9a89f649e0df561988e3140 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 18 Jan 2021 23:03:58 -0800 Subject: [PATCH] crypto: add randomPrime/randomPrimeSync/checkPrime APIs for generating and checking pseudo-random primes Signed-off-by: James M Snell --- doc/api/crypto.md | 99 +++++++++++ lib/crypto.js | 8 + lib/internal/crypto/random.js | 151 ++++++++++++++++ src/async_wrap.h | 2 + src/crypto/crypto_random.cc | 167 ++++++++++++++++++ src/crypto/crypto_random.h | 73 ++++++++ src/crypto/crypto_util.h | 2 + test/parallel/test-crypto-prime.js | 164 +++++++++++++++++ test/sequential/test-async-wrap-getasyncid.js | 2 + 9 files changed, 668 insertions(+) create mode 100644 test/parallel/test-crypto-prime.js diff --git a/doc/api/crypto.md b/doc/api/crypto.md index e43f3fa5dafc43..1cef435c67232a 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} 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} 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} +* `callback` {Function} + * `err` {Error} + * `prime` {ArrayBuffer} + +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} +* Returns: {ArrayBuffer} + +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])`