doc,test: fix prime generation description

The previous description incorrectly explained the behavior of options.add and options.rem for primes that are not safe. PR-URL: #37085 Reviewed-By: Juan José Arboleda <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]>
nodejs · Feb 2, 2021 · 634bedc · 634bedc
1 parent 6940252
commit 634bedc
Show file tree

Hide file tree

Showing 2 changed files with 50 additions and 16 deletions.
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
@@ -2757,13 +2757,18 @@ 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 the 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 `options.add` and `options.rem` parameters can be used to enforce additional
+requirements, e.g., for Diffie-Hellman:
+
+* If `options.add` and `options.rem` are both set, the prime will satisfy the
+  condition that `prime % add = rem`.
+* If only `options.add` is set and `options.safe` is not `true`, the prime will
+  satisfy the condition that `prime % add = 1`.
+* If only `options.add` is set and `options.safe` is set to `true`, the prime
+  will instead satisfy the condition that `prime % add = 3`. This is necessary
+  because `prime % add = 1` for `options.add > 2` would contradict the condition
+  enforced by `options.safe`.
+* `options.rem` is ignored if `options.add` is not given.
 
 Both `options.add` and `options.rem` must be encoded as big-endian sequences
 if given as an `ArrayBuffer`, `SharedArrayBuffer`, `TypedArray`, `Buffer`, or
@@ -2790,15 +2795,20 @@ added: REPLACEME
 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 the 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.
+`(prime - 1) / 2` will also be a prime.
+
+The `options.add` and `options.rem` parameters can be used to enforce additional
+requirements, e.g., for Diffie-Hellman:
+
+* If `options.add` and `options.rem` are both set, the prime will satisfy the
+  condition that `prime % add = rem`.
+* If only `options.add` is set and `options.safe` is not `true`, the prime will
+  satisfy the condition that `prime % add = 1`.
+* If only `options.add` is set and `options.safe` is set to `true`, the prime
+  will instead satisfy the condition that `prime % add = 3`. This is necessary
+  because `prime % add = 1` for `options.add > 2` would contradict the condition
+  enforced by `options.safe`.
+* `options.rem` is ignored if `options.add` is not given.
 
 Both `options.add` and `options.rem` must be encoded as big-endian sequences
 if given as an `ArrayBuffer`, `SharedArrayBuffer`, `TypedArray`, `Buffer`, or

diff --git a/test/parallel/test-crypto-prime.js b/test/parallel/test-crypto-prime.js
@@ -135,6 +135,30 @@ generatePrime(
   assert.strictEqual(val % add, rem);
 }
 
+{
+  // The behavior when specifying only add without rem should depend on the
+  // safe option.
+
+  if (process.versions.openssl >= '1.1.1f') {
+    generatePrime(128, {
+      bigint: true,
+      add: 5n
+    }, common.mustSucceed((prime) => {
+      assert(checkPrimeSync(prime));
+      assert.strictEqual(prime % 5n, 1n);
+    }));
+
+    generatePrime(128, {
+      bigint: true,
+      safe: true,
+      add: 5n
+    }, common.mustSucceed((prime) => {
+      assert(checkPrimeSync(prime));
+      assert.strictEqual(prime % 5n, 3n);
+    }));
+  }
+}
+
 [1, 'hello', {}, []].forEach((i) => {
   assert.throws(() => checkPrime(i), {
     code: 'ERR_INVALID_ARG_TYPE'