rfc:easy_userland_csprng

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
rfc:easy_userland_csprng [2015/02/24 22:54] – Added BC info. Updated patch link to point to PR. sammykrfc:easy_userland_csprng [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 1: Line 1:
 ====== PHP RFC: Easy User-land CSPRNG ====== ====== PHP RFC: Easy User-land CSPRNG ======
-  * Version: 0.4+  * Version: 0.5
   * Date: 2015-02-20   * Date: 2015-02-20
   * Author: Sammy Kaye Powers <me@sammyk.me> & Leigh <leigh@php.net>   * Author: Sammy Kaye Powers <me@sammyk.me> & Leigh <leigh@php.net>
-  * Status: Under Discussion+  * Status: Implemented (in PHP 7.0)
   * First Published at: http://wiki.php.net/rfc/easy_userland_csprng   * First Published at: http://wiki.php.net/rfc/easy_userland_csprng
  
Line 11: Line 11:
  
 ==== The Problem ==== ==== The Problem ====
-By default PHP does not provide an easy mechanism for accessing cryptographically strong random numbers in user-land. Users have a few options like ''openssl_random_pseudo_bytes()'', ''mcrypt_create_iv()'' or directly opening ''/dev/*random'' devices to obtain high quality pseudo-random bytes, but unfortunately system support for these functions and extensions varies and each come with their own set of problems+By default PHP does not provide an easy mechanism for accessing cryptographically strong random numbers in user-land. Users have a few options like ''openssl_random_pseudo_bytes()'', ''mcrypt_create_iv()'' or directly opening ''/dev/*random'' devices to obtain high quality pseudo-random bytes, but unfortunately system support for these functions and extensions varies between platforms and each come with their own set of problems
  
-  * ''mcrypt_create_iv()'' has no dependency on [[http://mcrypt.sourceforge.net/|MCrypt lib]]. Users are forced to include an entire library for no reason.+  * The ''mcrypt_create_iv()'' function has no dependency on [[http://mcrypt.sourceforge.net/|MCrypt lib]] yet it requires the MCrypt extension to be installed before it can be used. Users are forced to include an entire library for no reason.
   * ''openssl_random_pseudo_bytes()'' is provided by the [[https://www.openssl.org/|OpenSSL lib]]. This function comes with a ''$crypto_strong'' the meaning of which may just confuse users.   * ''openssl_random_pseudo_bytes()'' is provided by the [[https://www.openssl.org/|OpenSSL lib]]. This function comes with a ''$crypto_strong'' the meaning of which may just confuse users.
-  * Falling back to ''/dev/urandom'' is OS-specific and can fail when ''open_basedir'' is set. +  * Falling back to ''/dev/urandom'' is OS-specific.
- +
-See the [[https://github.com/facebook/facebook-php-sdk-v4/tree/master/src/Facebook/PseudoRandomString|Facebook PHP SDK's implementation of a CSPRNG]] in PHP to understand how much code is needed in user-land to simply generate cryptographically secure pseudo-random bytes.+
  
 In addition users may attempt to generate their own streams of random bytes relying on ''rand()'' or ''mt_rand()'', and this is something we absolutely want to avoid. In addition users may attempt to generate their own streams of random bytes relying on ''rand()'' or ''mt_rand()'', and this is something we absolutely want to avoid.
  
 ===== Proposal ===== ===== Proposal =====
-There should be a user-land API to easily return an arbitrary length of cryptographically secure pseudo-random bytes directly and work on any supported server configuration or OS.+There should be a user-land API to easily return an arbitrary length of cryptographically secure pseudo-random bytes directly and work on any supported platform.
  
-The initial proposal is to add **two** user-land functions that return the bytes as binary and integer.+The initial proposal is to add **two** user-land functions that return the bytes as binary and integer. Arbitrary length strings of random bytes are important for salts, keys and initialisation vectors. Integers based on CS random are important for applications where unbiased results are critical (i.e. shuffling a Poker deck).
  
 Signatures: Signatures:
 <code> <code>
 random_bytes(int length); random_bytes(int length);
-random_int([int min = ~PHP_INT_MAX [, int max = PHP_INT_MAX]]);+random_int(int min, int max);
 </code> </code>
  
Line 41: Line 39:
 The sources of random used are as follows: The sources of random used are as follows:
   * On windows ''CryptGenRandom'' is used exclusively   * On windows ''CryptGenRandom'' is used exclusively
-  * ''arc4random_buf()'' is used if present for fd-less random+  * ''arc4random_buf()'' is used if it is available (generally BSD specific)
   * ''/dev/arandom'' is used where available   * ''/dev/arandom'' is used where available
   * ''/dev/urandom'' is used where none of the above is available   * ''/dev/urandom'' is used where none of the above is available
 +  * An error is thrown in the event that a sufficient source of randomness is unavailable.
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
-Any user-land code that defines a ''random_bytes()'' or ''random_int()'' function would generate a fatal error. +Any user-land code that defines a ''random_bytes()'' or ''random_int()'' function would generate a fatal error, however it is likely that these functions provide the same or similar functionality as desired.
- +
-<code> +
-Fatal error: Cannot redeclare random_bytes() in %s on line %d +
-</code>+
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
Line 82: Line 77:
    * Deprecate ''mcrypt_create_iv()''    * Deprecate ''mcrypt_create_iv()''
    * Improve ''session_id'' randomness generation    * Improve ''session_id'' randomness generation
-   * Detect LibreSSL portable for arc4random() on Linux +   * Detect LibreSSL-portable for arc4random() on Linux
-   * Improve fd-less random for chroot environments with our own arc4random and the linux ''getrandom'' syscall +
-   * Add complimentary easy-use and secure by default cryptography functions+
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
-The current WIP patch can be found here: https://github.com/php/php-src/pull/1119+The current patch can be found here: https://github.com/php/php-src/pull/1119 
 + 
 +===== Proposed Voting Choices ===== 
 + 
 +The voting choices are yes (in favor for accepting this RFC for PHP 7) or no (against it). 
 + 
 +===== Vote ===== 
 + 
 +Vote starts on March 14th, and will end two weeks later, on March 28th. 
 + 
 +This RFC requires a 2/3 majority.
  
-===== References ===== +<doodle title="Reliable user-land CSPRNG" auth="SammyK" voteType="single" closed="true"> 
-None so far.+   * Yes 
 +   * No 
 +</doodle>
  
-===== Rejected Features ===== 
-None so far. 
  
 ===== Changelog ===== ===== Changelog =====
 +   * 0.5: Updated the function header for random_int() to reflect all args as required. - SammyK 
    * 0.4: Added BC info. Updated patch link to point to PR. - SammyK    * 0.4: Added BC info. Updated patch link to point to PR. - SammyK
    * 0.3: Changed ''-PHP_INT_MAX'' to ''~PHP_INT_MAX'' (thanks [[https://twitter.com/trevorsuarez/status/570308776185733122|@trevorsuarez]]) - SammyK    * 0.3: Changed ''-PHP_INT_MAX'' to ''~PHP_INT_MAX'' (thanks [[https://twitter.com/trevorsuarez/status/570308776185733122|@trevorsuarez]]) - SammyK
rfc/easy_userland_csprng.1424818443.txt.gz · Last modified: 2017/09/22 13:28 (external edit)