Issue #12049: improve RAND_bytes() and RAND_pseudo_bytes() documentation

Add also a security warning in the module random pointing to ssl.RAND_bytes().

Doc/library/random.rst

@@ -43,6 +43,12 @@ The :mod:`random` module also provides the :class:`SystemRandom` class which
 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:
 

Doc/library/ssl.rst

@@ -166,6 +166,11 @@ Random generation
 
    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 @@ Random generation
    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()