AuthenticatedEncryptionFilter is the concrete filter object for authenticated encryption (AE) and authenticated encryption with additional data (AEAD). The filter combines a block cipher operated in an appropriate mode with a HashFilter for authenticated encryption. Currently, the three modes of operation that can be utilized by this filter are CCM, EAX and GCM.
The filter allows input of both plain text data (PDATA) and additional authenticated data (ADATA). The plain text (PDATA), on the primary channel, has both encryption and authentication applied to its data. The additional authenticated data (ADATA), presented to the filter on the AAD channel, has only authentication assurances.
The output of the filter is a concatenation of both encrypted data (from the PDATA alone), and a tag attesting to the authenticity of both the ADATA and PDATA. In the case of GCM, the tag is a truncation of a 128-bit MAC. CCM uses the tag size as an input parameter to the formatting function. So a change in the CCM tag size results in a change in the CCM MAC value which results in a change to CCM's final tag value.
AuthenticatedEncryptionFilter(AuthenticatedSymmetricCipher &c, BufferedTransformation *attachment = NULL, bool putAAD=false, int truncatedDigestSize=-1, const std::string &macChannel=DEFAULT_CHANNEL, BlockPaddingScheme padding=DEFAULT_PADDING);
The AuthenticatedSymmetricCipher will be a CCM mode, EAX mode or GCM mode object. As is customary with Crypto++, a BufferedTransformation is available for pipelining as the second parameter. The third parameter, putAAD, is passed directly to the HashFilter.
The fourth parameter, truncatedDigestSize, is used by the HashFilter to truncate the digest size. Only GCM mode should use this parameter, as a simple truncation works as expected. CCM, which uses a formatting function, requires the digest size to be known at compile time and declared as a template parameter. So CCM mode should not change the default value.
The final two parameters, macChannel and padding, should not be modified. Depending on the mode, the padding value may (or may not) have an effect.
While the tag sizes are not always in the realm of construction (due to CCM's formatting function), it is appropriate to list their default values when discussing constructors. The default tag size for an AuthenticatedEncryptionFilter using both CCM and GCM is 16 bytes.
const int TAG_SIZE = 12 /*96 bits*/; CCM< AES, TAG_SIZE >::Encryption e; e.SetKeyWithIV(key, key.size(), iv, iv.size()); e.SpecifyDataLengths( ... ); AuthenticatedEncryptionFilter ef( e, new StringSink( cipher ) ); // AuthenticatedEncryptionFilter ...
const int TAG_SIZE = 12 /*96 bits*/; GCM< AES >::Encryption e; e.SetKeyWithIV(key, key.size(), iv, iv.size()); AuthenticatedEncryptionFilter ef( e, new StringSink( cipher ), false, TAG_SIZE ); // AuthenticatedEncryptionFilter ...