PHP RFC: Random Functions Throwing Exceptions in PHP 7
- Version: 1.0
- Date: 2015-08-22
- Author: Anthony Ferrara ircmaxell@php.net, Aaron Piotrowski aaron@icicle.io
- Status: Accepted
- First Published at: http://wiki.php.net/rfc/random-function-exceptions
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
TypeErrorif zend_parse_parameters fails. - Throws
Exceptionif generating sufficiently random data fails. - Throws
Errorif$min > $max.
random_bytes()
- Throws
TypeErrorif zend_parse_parameters fails. - Throws
Exceptionif generating sufficiently random data fails. - Throws
Errorif$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
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.