Text of peps.python.org › pep-0522 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 522 – Allow BlockingIOError in security sensitive APIs | peps.python.org

PEP 522 – Allow BlockingIOError in security sensitive APIs PEP 522 – Allow BlockingIOError in security sensitive APIs Author : Alyssa Coghlan <ncoghlan at gmail.com>, Nathaniel J. Smith <njs at pobox.com> Status : Rejected Type : Standards Track Requires : 506 Created : 16-Jun-2016 Python-Version : 3.6 Resolution : Security-SIG message Table of Contents Abstract Relationship with other PEPs PEP Rejection Changes independent of this PEP Proposal Changing os.urandom() on platforms with the getrandom() system call Adding secrets.wait_for_system_rng() Limitations on scope Rationale Ensuring the secrets module implicitly blocks when needed Raising BlockingIOError in os.urandom() on Linux Making secrets.wait_for_system_rng() public Backwards Compatibility Impact Assessment Unaffected Applications Affected security sensitive applications Affected non-security sensitive applications Additional Background Why propose this now?

The cross-platform behaviour of os.urandom() Problems with the behaviour of /dev/urandom on Linux Consequences of getrandom() availability for Python References Copyright Abstract A number of APIs in the standard library that return random values nominally suitable for use in security sensitive operations currently have an obscure operating system dependent failure mode that allows them to return values that are not, in fact, suitable for such operations.

This is due to some operating system kernels (most notably the Linux kernel) permitting reads from /dev/urandom before the system random number generator is fully initialized, whereas most other operating systems will implicitly block on such reads until the random number generator is ready. For the lower level os.urandom and random.SystemRandom APIs, this PEP proposes changing such failures in Python 3.6 from the current silent, hard to detect, and hard to debug, errors to easily detected and debugged errors by raising BlockingIOError with a suitable error message, allowing developers the opportunity to unambiguously specify their preferred approach for handling the situation.

For the new high level secrets API, it proposes to block implicitly if needed whenever random number is generated by that module, as well as to expose a new secrets.wait_for_system_rng() function to allow code otherwise using the low level APIs to explicitly wait for the system random number generator to be available. This change will impact any operating system that offers the getrandom() system call, regardless of whether the default behaviour of the /dev/urandom device is to return potentially predictable results when the system random number generator is not ready (e.g.

Linux, NetBSD) or to block (e.g. FreeBSD, Solaris, Illumos). Operating systems that prevent execution of userspace code prior to the initialization of the system random number generator, or do not offer the getrandom() syscall, will be entirely unaffected by the proposed change (e.g. Windows, Mac OS X, OpenBSD). The new exception or the blocking behaviour in the secrets module would potentially be encountered in the following situations: Python code calling these APIs during Linux system initialization Python code running on improperly initialized Linux systems (e.g. embedded hardware without adequate sources of entropy to seed the system random number generator, or Linux VMs that aren’t configured to accept entropy from the VM host) Relationship with other PEPs This PEP depends on the Accepted PEP 506 , which adds the secrets module.

This PEP competes with Victor Stinner’s PEP 524 , which proposes to make os.urandom itself implicitly block when the system RNG is not ready. PEP Rejection For the reference implementation, Guido rejected this PEP in favour of the unconditional implicit blocking proposal in PEP 524 (which brings CPython’s behaviour on Linux into line with its behaviour on other operating systems). This means any further discussion of appropriate default behaviour for os.urandom() in system Python installations in Linux distributions should take place on the respective distro mailing lists, rather than on the upstream CPython mailing lists.

Changes independent of this PEP CPython interpreter initialization and random module initialization have already been updated to gracefully fall back to alternative seeding options if the system random number generator is not ready. This PEP does not compete with the proposal in PEP 524 to add an os.getrandom() API to expose the getrandom syscall on platforms that offer it. There is sufficient motive for adding that API in the os module’s role as a thin wrapper around potentially platform dependent operating system features that it can be added regardless of what happens to the default behaviour of os.urandom() on these systems.

Proposal Changing os.urandom() on platforms with the getrandom() system call This PEP proposes that in Python 3.6+, os.urandom() be updated to call the getrandom() syscall in non-blocking mode if available and raise BlockingIOError: system random number generator is not ready; see secrets.token_bytes() if the kernel reports that the call would block. This behaviour will then propagate through to the existing random.SystemRandom , which provides a relatively thin wrapper around os.urandom() that matches the random.Random() API.

However, the new secrets module introduced by PEP 506 will be updated to catch the new exception and implicitly wait for the system random number generator if the exception is ever encountered. In all cases, as soon as a call to one of these security sensitive APIs succeeds, all future calls to these APIs in that process will succeed without blocking (once the operating system random number generator is ready after system boot, it remains ready).

On Linux and NetBSD, this will replace the previous behaviour of returning potentially predictable results read from /dev/urandom . On FreeBSD, Solaris, and Illumos, this will replace the previous behaviour of implicitly blocking until the system random number generator is ready. However, it is not clear if these operating systems actually allow userspace code (and hence Python) to run before the system random number generator is ready.

Note that in all cases, if calling the underlying getrandom() API reports ENOSYS rather than returning a successful response or reporting EAGAIN , CPython will continue to fall back to reading from /dev/urandom directly. Adding secrets.wait_for_system_rng() A new exception shouldn’t be added without a straightforward recommendation for how to resolve that error when encountered (however rare encountering the new error is expected to be in practice).

For security sensitive code that actually does need to use the lower level interfaces to the system random number generator (rather than the new secrets module), and does receive live bug reports indicating this is a real problem for the userbase of that particular application rather than a theoretical one, this PEP’s recommendation will be to add the following snippet (directly or indirectly) to the __main__ module: import secrets secrets . wait_for_system_rng () Or, if compatibility with versions prior to Python 3.6 is needed: try : import secrets except ImportError : pass else : secrets . wait_for_system_rng () Within the secrets module itself, this will then be used in token_bytes() to block implicitly if the new exception is encountered: def token_bytes ( nbytes = None ): if nbytes is None : nbytes = DEFAULT_ENTROPY try : result = os . urandom ( nbytes ) except BlockingIOError : wait_for_system_rng () result = os . urandom ( nbytes ) return result Other parts of the module will then be updated to use token_bytes() as their basic random number generation building block, rather than calling os.urandom() directly.

Application frameworks covering use cases where access to the system random number generator is almost certain to be needed (e.g. web frameworks) may choose to incorporate a call to secrets.wait_f

The rest of this page is on the live site.