From 66d5133edf0a3ce47b7a3fe7ceb2383ca8d8b48b Mon Sep 17 00:00:00 2001
From: Tomasz Buchert <tomasz@buchert.pl>
Date: Thu, 18 Jun 2015 01:39:48 +0200
Subject: [PATCH] crypto: update docs

---
 doc/api/crypto.markdown | 30 +++++++++++++++++++-----------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown
index f0a867360cf..2f835740c1c 100644
--- a/doc/api/crypto.markdown
+++ b/doc/api/crypto.markdown
@@ -502,21 +502,29 @@ expected.
 ## crypto.getDiffieHellman(group_name)
 
 Creates a predefined Diffie-Hellman key exchange object.  The
-supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in [RFC
-2412][]) and `'modp14'`, `'modp15'`, `'modp16'`, `'modp17'`,
-`'modp18'` (defined in [RFC 3526][]).  The returned object mimics the
-interface of objects created by [crypto.createDiffieHellman()][]
-above, but will not allow to change the keys (with
-[diffieHellman.setPublicKey()][] for example).  The advantage of using
-this routine is that the parties don't have to generate nor exchange
-group modulus beforehand, saving both processor and communication
-time.
+supported groups are: `'modp1'`, `'modp2'`, `'modp5'` (defined in
+[RFC 2412][]) and `'modp14'`, `'modp15'`, `'modp16'`, `'modp17'`,
+`'modp18'` (defined in [RFC 3526][]).
+
+The returned object mimics the interface of objects created by
+[crypto.createDiffieHellman()][] above, but will not allow to change
+the keys (with [diffieHellman.setPublicKey()][] for example).  The
+advantage of using this routine is that the parties do not have to
+generate nor exchange group modulus beforehand, saving both processor
+and communication time.
+
+The groups `'modp1'`, `'modp2'` and `'modp5'` (i.e., the groups with
+size smaller than 2048 bits) are considered **deprecated** and should
+not be used in new code. Moreover, the use of the `'modp1'` group must
+be explicitly enabled: either via `'--enable-small-groups'` switch to
+node, or by setting the `'ENABLE_SMALL_GROUPS'` environment variable
+to a non-empty value.
 
 Example (obtaining a shared secret):
 
     var crypto = require('crypto');
-    var alice = crypto.getDiffieHellman('modp5');
-    var bob = crypto.getDiffieHellman('modp5');
+    var alice = crypto.getDiffieHellman('modp14');
+    var bob = crypto.getDiffieHellman('modp14');
 
     alice.generateKeys();
     bob.generateKeys();