yiisoft/yii2 · error · InvalidArgumentException

Invalid parameters to hash_hkdf()

Error message

Invalid parameters to hash_hkdf()

What it means

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.

Source

Thrown at framework/base/Security.php:303

     * Derives a key from the given input key using the standard HKDF algorithm.
     * Implements HKDF specified in [RFC 5869](https://tools.ietf.org/html/rfc5869).
     * Recommend use one of the SHA-2 hash algorithms: sha224, sha256, sha384 or sha512.
     * @param string $algo a hash algorithm supported by `hash_hmac()`, e.g. 'SHA-256'
     * @param string $inputKey the source key
     * @param string|null $salt the random salt
     * @param string|null $info optional info to bind the derived key material to application-
     * and context-specific information, e.g. a user ID or API version, see
     * [RFC 5869](https://tools.ietf.org/html/rfc5869)
     * @param int $length length of the output key in bytes. If 0, the output key is
     * the length of the hash algorithm output.
     * @throws InvalidArgumentException when HMAC generation fails.
     * @return string the derived key
     */
    public function hkdf($algo, $inputKey, $salt = null, $info = null, $length = 0)
    {
        $outputKey = hash_hkdf((string)$algo, (string)$inputKey, $length, (string)$info, (string)$salt);
        if ($outputKey === false) {
            throw new InvalidArgumentException('Invalid parameters to hash_hkdf()');
        }

        return $outputKey;
    }

    /**
     * Derives a key from the given password using the standard PBKDF2 algorithm.
     * Implements HKDF2 specified in [RFC 2898](https://datatracker.ietf.org/doc/html/rfc2898#section-5.2)
     * Recommend use one of the SHA-2 hash algorithms: sha224, sha256, sha384 or sha512.
     * @param string $algo a hash algorithm supported by `hash_hmac()`, e.g. 'SHA-256'
     * @param string $password the source password
     * @param string $salt the random salt
     * @param int $iterations the number of iterations of the hash algorithm. Set as high as
     * possible to hinder dictionary password attacks.
     * @param int $length length of the output key in bytes. If 0, the output key is
     * the length of the hash algorithm output.
     * @return string the derived key
     * @throws InvalidArgumentException when hash generation fails due to invalid params given.

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Use an algorithm name exactly as listed by hash_algos() (normally 'sha256')
2. Keep $length within 255 × digest size, or pass 0 to request the full digest length
3. Validate kdfHash against hash_algos() once at bootstrap and fail the deploy on mismatch
4. After fixing, re-encrypt affected data — keys derived under a different algorithm cannot decrypt old ciphertexts

Example fix

// before
$security->hkdf('sha245', $key, $salt, null, 32); // typo → hash_hkdf() false → exception

// after
$security->hkdf('sha256', $key, $salt, null, 32);

if (!in_array($algo, hash_algos(), true)) {
    throw new \RuntimeException("Unknown hash algorithm: $algo");
}
$okm = Yii::$app->security->hkdf($algo, $inputKey, $salt, $info, $length);

try {
    $derived = Yii::$app->security->hkdf('sha256', $key, $salt, null, 32);
} catch (\InvalidArgumentException $e) {
    // invalid algo or out-of-range length — fix the parameters, do not retry
}

When it happens

Trigger: '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.

Common situations: Hand-edited security config; switching to exotic hashes for compliance without checking the runtime; shared config across PHP builds that differ in compiled algorithms.

Related errors

• Invalid parameters to hash_pbkdf2()
• Failed to generate HMAC with hash algorithm: {macHash}
• Failed to generate HMAC with hash algorithm:
• Encryption requires the OpenSSL PHP extension
• {cipher} is not an allowed cipher

AI-assisted analysis of yiisoft/yii2@66f00d18a2 (2026-08-17). Data as JSON: /api/errors/795d789078672f6d. Report an issue: GitHub.