AuthenticatedDecryptionFilter
Documentation |
#include <cryptopp/filters.h>
|
AuthenticatedDecryptionFilter is the concrete 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 two modes of operation that can be utilized by this filter are CCM and GCM.
The filter allows input of both confidential data (data to be encrypted or decrypted) and additional authenticated data (plain text data to be authenticated). The confidential data, on the primary channel, has both encryption and authentication applied to it. The additional authenticated data (aad), presented to the filter on the AAD channel, has only authentication assurances.
Unlike StreamTransformationFilter, the AuthenticatedDecryptionFilter
requires a counterpart for the encryption and authentication process - the AuthenticatedEncryptionFilter. The wiki also has a AadSource example to pump both confidential data and aad to an AuthenticatedDecryptionFilter
.
Crypto++ 8.2 and earlier had a bug in AuthenticatedDecryptionFilter
where using a FileSource would cause an exception; but a StringSource was OK. The bug was fixed at Commit ff110c6e183e. Also see Issue 817.
Sources, filters and sinks are discussed at Pipelining. The pipeline article explains the design and shows you how to use them.
Constructor
AuthenticatedDecryptionFilter(AuthenticatedSymmetricCipher &c, BufferedTransformation *attachment = NULL, word32 flags = DEFAULT_FLAGS, int truncatedDigestSize=-1, 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, flags
, can be any of the following; however MAC_AT_BEGIN
and MAC_AT_END
are mutually exclusive.
DEFAULT_FLAGS
=THROW_EXCEPTION
|MAC_AT_END
MAC_AT_END
(0)- specifies the mac is inserted after the additional authenticated data (aad) and cipher text data
MAC_AT_BEGIN
(1)- specifies the mac is inserted before the additional authenticated data (aad) and cipher text data
THROW_EXCEPTION
(16)- intructs the
AuthenticatedDecryptionFilter
to throw a HashVerificationFailed exception upon verification failure
- intructs the
The fourth parameter, truncatedDigestSize
, is used by the HashFilter to truncate the digest size. Only GCM mode should use this parameter, as 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 parameter, padding
, allows you to specify padding. Depending on the mode, the value may (or may not) have an effect.
The tag sizes are not always in the realm of construction (due to CCM's formatting function), however, it is appropriate to list their default values when discussing constructors. The default tag size for an AuthenticatedDecryptionFilter
using both CCM and GCM is 16 bytes.
CCM Mode
The first sample demonstrates using the AuthenticatedDecryptionFilter
with CCM mode. Recall that the tag size must be a template parameter when using CCM.
const int TAG_SIZE = 12 /*96 bits*/; CCM< AES, TAG_SIZE >::Decryption d; d.SetKeyWithIV(key, key.size(), iv, iv.size()); d.SpecifyDataLengths( ... ); AuthenticatedDecryptionFilter df( d, new StringSink( recovered) /* THROW_EXCEPTION | MAC_AT_END is default */ ); // AuthenticatedEncryptionFilter ... // If verification fails, catch a // HashVerificationFailed exception
GCM Mode
The second sample demonstrates using the AuthenticatedDecryptionFilter
with GCM mode. Recall that the tag size is passed as a parameter to the AuthenticatedDecryptionFilter
during construction.
const int TAG_SIZE = 12 /*96 bits*/; GCM< AES >::Decryption d; d.SetKeyWithIV(key, key.size(), iv, iv.size()); AuthenticatedDecryptionFilter df( d, new StringSink( recovered ), DEFAULT_FLAGS, TAG_SIZE ); // AuthenticatedEncryptionFilter ...
Downloads
CCM-AE-Test.zip - CCM Test using only confidential data - 5KB
CCM-AEAD-Test.zip - CCM Test using both aad and confidential data - 7KB
EAX-AE-Test.zip - EAX Test using only confidential data - 4KB
EAX-AEAD-Test.zip - EAX Test using both aad and confidential data - 7KB
GCM-AE-Test.zip - GCM Test using only confidential data - 5KB
GCM-AEAD-Test.zip - GCM Test using both aad and confidential data - 7KB