Random Functions throwing Exceptions View as Markdown

Introduction

Concern has been raised over the way failure is indicated by several functions in the core that are often used for security purposes. These functions may fail open, allowing execution to continue, potentially compromising the security of an application. Failure of these functions is only indicating failure through a return value that may be inappropriate cast and used or requiring further function calls to check for failure. It is far too easy for an uninformed programmer to be unaware of the potential for failure and the consequences of neglecting to check for failure, so it is imperative that these functions fail closed, so execution cannot continue if the error is ignored.

The following functions are addressed by this RFC:

• random_int()
• random_bytes()

An example of a common use of these functions is:

example.php

<?php
$password = "";
for ($i = 0; $i < 10; $i++) {
    $password .= chr(random_int(33, 124));
}
?>

If random_int isn't able to capture enough entropy, it will error. In that case, $password would be 10 null bytes. Without careful error checking this could cause severe security issues. This is not acceptable and this RFC proposes to solve this by making all errors in these functions into exceptions.

Proposal

To fail closed while allowing the error to be handled, it is this RFCs proposal that the functions above throw exceptions upon failure. The specific types of exceptions and conditions from which they are thrown are outlined below.

random_int()

• Throws TypeError if zend_parse_parameters fails.
• Throws Exception if generating sufficiently random data fails.
• Throws Error if $min > $max.

random_bytes()

• Throws TypeError if zend_parse_parameters fails.
• Throws Exception if generating sufficiently random data fails.
• Throws Error if $length <= 0.

Backward Incompatible Changes

random_int() and random_bytes() are new functions to PHP 7, so changes to these functions do not have any backwards compatibility issues.

Proposed PHP Version

PHP 7.0.0

Future Scope

This RFC explicitly does not address how exceptions should be thrown from other core functions. This question will be addressed in a separate RFC. Focus was given to the particular functions in this RFC due to their importance to security applications.

Proposed Voting Choices

• Throw exceptions

Vote

This vote will close on 07:00 UTC on Sunday 06-09-2015

Vote: Should this RFC be accepted for 7.0 — Yes: 28 · No: 2 (closed)

Patches and Tests

Below are implementations of random_int() and random_bytes() which throw exceptions, though not exactly what is outlined above. The pulls will be updated to throw the exceptions described above before merging.

• https://github.com/php/php-src/pull/1397
• https://github.com/php/php-src/pull/1398

References

• Core functions throwing exceptions in PHP7
• Recap - Core functions throwing exceptions in PHP7