# HG changeset patch
# Parent  811620fb1450acd8c287cf6551df0cf5d172439e
Issue #27292: Add warning that os.urandom() may be insecure

diff -r 811620fb1450 Doc/library/os.rst
--- a/Doc/library/os.rst	Thu Jun 16 04:11:00 2016 +0000
+++ b/Doc/library/os.rst	Thu Jun 16 10:27:35 2016 +0000
@@ -3803,27 +3803,38 @@
 
 .. function:: urandom(n)
 
-   Return a string of *n* random bytes suitable for cryptographic use.
+   Return a string of *n* random bytes.  Depending on the platform,
+   this may be suitable for cryptographic use.
 
    This function returns random bytes from an OS-specific randomness source.  The
-   returned data should be unpredictable enough for cryptographic applications,
+   returned data may be unpredictable enough for cryptographic applications,
    though its exact quality depends on the OS implementation.
 
-   On Linux, ``getrandom()`` syscall is used if available and the urandom
+   On Windows, ``CryptGenRandom()`` is used.  On other platforms, OpenBSD
+   5.6's ``getentropy()`` syscall is used if available. Otherwise, Linux
+   3.17's ``getrandom()`` syscall may be used if available and the urandom
    entropy pool is initialized (``getrandom()`` does not block).
-   On a Unix-like system this will query ``/dev/urandom``. On Windows, it
-   will use ``CryptGenRandom()``.  If a randomness source is not found,
-   :exc:`NotImplementedError` will be raised.
+   If ``getrandom()`` cannot be used, ``/dev/urandom``
+   is queried.  If a randomness source is not found,
+   :exc:`NotImplementedError` is raised.
 
    For an easy-to-use interface to the random number generator
    provided by your platform, please see :class:`random.SystemRandom`.
 
+   .. warning::
+      On some platforms, the bytes returned may not be cryptographically
+      secure.  In particular, this can happen on Linux if the OS has
+      not gathered enough entropy since it has booted up.  The bytes
+      may appear random, but could in fact be predictable.
+
+      On other platforms, including some FreeBSD and OpenBSD systems,
+      :func:`os.urandom` may block until the OS has gathered
+      sufficient entropy.
+
    .. versionchanged:: 3.5.2
-      On Linux, if ``getrandom()`` blocks (the urandom entropy pool is not
+      If ``getrandom()`` blocks (the urandom entropy pool is not
       initialized yet), fall back on reading ``/dev/urandom``.
 
    .. versionchanged:: 3.5
-      On Linux 3.17 and newer, the ``getrandom()`` syscall is now used
-      when available.  On OpenBSD 5.6 and newer, the C ``getentropy()``
-      function is now used. These functions avoid the usage of an internal file
-      descriptor.
+      The ``getrandom()`` and ``getentropy()`` syscalls are now used.
+      These functions avoid the usage of an internal file descriptor.
diff -r 811620fb1450 Modules/posixmodule.c
--- a/Modules/posixmodule.c	Thu Jun 16 04:11:00 2016 +0000
+++ b/Modules/posixmodule.c	Thu Jun 16 10:27:35 2016 +0000
@@ -11083,7 +11083,8 @@
     size: Py_ssize_t
     /
 
-Return a bytes object containing random bytes suitable for cryptographic use.
+Return a bytes object containing random bytes.  Depending on the platform,
+this may be suitable for cryptographic use.
 [clinic start generated code]*/
 
 static PyObject *