{"record":{"id":"ab8823d803363d2a","repo":"phalcon/cphalcon","slug":"auth-data-must-be-provided-when-using-aead-mode","errorCode":null,"errorMessage":"Auth data must be provided when using AEAD mode","messagePattern":"Auth data must be provided when using AEAD mode","errorType":"exception","errorClass":"MissingAuthData","httpStatus":null,"severity":"error","filePath":"phalcon/Encryption/Crypt.zep","lineNumber":895,"sourceCode":"        string mode,\n        string padded,\n        string encryptKey,\n        string iv\n    ) -> string {\n        var authData, authTag, authTagLength, cipher, encrypted;\n\n        let cipher  = this->cipher,\n            authTag = \"\";\n\n        /**\n         * If the mode is \"gcm\" or \"ccm\" and auth data has been passed call it\n         * with that data\n         */\n        if true === this->checkIsMode([\"ccm\", \"gcm\"], mode) {\n            let authData = this->authData;\n\n            if true === empty(authData) {\n                throw new MissingAuthData();\n            }\n\n            let authTag       = this->authTag,\n                authTagLength = this->authTagLength;\n\n            let encrypted = openssl_encrypt(\n                padded,\n                cipher,\n                encryptKey,\n                OPENSSL_RAW_DATA,\n                iv,\n                authTag,\n                authData,\n                authTagLength\n            );\n\n            let this->authTag = authTag;\n        } else {","sourceCodeStart":877,"sourceCodeEnd":913,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Encryption/Crypt.zep#L877-L913","documentation":"For AEAD modes (gcm/ccm) Crypt::encryptGcmCcm() requires associated authentication data: it reads $this->authData (set via setAuthData()) and throws MissingAuthData if it is empty. GCM/CCM distinguish 'additional authenticated data' from the message itself, and Phalcon mandates it rather than defaulting to empty, so encrypted payloads always carry an AEAD context.","triggerScenarios":"setCipher('aes-256-gcm') followed by encrypt() without ever calling setAuthData('...'); or setAuthData('') (empty string counts as empty). Decrypting never throws this - only the encrypt path checks.","commonSituations":"Switching a service from aes-256-cbc to aes-256-gcm without adding the new required call; copying example code that predates the auth-data requirement; config defining auth_data only in some environments.","solutions":["Call $crypt->setAuthData($aad) before encrypting with a gcm/ccm cipher - use stable context such as the user id, record id, or app name so decryption can reproduce it exactly.","The same auth data must be present (and identical) when decrypting - keep it alongside your configuration, not per-random values.","If you have no meaningful AAD, prefer aes-256-cbc (with default HMAC signing) instead of passing dummy data - it sidesteps AEAD semantics entirely."],"exampleFix":"// before\n$crypt->setCipher('aes-256-gcm');\n$crypt->setKey($key);\n$token = $crypt->encrypt($payload); // MissingAuthData\n\n// after\n$crypt->setCipher('aes-256-gcm');\n$crypt->setKey($key);\n$crypt->setAuthData('user:' . $user->id);\n$token = $crypt->encrypt($payload);","handlingStrategy":"validation","validationCode":"if ($crypt->getAuthData() === '') {\n    throw new \\RuntimeException('AEAD cipher requires auth data - call setAuthData() before encrypt');\n}\n$cipherText = $crypt->encrypt($payload);","typeGuard":"function isAeadReady(\\Phalcon\\Encryption\\Crypt $crypt): bool\n{\n    $mode = substr($crypt->getCipher(), -3); // 'gcm'/'ccm'\n\n    return !in_array($mode, ['gcm', 'ccm'], true) || '' !== $crypt->getAuthData();\n}","tryCatchPattern":"try {\n    $token = $crypt->encrypt($payload);\n} catch (\\Phalcon\\Encryption\\Crypt\\Exception\\MissingAuthData $e) {\n    throw new \\RuntimeException('AEAD misconfigured: setAuthData() missing in Crypt setup', 0, $e);\n}","preventionTips":["Encapsulate Crypt configuration in one factory: cipher + key + authData are set together, so gcm can never be half-configured.","Use stable, reproducible auth data (user id, record id) so decrypt can recompute the same AAD.","Prefer aes-256-cbc with default signing if you have no meaningful associated data."],"tags":["phalcon","crypt","gcm","aead","auth-data","encryption"],"backgroundTag":"missing-aead-auth-data","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}