{"record":{"id":"6d7892875559cd98","repo":"paragonie/random_compat","slug":"there-is-no-suitable-csprng-installed-on-your-system","errorCode":null,"errorMessage":"There is no suitable CSPRNG installed on your system","messagePattern":"There is no suitable CSPRNG installed on your system","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"critical","filePath":"lib/random.php","lineNumber":214,"sourceCode":"    }\n\n    /**\n     * throw new Exception\n     */\n    if (!is_callable('random_bytes')) {\n        /**\n         * We don't have any more options, so let's throw an exception right now\n         * and hope the developer won't let it fail silently.\n         *\n         * @param mixed $length\n         * @psalm-suppress InvalidReturnType\n         * @throws Exception\n         * @return string\n         */\n        function random_bytes($length)\n        {\n            unset($length); // Suppress \"variable not used\" warnings.\n            throw new Exception(\n                'There is no suitable CSPRNG installed on your system'\n            );\n            return '';\n        }\n    }\n}\n\nif (!is_callable('random_int')) {\n    require_once $RandomCompatDIR.DIRECTORY_SEPARATOR.'random_int.php';\n}\n\n$RandomCompatDIR = null;\n","sourceCodeStart":196,"sourceCodeEnd":227,"githubUrl":"https://github.com/paragonie/random_compat/blob/b5d188cc9d5e02f94d2c41da23093f1ef557c5b1/lib/random.php#L196-L227","documentation":"This is random_compat's terminal fallback: if the library could not find any cryptographically secure random number generator at load time (no libsodium, no mcrypt, no /dev/urandom, no CAPICOM on Windows, and PHP < 7 without any suitable source), every call to random_bytes() throws this Exception unconditionally.","triggerScenarios":"Calling random_bytes() on a system where no CSPRNG was detected: non-Windows hosts without /dev/urandom (some chroots, restricted containers, OpenBSD in certain modes), Windows without CAPICOM under PHP < 7, or open_basedir/open_basedir-like restrictions blocking /dev/urandom reads.","commonSituations":"Shared hosting with restricted open_basedir, minimal Docker images lacking /dev/urandom mounts, very old PHP 5.x on Windows, or platforms where com_dotnet extension is disabled so CAPICOM is unavailable.","solutions":["Upgrade to PHP 7+ where random_bytes() is native and this polyfill branch never executes.","Ensure /dev/urandom exists and is readable by the PHP process (fix open_basedir, chroot, or container device mounts).","Install/enable paragonie/sodium_compat or the libsodium extension so a userspace/kernel CSPRNG is available.","On Windows with PHP 5.x, enable the com_dotnet extension so CAPICOM can be used as the entropy source."],"exampleFix":"// before (docker run without devices)\n$bytes = random_bytes(32);\n\n// after (docker-compose.yml)\n// services:\n//   app:\n//     devices:\n//       - /dev/urandom:/dev/urandom\n// or upgrade the image to php:7+\n$bytes = random_bytes(32);","handlingStrategy":"try-catch","validationCode":"// capability check at app bootstrap\nif (!function_exists('random_bytes') && !is_readable('/dev/urandom') && !extension_loaded('libsodium')) {\n    error_log('FATAL: no CSPRNG available on this host');\n}","typeGuard":null,"tryCatchPattern":"try {\n    $bytes = random_bytes(32);\n} catch (Exception $e) {\n    // no CSPRNG: fail closed for security-sensitive use\n    throw new RuntimeException('Secure randomness unavailable; cannot continue safely', 0, $e);\n}","preventionTips":["Run on PHP 7+ where random_bytes() is built in","In containers/chroots, verify /dev/urandom is present and readable at deploy time","Install paragonie/sodium_compat as a fallback entropy source","Add a startup health check that calls random_bytes(1) and fails deployment if it throws"],"tags":["php","csprng","environment","missing-dependency","crypto"],"backgroundTag":"missing-dependency","analyzedSha":"b5d188cc9d5e02f94d2c41da23093f1ef557c5b1","analyzedAt":"2026-09-13T16:12:09.755Z","contentChangedAt":"2026-09-13T16:12:09.755Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}