phalcon/cphalcon · error · InvalidAuthTagLength

The auth tag length must be between 4 and 16 bytes.

Error message

The auth tag length must be between 4 and 16 bytes.

What it means

Crypt::setAuthTagLength() validates that the GCM/CCM authentication tag length is between 4 and 16 bytes (inclusive) before storing it; anything outside that range throws InvalidAuthTagLength. The tag length later feeds openssl_encrypt's $tag argument in AEAD modes, and OpenSSL rejects tags outside 4..16, so Phalcon fails fast at configuration time.

Source

Thrown at phalcon/Encryption/Crypt.zep:545

     * @return CryptInterface
     */
    public function setAuthTag(string tag) -> <CryptInterface>
    {
        let this->authTag = tag;

        return this;
    }

    /**
     * @param int $length
     *
     * @return CryptInterface
     * @throws InvalidAuthTagLength
     */
    public function setAuthTagLength(int length) -> <CryptInterface>
    {
        if length < 4 || length > 16 {
            throw new InvalidAuthTagLength();
        }

        let this->authTagLength = length;

        return this;
    }

    /**
     * Sets the cipher algorithm for data encryption and decryption.
     *
     * @param string $cipher
     *
     * @return CryptInterface
     * @throws Exception
     */
    public function setCipher(string cipher) -> <CryptInterface>
    {
        this->checkCipherHashIsAvailable(cipher, "cipher");

View on GitHub (pinned to b7419de9cd)

Solutions

1. Use a value in 4..16; 16 is the GCM default and recommended - if you never call setAuthTagLength you get the safe default.
2. If interoperating with an external system, check what tag length IT writes and clamp to 4..16 or switch that system's expectations.
3. Set it once in the DI/Crypt setup, not per request, and add an assertion around config-driven values.

Example fix

// before
$crypt->setAuthTagLength(32); // 32-byte MAC habit -> throws

// after
$crypt->setAuthTagLength(16); // GCM default, strongest allowed

$tagLength = (int) $config->path('encryption.authTagLength', 16);
if ($tagLength < 4 || $tagLength > 16) {
    throw new \InvalidArgumentException('authTagLength must be within 4..16');
}
$crypt->setAuthTagLength($tagLength);

function isValidAuthTagLength(mixed $length): bool
{
    return is_int($length) && $length >= 4 && $length <= 16;
}

try {
    $crypt->setAuthTagLength($tagLength);
} catch (\Phalcon\Encryption\Crypt\Exception\InvalidAuthTagLength $e) {
    $crypt->setAuthTagLength(16); // safe default, then log the config error
    $logger->error('Invalid authTagLength in config, fell back to 16');
}

When it happens

Trigger: Calling $crypt->setAuthTagLength(3), setAuthTagLength(17), or larger values like 32 (a common mistake - 32 is valid for HMAC digests, not for GCM tags); also passing 0 hoping to disable tags.

Common situations: Copying a key-size or hash-length constant (16/32/64) into the tag-length setting; trying to match another system's token format that stores 32-byte MACs; tuning performance by shrinking the tag below the 4-byte floor.

Related errors

• Auth data must be provided when using AEAD mode
• Decryption key cannot be empty
• Encryption key cannot be empty
• Invalid module definition for module '{moduleName}': The mod
• Invalid module definition for module '{moduleName}': The mod

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/f02b74dd1273ea0c. Report an issue: GitHub.