Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add caveats section in the doc of crypto #3479

Closed
wants to merge 7 commits into from
Closed

Add caveats section in the doc of crypto #3479

Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e4ef21e
doc: add caveats of algs and key size in crypto
Jul 27, 2015
875f6ab
change "more than" to "at least"
thinred Jul 27, 2015
3db5f4f
update getDiffieHellman docs
thinred Jul 27, 2015
bbe1076
docs: remove md5 and sha1 in crypto example
Jul 27, 2015
220a635
sha1 -> sha265
thinred Jul 27, 2015
a152cd9
revise the doc according to jasnell's comments
Oct 22, 2015
db5b6e2
revise the doc according to 2nd jasnell's comments
Oct 22, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 35 additions & 15 deletions doc/api/crypto.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,18 +97,18 @@ Creates and returns a hash object, a cryptographic hash with the given
algorithm which can be used to generate hash digests.

`algorithm` is dependent on the available algorithms supported by the
version of OpenSSL on the platform. Examples are `'sha1'`, `'md5'`,
`'sha256'`, `'sha512'`, etc. On recent releases, `openssl
version of OpenSSL on the platform. Examples are `'sha256'`,
`'sha512'`, etc. On recent releases, `openssl
list-message-digest-algorithms` will display the available digest
algorithms.

Example: this program that takes the sha1 sum of a file
Example: this program that takes the sha256 sum of a file

var filename = process.argv[2];
var crypto = require('crypto');
var fs = require('fs');

var shasum = crypto.createHash('sha1');
var shasum = crypto.createHash('sha256');

var s = fs.ReadStream(filename);
s.on('data', function(d) {
Expand Down Expand Up @@ -511,21 +511,21 @@ 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][], but see [Caveats](#crypto_caveats)) 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"but will not allow changing the keys" (replace to change with changing)

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.

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();
Expand Down Expand Up @@ -768,6 +768,25 @@ default, set the `crypto.DEFAULT_ENCODING` field to 'binary'. Note
that new programs will probably expect buffers, so only use this as a
temporary measure.

## Caveats

The crypto module still supports some algorithms which are already
compromised. And the API also allows to use ciphers and hashes with a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"And the API also allows the use of ciphers and hashes with a" (replace to with the)

small key size that are considered to be too weak for safe use.

Users should take full responsibility for selecting the crypto
algorithm and key size according to their security requirements.

The following descriptions only show some recommendations to use
crypto module. See [NIST SP 800-131A] for details.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps something like, "Based on the recommendations of [NIST SP 800-131A]:" instead?

- MD5 and SHA-1 are no longer acceptable where collision resistance is
required such as digital signatures.
- The key used with RSA, DSA and DH algorithms is recommended to have
at least 2048 bits and that of the curve of ECDSA and ECDH at least
224 bits, to be safe to use for several years.
- The DH groups of `modp1`, `modp2` and `modp5` have a key size
smaller than 2048 bits and are not recommended.

[createCipher()]: #crypto_crypto_createcipher_algorithm_password
[createCipheriv()]: #crypto_crypto_createcipheriv_algorithm_key_iv
Expand All @@ -779,3 +798,4 @@ temporary measure.
[RFC 3526]: http://www.rfc-editor.org/rfc/rfc3526.txt
[crypto.pbkdf2]: #crypto_crypto_pbkdf2_password_salt_iterations_keylen_digest_callback
[EVP_BytesToKey]: https://www.openssl.org/docs/crypto/EVP_BytesToKey.html
[NIST SP 800-131A]: http://csrc.nist.gov/publications/nistpubs/800-131A/sp800-131A.pdf