{"record":{"id":"f02b74dd1273ea0c","repo":"phalcon/cphalcon","slug":"the-auth-tag-length-must-be-between-4-and-16-bytes","errorCode":null,"errorMessage":"The auth tag length must be between 4 and 16 bytes.","messagePattern":"The auth tag length must be between 4 and 16 bytes\\.","errorType":"exception","errorClass":"InvalidAuthTagLength","httpStatus":null,"severity":"error","filePath":"phalcon/Encryption/Crypt.zep","lineNumber":545,"sourceCode":"     * @return CryptInterface\n     */\n    public function setAuthTag(string tag) -> <CryptInterface>\n    {\n        let this->authTag = tag;\n\n        return this;\n    }\n\n    /**\n     * @param int $length\n     *\n     * @return CryptInterface\n     * @throws InvalidAuthTagLength\n     */\n    public function setAuthTagLength(int length) -> <CryptInterface>\n    {\n        if length < 4 || length > 16 {\n            throw new InvalidAuthTagLength();\n        }\n\n        let this->authTagLength = length;\n\n        return this;\n    }\n\n    /**\n     * Sets the cipher algorithm for data encryption and decryption.\n     *\n     * @param string $cipher\n     *\n     * @return CryptInterface\n     * @throws Exception\n     */\n    public function setCipher(string cipher) -> <CryptInterface>\n    {\n        this->checkCipherHashIsAvailable(cipher, \"cipher\");","sourceCodeStart":527,"sourceCodeEnd":563,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Encryption/Crypt.zep#L527-L563","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a value in 4..16; 16 is the GCM default and recommended - if you never call setAuthTagLength you get the safe default.","If interoperating with an external system, check what tag length IT writes and clamp to 4..16 or switch that system's expectations.","Set it once in the DI/Crypt setup, not per request, and add an assertion around config-driven values."],"exampleFix":"// before\n$crypt->setAuthTagLength(32); // 32-byte MAC habit -> throws\n\n// after\n$crypt->setAuthTagLength(16); // GCM default, strongest allowed","handlingStrategy":"validation","validationCode":"$tagLength = (int) $config->path('encryption.authTagLength', 16);\nif ($tagLength < 4 || $tagLength > 16) {\n    throw new \\InvalidArgumentException('authTagLength must be within 4..16');\n}\n$crypt->setAuthTagLength($tagLength);","typeGuard":"function isValidAuthTagLength(mixed $length): bool\n{\n    return is_int($length) && $length >= 4 && $length <= 16;\n}","tryCatchPattern":"try {\n    $crypt->setAuthTagLength($tagLength);\n} catch (\\Phalcon\\Encryption\\Crypt\\Exception\\InvalidAuthTagLength $e) {\n    $crypt->setAuthTagLength(16); // safe default, then log the config error\n    $logger->error('Invalid authTagLength in config, fell back to 16');\n}","preventionTips":["Omit setAuthTagLength entirely to keep the secure default of 16.","Validate config-driven tag lengths at boot with the same 4..16 rule.","Do not reuse key-size or hash-length constants for tag length."],"tags":["phalcon","crypt","gcm","aead","auth-tag","configuration"],"backgroundTag":"invalid-aead-tag-length","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}