From 2193e707ee6e8eb82c22242c734918fd6049ede4 Mon Sep 17 00:00:00 2001 From: Bill Automata Date: Tue, 1 Mar 2016 09:26:32 -0800 Subject: [PATCH 1/3] crypto docs updated to use good defaults [Diffie-Hellman](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange#Cryptographic_explanation) keys are composed of a `generator` a `prime` a `secret_key` and the `public_key` resulting from the math operation: ``` (generator ^ secret_key) mod prime = public_key ``` Diffie-Hellman keypairs will compute a matching shared secret if and only if the generator and prime match for both recipients. The generator is usually **2** and the prime is what is called a [Safe Prime](https://en.wikipedia.org/wiki/Safe_prime). Usually this matching is accomplished by using [standard published groups](http://tools.ietf.org/html/rfc3526). We expose access those groups with the `crypto.getDiffieHellman` function. `createDiffieHellman` is trickier to use. The original example had the user creating 11 bit keys, and creating random groups of generators and primes. 11 bit keys are very very small, can be cracked by a single person on a single sheet of paper. A byproduct of using such small keys were that it was a high likelihood that two calls of `createDiffieHellman(11)` would result in using the same 11 bit safe prime. The original example code would fail when the safe primes generated at 11 bit lengths did not match for alice and bob. If you want to use your own generated safe `prime` then the proper use of `createDiffieHellman` is to pass the `prime` and `generator` to the recipient's constructor, so that when they compute the shared secret their `prime` and `generator` match, which is fundamental to the algorithm. --- doc/api/crypto.markdown | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index dd31ae7ac3b92b..3b6acefc1bc0a8 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -325,19 +325,20 @@ const crypto = require('crypto'); const assert = require('assert'); // Generate Alice's keys... -const alice = crypto.createDiffieHellman(11); +const alice = crypto.createDiffieHellman(2048); const alice_key = alice.generateKeys(); // Generate Bob's keys... -const bob = crypto.createDiffieHellman(11); +const bob = crypto.createDiffieHellman(alice.getPrime(), 'binary', alice.getGenerator(), 'binary'); const bob_key = bob.generateKeys(); // Exchange and generate the secret... const alice_secret = alice.computeSecret(bob_key); const bob_secret = bob.computeSecret(alice_key); -assert(alice_secret, bob_secret); - // OK +// OK +assert.equal(alice_secret.toString('hex'), bob_secret.toString('hex')); + ``` ### diffieHellman.computeSecret(other_public_key[, input_encoding][, output_encoding]) From f3a94e32788d905ab867f0cfc6d62de64fd45f25 Mon Sep 17 00:00:00 2001 From: Bill Automata Date: Tue, 1 Mar 2016 09:35:56 -0800 Subject: [PATCH 2/3] removed unnecessary encodings --- doc/api/crypto.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index 3b6acefc1bc0a8..8445339e6c0c54 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -329,7 +329,7 @@ const alice = crypto.createDiffieHellman(2048); const alice_key = alice.generateKeys(); // Generate Bob's keys... -const bob = crypto.createDiffieHellman(alice.getPrime(), 'binary', alice.getGenerator(), 'binary'); +const bob = crypto.createDiffieHellman(alice.getPrime(), alice.getGenerator()); const bob_key = bob.generateKeys(); // Exchange and generate the secret... From 0fb7df73e214101c6f759079b9443474dc0f9ca0 Mon Sep 17 00:00:00 2001 From: Bill Automata Date: Tue, 1 Mar 2016 09:54:42 -0800 Subject: [PATCH 3/3] removed newline --- doc/api/crypto.markdown | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown index 8445339e6c0c54..d6deed7d924759 100644 --- a/doc/api/crypto.markdown +++ b/doc/api/crypto.markdown @@ -338,7 +338,6 @@ const bob_secret = bob.computeSecret(alice_key); // OK assert.equal(alice_secret.toString('hex'), bob_secret.toString('hex')); - ``` ### diffieHellman.computeSecret(other_public_key[, input_encoding][, output_encoding])