crypto.randomBytes documentation needs improvement

[brendanashworth]

The crypto.randomBytes documentation is quite confusing on whether or not the function throws on a lack of entropy. The code shows that it does, but the note below says that it does not. I'm currently under the impression that it does not throw on low entropy, so this needs to be fixed. Here is how it looks now:

crypto.randomBytes(size[, callback])

Generates cryptographically strong pseudo-random data. Usage:

// async
crypto.randomBytes(256, function(ex, buf) {
  if (ex) throw ex;
  console.log('Have %d bytes of random data: %s', buf.length, buf);
});
// sync
try {
  var buf = crypto.randomBytes(256);
  console.log('Have %d bytes of random data: %s', buf.length, buf);
} catch (ex) {
  // handle error
  // most likely, entropy sources are drained
}

NOTE: This will block if there is insufficient entropy, although it should normally never take longer than a few milliseconds. The only time when this may conceivably block is right after boot, when the whole system is still low on entropy.

Refs to: #3073 (comment) and following discussion, e5e5980, f68a116, and RAND_bytes() docs. Also #813.

[JungMinu]

@brendanashworth I will take care of this :)

[brendanashworth]

ref: #3087