Skip to content

Commit

Permalink
doc: update crypto docs to use good defaults
Browse files Browse the repository at this point in the history
[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.

PR-URL: #5505
Reviewed-By: Brian White <mscdex@mscdex.net>
Reviewed-By: Fedor Indutny <fedor.indutny@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
  • Loading branch information
billautomata authored and Myles Borins committed Mar 30, 2016
1 parent af23632 commit f4ac952
Showing 1 changed file with 4 additions and 4 deletions.
8 changes: 4 additions & 4 deletions doc/api/crypto.markdown
Original file line number Diff line number Diff line change
@@ -325,19 +325,19 @@ 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(), alice.getGenerator());
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])

0 comments on commit f4ac952

Please sign in to comment.