AuthenticatedDecryptionFilter

From Crypto++ Wiki
Jump to: navigation, search
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 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.

Unlike StreamTransformationFilter, the AuthenticatedDecryptionFilter requires a counterpart for the encryption and authentication process - the AuthenticatedEncryptionFilter.

Constructor

AuthenticatedDecryptionFilter(AuthenticatedSymmetricCipher &c,
    BufferedTransformation *attachment = NULL, word32 flags = DEFAULT_FLAGS,
    int truncatedDigestSize=-1, BlockPaddingScheme padding = DEFAULT_PADDING);

The AuthenticatedSymmetricCipher will be either a CCM 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 (ADATA) and cipher text data
  • MAC_AT_BEGIN (1)
    • specifies the mac is inserted before the additional authenticated data (ADATA) and cipher text data
  • THROW_EXCEPTION (16)
    • intructs the AuthenticatedDecryptionFilter to throw a HashVerificationFailed exception upon verification failure

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, should not be modified.

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.

Crypto++ Demonstration

Crypto++ demonstrates the use of AuthenticatedEncryptionFilter in datatest.cpp, function TestAuthenticatedSymmetricCipher. Please see the discussion of the TestAuthenticatedSymmetricCipher.

Sample Program

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( ... );
d.SpecifyDataLengths( ... );

AuthenticatedEncryptionFilter df( d,
    new StringSink( cipher )
    /* THROW_EXCEPTION | MAC_AT_END is default */
); // AuthenticatedEncryptionFilter

...

// If verification fails, catch a
//  HashVerificationFailed exception

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( ... );

AuthenticatedDecryptionFilter df( d,
    new StringSink( cipher ),
    DEFAULT_FLAGS, TAG_SIZE
); // AuthenticatedEncryptionFilter

...

Downloads

CCM-AE-Test.zip - CCM Test using only PDATA - 5KB

CCM-AEAD-Test.zip - CCM Test using both ADATA and PDATA - 7KB

EAX-AE-Test.zip - EAX Test using only PDATA - 4KB

EAX-AEAD-Test.zip - EAX Test using both ADATA and PDATA - 7KB

GCM-AE-Test.zip - GCM Test using only PDATA - 5KB

GCM-AEAD-Test.zip - GCM Test using both ADATA and PDATA - 7KB