yiisoft/yii2 · error · InvalidArgumentException

Invalid parameters to hash_pbkdf2()

Error message

Invalid parameters to hash_pbkdf2()

What it means

Security::pbkdf2() wraps hash_pbkdf2() and maps a false return to InvalidArgumentException. false indicates a bad parameter combination: an algorithm unknown to the hash extension, a non-positive iteration count, or a negative output length. For the Security component this usually means kdfHash or derivationIterations (used for password-based encryption) were misconfigured.

Source

Thrown at framework/base/Security.php:327

    /**
     * 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.
     */
    public function pbkdf2($algo, $password, $salt, $iterations, $length = 0)
    {
        $outputKey = hash_pbkdf2($algo, $password, $salt, $iterations, $length, true);
        if ($outputKey === false) {
            throw new InvalidArgumentException('Invalid parameters to hash_pbkdf2()');
        }

        return $outputKey;
    }

    /**
     * Prefixes data with a keyed hash value so that it can later be detected if it is tampered.
     * There is no need to hash inputs or outputs of [[encryptByKey()]] or [[encryptByPassword()]]
     * as those methods perform the task.
     * @param string $data the data to be protected
     * @param string $key the secret key to be used for generating hash. Should be a secure
     * cryptographic key.
     * @param bool $rawHash whether the generated hash value is in raw binary format. If false, lowercase
     * hex digits will be generated.
     * @return string the data prefixed with the keyed hash
     * @throws InvalidConfigException when HMAC generation fails.
     * @see validateData()
     * @see generateRandomKey()

View on GitHub (pinned to 66f00d18a2)

Solutions

1. Set derivationIterations to a positive integer (framework default 100000)
2. Correct kdfHash to a hash_algos() entry such as 'sha256'
3. Normalize env-derived values before assigning: max(1, (int) ($envValue ?: 100000))
4. Add a bootstrap check that kdfHash is a known algorithm and iterations >= 1

Example fix

// before
'components' => [
    'security' => [
        'derivationIterations' => (int) getenv('KDF_ITERATIONS'), // missing env → 0
    ],
],

// after
'components' => [
    'security' => [
        'derivationIterations' => max(1, (int) (getenv('KDF_ITERATIONS') ?: 100000)),
    ],
],

if (!in_array($algo, hash_algos(), true) || $iterations < 1 || $length < 0) {
    throw new \RuntimeException('Invalid PBKDF2 parameters');
}
$dk = Yii::$app->security->pbkdf2($algo, $password, $salt, $iterations, $length);

try {
    $dk = Yii::$app->security->pbkdf2('sha256', $password, $salt, 100000, 32);
} catch (\InvalidArgumentException $e) {
    // bad algo/iterations/length — correct inputs instead of retrying
}

When it happens

Trigger: 'derivationIterations' => 0 from casting a missing environment variable; kdfHash typo; calling pbkdf2() directly with $iterations = 0 or a negative $length; note that on newer PHP versions some invalid inputs raise ValueError directly from hash_pbkdf2() instead of surfacing this wrapper message.

Common situations: Environment-driven security settings where a missing var coerces to 0; hardening iterations to values copied between PHP versions; config drift between environments sharing derived-key data.

Related errors

• Invalid parameters to hash_hkdf()
• 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/38f85cf633771881. Report an issue: GitHub.