{"record":{"id":"e27c5985b6ddeb27","repo":"yiisoft/yii2","slug":"encryption-requires-the-openssl-php-extension","errorCode":null,"errorMessage":"Encryption requires the OpenSSL PHP extension","messagePattern":"Encryption requires the OpenSSL PHP extension","errorType":"exception","errorClass":"InvalidConfigException","httpStatus":null,"severity":"error","filePath":"framework/base/Security.php","lineNumber":202,"sourceCode":"\n    /**\n     * Encrypts data.\n     *\n     * @param string $data data to be encrypted\n     * @param bool $passwordBased set true to use password-based key derivation\n     * @param string $secret the encryption password or key\n     * @param string|null $info context/application specific information, e.g. a user ID\n     * See [RFC 5869 Section 3.2](https://tools.ietf.org/html/rfc5869#section-3.2) for more details.\n     *\n     * @return string the encrypted data as byte string\n     * @throws InvalidConfigException on OpenSSL not loaded\n     * @throws Exception on OpenSSL error\n     * @see decrypt()\n     */\n    protected function encrypt($data, $passwordBased, $secret, $info)\n    {\n        if (!extension_loaded('openssl')) {\n            throw new InvalidConfigException('Encryption requires the OpenSSL PHP extension');\n        }\n        if (!isset($this->allowedCiphers[$this->cipher][0], $this->allowedCiphers[$this->cipher][1])) {\n            throw new InvalidConfigException($this->cipher . ' is not an allowed cipher');\n        }\n\n        list($blockSize, $keySize) = $this->allowedCiphers[$this->cipher];\n\n        $keySalt = $this->generateRandomKey($keySize);\n        if ($passwordBased) {\n            $key = $this->pbkdf2($this->kdfHash, $secret, $keySalt, $this->derivationIterations, $keySize);\n        } else {\n            $key = $this->hkdf($this->kdfHash, $secret, $keySalt, $info, $keySize);\n        }\n\n        $iv = $this->generateRandomKey($blockSize);\n\n        $encrypted = openssl_encrypt($data, $this->cipher, $key, OPENSSL_RAW_DATA, $iv);\n        if ($encrypted === false) {","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/yiisoft/yii2/blob/66f00d18a29b520f85e8e8f1e32d1e7e7b556cac/framework/base/Security.php#L184-L220","documentation":"yii\\base\\Security::encrypt() — the shared engine behind encryptByKey() and encryptByPassword() — refuses to run without the OpenSSL PHP extension because the AES-CBC pipeline needs openssl_encrypt/openssl_decrypt plus authenticated encryption. The InvalidConfigException fires before any key derivation or cipher validation, so this is purely an environment problem, not a data or key problem.","triggerScenarios":"Calling encryptByKey()/encryptByPassword() on a runtime where ext-openssl is absent or disabled: official php:8.x-cli images built without it, Alpine splits (php83-openssl not installed), extension commented out in php.ini, or minimal custom builds.","commonSituations":"Works on the dev machine (bundled OpenSSL) but fails in slim Docker/Alpine images; hosting tiers without the extension; upgraded base images dropping it; CI matrices missing the package.","solutions":["Install/enable the extension in the failing runtime: docker-php-ext-install openssl in Docker builds, apk add php83-openssl on Alpine, apt install php-openssl on Debian, or uncomment extension=openssl in php.ini","Confirm with php -m | grep openssl inside the exact runtime that throws (CLI vs FPM vs worker container can differ)","Declare the requirement in composer.json ('require': {'ext-openssl': '*'}) so installs fail early on bad environments","Where encryption is unavailable, degrade explicitly (skip and queue the operation) instead of swallowing the exception"],"exampleFix":"# before: Dockerfile\nFROM php:8.3-cli\n# ext-openssl missing → encryptByKey() throws InvalidConfigException\n\n# after\nFROM php:8.3-cli\nRUN docker-php-ext-install openssl","handlingStrategy":"validation","validationCode":"if (!extension_loaded('openssl')) {\n    throw new \\RuntimeException('Encryption features require ext-openssl');\n}\n$ciphertext = Yii::$app->security->encryptByKey($data, $key);","typeGuard":null,"tryCatchPattern":"try {\n    $ct = Yii::$app->security->encryptByKey($data, $key);\n} catch (\\yii\\base\\InvalidConfigException $e) {\n    // environment misconfiguration — surface it, never retry\n    \\Yii::error($e->getMessage(), 'security');\n}","preventionTips":["Require ext-openssl in composer.json so broken environments fail at install time","Assert php -m includes openssl in CI and container healthchecks","Exercise encryption paths in the same image used for production"],"tags":["php","yii2","security","encryption","openssl","php-extension"],"backgroundTag":"missing-php-extension","analyzedSha":"66f00d18a29b520f85e8e8f1e32d1e7e7b556cac","analyzedAt":"2026-08-17T05:17:23.470Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}