doc,test: fix prime generation description

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

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'