crypto: `randomBytes` is non-blocking

Add NOTE section in documentation, mentioning that `randomBytes` won't
block when entropy sources are drained.

fix #6372

diff --git a/doc/api/crypto.markdown b/doc/api/crypto.markdown
index e0fe26f..1aba68e 100644 (file)
--- a/doc/api/crypto.markdown
+++ b/doc/api/crypto.markdown
@@ -465,8 +465,14 @@ Generates cryptographically strong pseudo-random data. Usage:
       console.log('Have %d bytes of random data: %s', buf.length, buf);
     } catch (ex) {
       // handle error
+      // most likely, entropy sources are drained
     }
 
+NOTE: Will throw error or invoke callback with error, if there is not enough
+accumulated entropy to generate cryptographically strong data. In other words,
+`crypto.randomBytes` without callback will not block even if all entropy sources
+are drained.
+
 ## crypto.pseudoRandomBytes(size, [callback])
 
 Generates *non*-cryptographically strong pseudo-random data. The data