fix phplist 500 error due to random_compat

By Michael Altfield, on August 25th, 2018

So you've just done a fresh install of phplist, but when you attempt to load it in your browser, you get a 500 Internal Server Error. But the error log is empty! It's possible that phplist is suppressing the errors produced by the included library random_compat. This blog post will describe this possible issue, and how to resolve it.

Update 2018-09-17: Sam Tuke (CEO at phplist) just merged my PR (#403) to make this issue more shallow. As a result, it should die() with a very specific error message when a call to "random_bytes(1)" throws an exception. The solution is the same (spoiler: install libsodium), but you probably won't get a generic 500 error in newer versions of phplist.

Next to MailChimp, phplist is one of the most popular tools for managing email list campaigns. I recently installed phplist on our CentOS7 server at Open Source Ecology, but I spent most of the day digging through the source code trying to debug this issue. Hence, I'm documenting this issue here to help save you that effort 😉

Step 1: Stop phplist from suppressing errors in your logs

At the time of writing, phplist's documentation on troubleshooting phplist leaves much to be desired. For example, it doesn't mention that phplist will, by default, suppress exceptions thrown from being written to your error logs--making troubleshooting extremely difficult. As a first step to debugging phplist errors, you probably want to change this behavior! To do so, change "error_reporting(0)" to "error_reporting(1)" in 'lists/admin/init.php' and 'lists/admin/index.php' as I described here.

ⓘ Note: It goes without saying that you should have "display_errors = Off" set in your '/etc/php.ini' file. This setting does not suppress errors from being sent to your log files (why would you want to do that?). It prevents them from being sent to your client's web browsers.

After doing so, you may see something similar to the following pop-up in your error log:

[Thu Aug 23 00:06:29.560157 2018] [:error] [pid 17617] [client 127.0.0.1:51262] PHP Fatal error:  Uncaught exception 'Exception' with message 'There is no suitable CSPRNG installed on your system' in /var/www/html/phplist.opensourceecology.org/public_html/lists/admin/inc/random_compat/random.php:204\nStack trace:\n#0 /var/www/html/phplist.opensourceecology.org/public_html/lists/admin/defaultconfig.php(3): random_bytes(10)\n#1 /var/www/html/phplist.opensourceecology.org/public_html/lists/admin/index.php(103): require_once('/var/www/html/p...')\n#2 {main}\n  thrown in /var/www/html/phplist.opensourceecology.org/public_html/lists/admin/inc/random_compat/random.php on line 204

If you see the exception thrown by '/lists/admin/inc/random_compat/random.php' about the CSPRNG, then keep reading. Else, you may just have the typical issues with your '.htaccess' files.

About the error

phplist includes a library 'random_compat' from 'paragonie' for generating cryptographically secure pseudo random numbers (CSPRNG). This library employs a number of techniques to generate CSPRNs, as documented in their source code:

     * In order of preference:
     *   1. Use libsodium if available.
     *   2. fread() /dev/urandom if available (never on Windows)
     *   3. mcrypt_create_iv($bytes, MCRYPT_DEV_URANDOM)
     *   4. COM('CAPICOM.Utilities.1')->GetRandom()

ⓘ Note: for more information on this, you can read through random_compat's RATIONALE.md.

If you've encountered this issue, it's probably because you use open_basedir in your '/etc/php.ini' file to whitelist which directories in which php is allowed to execute. Good for you! However, that means that php can't access '/dev/urandom'.

The official response from the maintainers (see issue #99 of the random_compat repo on github) is to simply add '/dev/urandom' to open_basedir. Personally, that didn't seem like the wisest option..

Alternately, you can install libsodium, which is indeed the #1 preferred source of entropy by the random_compat library.