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 f0c4add61a19c0f2868565207c5740375fb9d286..52419a1f2553885080004a6269fdbdedf84a6a61 100644 (file)
--- a/Doc/library/random.rst
+++ b/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:
 

diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index a528a03f985f9927ff9724cb393e10647c3ac941..295d007f067be6f1a7e36195a647b3fedb6edddb 100644 (file)
--- a/Doc/library/ssl.rst
+++ b/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()