From 634bedcd6fd6c3ee9d9824b230ec5ea560338f1f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= <tniessen@tnie.de>
Date: Tue, 26 Jan 2021 20:40:57 +0100
Subject: [PATCH] doc,test: fix prime generation description
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous description incorrectly explained the behavior of
options.add and options.rem for primes that are not safe.

PR-URL: https://github.com/nodejs/node/pull/37085
Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
---
 doc/api/crypto.md                  | 42 ++++++++++++++++++------------
 test/parallel/test-crypto-prime.js | 24 +++++++++++++++++
 2 files changed, 50 insertions(+), 16 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 4afb6d27d38706..b6daac6aaae246 100644
--- 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
index 4d26c46eb5411a..27f34adea36d9e 100644
--- 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'