From 5865442a0215fc5cfc7dcd2510f3d1bd01b98515 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= <tniessen@tnie.de>
Date: Sat, 10 Sep 2022 21:42:25 +0000
Subject: [PATCH] doc: deprecate modp1, modp2, and modp5 groups

These MODP groups should not be used by new applications, and existing
applications should attempt to migrate to stronger groups (or different
key exchange mechanisms).

Some applications still rely on these particular groups, so Node.js will
likely maintain support, directly or indirectly, for the foreseeable
future.

Refs: https://github.com/nodejs/node/issues/44539
---
 doc/api/crypto.md        | 11 ++++++++---
 doc/api/deprecations.md  | 19 +++++++++++++++++++
 doc/api_assets/style.css |  3 ++-
 3 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index ad1b5a768a4128..0213f5dcb8f299 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1185,15 +1185,20 @@ const dh = createDiffieHellmanGroup('modp16');
 
 The following groups are supported:
 
-* `'modp1'` (768 bits, [RFC 2409][] Section 6.1)
-* `'modp2'` (1024 bits, [RFC 2409][] Section 6.2)
-* `'modp5'` (1536 bits, [RFC 3526][] Section 2)
 * `'modp14'` (2048 bits, [RFC 3526][] Section 3)
 * `'modp15'` (3072 bits, [RFC 3526][] Section 4)
 * `'modp16'` (4096 bits, [RFC 3526][] Section 5)
 * `'modp17'` (6144 bits, [RFC 3526][] Section 6)
 * `'modp18'` (8192 bits, [RFC 3526][] Section 7)
 
+The following groups are still supported but deprecated (see [Caveats][]):
+
+* `'modp1'` (768 bits, [RFC 2409][] Section 6.1) <span class="deprecated-inline"></span>
+* `'modp2'` (1024 bits, [RFC 2409][] Section 6.2) <span class="deprecated-inline"></span>
+* `'modp5'` (1536 bits, [RFC 3526][] Section 2) <span class="deprecated-inline"></span>
+
+These deprecated groups may be removed in future versions of Node.js.
+
 ## Class: `ECDH`
 
 <!-- YAML
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index d3f3eac9cef122..48645b5102f293 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -3194,9 +3194,28 @@ Type: Documentation-only
 
 The [`--trace-atomics-wait`][] flag is deprecated.
 
+### DEP0166: Weak `DiffieHellmanGroup` instances (`modp1`, `modp2`, `modp5`)
+
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/44588
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+The well-known MODP groups `modp1`, `modp2`, and `modp5` are deprecated because
+they are not considered secure against practical attacks. See
+[RFC 8247 Section 2.4][] for details.
+
+These groups may be removed in future versions of Node.js. Applications that
+rely on these groups should evaluate using stronger MODP groups instead.
+
 [Legacy URL API]: url.md#legacy-url-api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
+[RFC 8247 Section 2.4]: https://www.rfc-editor.org/rfc/rfc8247#section-2.4
 [WHATWG URL API]: url.md#the-whatwg-url-api
 [`"exports"` or `"main"` entry]: packages.md#main-entry-point-export
 [`--pending-deprecation`]: cli.md#--pending-deprecation
diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css
index acab9bfa04858e..4bff9e3299f25f 100644
--- a/doc/api_assets/style.css
+++ b/doc/api_assets/style.css
@@ -598,7 +598,8 @@ hr {
   padding-left: 5rem;
 }
 
-#toc .stability_0::after {
+#toc .stability_0::after,
+.deprecated-inline::after {
   background-color: var(--red2);
   color: var(--white);
   content: "deprecated";