doc: crypto docs updated to use good defaults for createDiffieHellman #5505
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
[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.
| const alice_key = alice.generateKeys(); | ||
|
|
||
| // Generate Bob's keys... | ||
| const bob = crypto.createDiffieHellman(11); | ||
| const bob = crypto.createDiffieHellman(alice.getPrime(), 'binary', alice.getGenerator(), 'binary'); |
There was a problem hiding this comment.
The 'binary' arguments are not necessary here and can be removed since the prime and generator are Buffers.
|
LGTM. /cc @nodejs/crypto |
| // OK | ||
| // OK | ||
| assert.equal(alice_secret.toString('hex'), bob_secret.toString('hex')); | ||
|
|
|
One nit, otherwise LGTM! Thank you! |
|
LGTM |
billautomata
changed the title
jasnell
pushed a commit
that referenced
this pull request
Mar 21, 2016
[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>
|
Landed in e136c17 |
Fishrock123
pushed a commit
that referenced
this pull request
Mar 22, 2016
[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>
MylesBorins
pushed a commit
that referenced
this pull request
Mar 30, 2016
[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>
MylesBorins
pushed a commit
that referenced
this pull request
Mar 30, 2016
[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>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Pull Request check-list
make -j8 test(UNIX) orvcbuild test nosign(Windows) pass withthis change (including linting)?
test (or a benchmark) included?
existing APIs, or introduces new ones)?
NOTE: these things are not required to open a PR and can be done
afterwards / while the PR is open.
Affected core subsystem(s)
createDiffieHellmanDescription of change
Diffie-Hellman keys are composed of a
generatoraprimeasecret_keyand thepublic_keyresulting from the math operation: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.
Usually this matching is accomplished by using standard published groups. We expose access those groups with the
crypto.getDiffieHellmanfunction.createDiffieHellmanis 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 ofcreateDiffieHellman(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
primethen the proper use ofcreateDiffieHellmanis to pass theprimeandgeneratorto the recipient's constructor, so that when they compute the shared secret theirprimeandgeneratormatch, which is fundamental to the algorithm.