Issue #12049: improve RAND_bytes() and RAND_pseudo_bytes() documentation
Add also a security warning in the module random pointing to ssl.RAND_bytes().
diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index f0c4add..52419a1 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -43,6 +43,12 @@
uses the system function :func:`os.urandom` to generate random numbers
from sources provided by the operating system.
+.. warning::
+
+ The generators of the :mod:`random` module should not be used for security
+ purposes, they are not cryptographic. Use :func:`ssl.RAND_bytes` if you
+ require a cryptographically secure pseudorandom number generator.
+
Bookkeeping functions:
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index a528a03..295d007 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -166,6 +166,11 @@
Returns *num* cryptographically strong pseudo-random bytes.
+ Read the Wikipedia article, `Cryptographically secure pseudorandom number
+ generator
+ <http://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator>`_,
+ to get the requirements of a cryptographically generator.
+
.. versionadded:: 3.3
.. function:: RAND_pseudo_bytes(num)
@@ -174,6 +179,11 @@
is_cryptographic is True if the bytes generated are cryptographically
strong.
+ Generated pseudo-random byte sequences will be unique if they are of
+ sufficient length, but are not necessarily unpredictable. They can be used
+ for non-cryptographic purposes and for certain purposes in cryptographic
+ protocols, but usually not for key generation etc.
+
.. versionadded:: 3.3
.. function:: RAND_status()