{"record":{"id":"795d789078672f6d","repo":"yiisoft/yii2","slug":"invalid-parameters-to-hash-hkdf","errorCode":null,"errorMessage":"Invalid parameters to hash_hkdf()","messagePattern":"Invalid parameters to hash_hkdf\\(\\)","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"framework/base/Security.php","lineNumber":303,"sourceCode":"     * Derives a key from the given input key using the standard HKDF algorithm.\n     * Implements HKDF specified in [RFC 5869](https://tools.ietf.org/html/rfc5869).\n     * Recommend use one of the SHA-2 hash algorithms: sha224, sha256, sha384 or sha512.\n     * @param string $algo a hash algorithm supported by `hash_hmac()`, e.g. 'SHA-256'\n     * @param string $inputKey the source key\n     * @param string|null $salt the random salt\n     * @param string|null $info optional info to bind the derived key material to application-\n     * and context-specific information, e.g. a user ID or API version, see\n     * [RFC 5869](https://tools.ietf.org/html/rfc5869)\n     * @param int $length length of the output key in bytes. If 0, the output key is\n     * the length of the hash algorithm output.\n     * @throws InvalidArgumentException when HMAC generation fails.\n     * @return string the derived key\n     */\n    public function hkdf($algo, $inputKey, $salt = null, $info = null, $length = 0)\n    {\n        $outputKey = hash_hkdf((string)$algo, (string)$inputKey, $length, (string)$info, (string)$salt);\n        if ($outputKey === false) {\n            throw new InvalidArgumentException('Invalid parameters to hash_hkdf()');\n        }\n\n        return $outputKey;\n    }\n\n    /**\n     * Derives a key from the given password using the standard PBKDF2 algorithm.\n     * Implements HKDF2 specified in [RFC 2898](https://datatracker.ietf.org/doc/html/rfc2898#section-5.2)\n     * Recommend use one of the SHA-2 hash algorithms: sha224, sha256, sha384 or sha512.\n     * @param string $algo a hash algorithm supported by `hash_hmac()`, e.g. 'SHA-256'\n     * @param string $password the source password\n     * @param string $salt the random salt\n     * @param int $iterations the number of iterations of the hash algorithm. Set as high as\n     * possible to hinder dictionary password attacks.\n     * @param int $length length of the output key in bytes. If 0, the output key is\n     * the length of the hash algorithm output.\n     * @return string the derived key\n     * @throws InvalidArgumentException when hash generation fails due to invalid params given.","sourceCodeStart":285,"sourceCodeEnd":321,"githubUrl":"https://github.com/yiisoft/yii2/blob/66f00d18a29b520f85e8e8f1e32d1e7e7b556cac/framework/base/Security.php#L285-L321","documentation":"Security::hkdf() delegates to PHP's hash_hkdf() and converts a false return into InvalidArgumentException. hash_hkdf() returns false when the algorithm is not registered (typo or not compiled into this PHP) or when the requested length exceeds 255 times the algorithm's digest size. The component drives it with kdfHash for encryptByKey(), so that setting is the usual culprit.","triggerScenarios":"'kdfHash' configured as a name absent from hash_algos() (e.g. 'sha245' typo, or 'sha3-256' on a build without SHA-3); calling hkdf() directly with a $length beyond 255 × digest size; config copied from a system whose hash extension exposes different algorithms.","commonSituations":"Hand-edited security config; switching to exotic hashes for compliance without checking the runtime; shared config across PHP builds that differ in compiled algorithms.","solutions":["Use an algorithm name exactly as listed by hash_algos() (normally 'sha256')","Keep $length within 255 × digest size, or pass 0 to request the full digest length","Validate kdfHash against hash_algos() once at bootstrap and fail the deploy on mismatch","After fixing, re-encrypt affected data — keys derived under a different algorithm cannot decrypt old ciphertexts"],"exampleFix":"// before\n$security->hkdf('sha245', $key, $salt, null, 32); // typo → hash_hkdf() false → exception\n\n// after\n$security->hkdf('sha256', $key, $salt, null, 32);","handlingStrategy":"validation","validationCode":"if (!in_array($algo, hash_algos(), true)) {\n    throw new \\RuntimeException(\"Unknown hash algorithm: $algo\");\n}\n$okm = Yii::$app->security->hkdf($algo, $inputKey, $salt, $info, $length);","typeGuard":null,"tryCatchPattern":"try {\n    $derived = Yii::$app->security->hkdf('sha256', $key, $salt, null, 32);\n} catch (\\InvalidArgumentException $e) {\n    // invalid algo or out-of-range length — fix the parameters, do not retry\n}","preventionTips":["Pick kdfHash from hash_algos() output of the target runtime ('sha256' is universally available)","Keep HKDF length within 255 x digest size or use 0 for the full digest","Validate security component hash settings at bootstrap rather than at first use"],"tags":["php","yii2","security","hkdf","key-derivation","hash"],"backgroundTag":"invalid-kdf-parameters","analyzedSha":"66f00d18a29b520f85e8e8f1e32d1e7e7b556cac","analyzedAt":"2026-08-17T05:17:23.470Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}