From 19fb53c1195653e87b9197211015c624960c7b95 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Tue, 24 May 2011 21:32:40 +0200 Subject: 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 | 6 ++++++ Doc/library/ssl.rst | 10 ++++++++++ 2 files changed, 16 insertions(+) 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 @@ 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 a528a03..295d007 100644 --- 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 + `_, + 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() -- cgit v0.12