changeset:   70346:ca92fa2fe5c9
user:        Victor Stinner <victor.stinner@haypocalc.com>
date:        Tue May 24 21:32:40 2011 +0200
files:       Doc/library/random.rst Doc/library/ssl.rst
description:
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 -r 0494046d8fdc -r ca92fa2fe5c9 Doc/library/random.rst
--- a/Doc/library/random.rst	Tue May 24 12:51:32 2011 -0500
+++ b/Doc/library/random.rst	Tue May 24 21:32:40 2011 +0200
@@ -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 -r 0494046d8fdc -r ca92fa2fe5c9 Doc/library/ssl.rst
--- a/Doc/library/ssl.rst	Tue May 24 12:51:32 2011 -0500
+++ b/Doc/library/ssl.rst	Tue May 24 21:32:40 2011 +0200
@@ -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()