Skip to main content

AEAD algorithms

The AES-GCM, AES-CCM, and ChaCha20-Poly1305 as AEAD ciphers are supported. Refer to AEAD algorithms for descriptions of these ciphers.

This section focuses on how to use AES-GCM. The other ciphers are similar. One aspect that is unique to the GCM implementation is the concept of the internal table size used by the GCM algorithm, which may be 256 bytes, 4K bytes, or 64K bytes. These tables provide the obvious runtime performance versus memory usage tradeoff.

The table sizes available must be chosen at build-time by defining one or more of the following flags:

  • __ENABLE_MOCANA_GCM_256B__

  • __ENABLE_MOCANA_GCM_4K__

  • __ENABLE_MOCANA_GCM_64K__

The APIs for AES-GCM are all suffixed with an underscore and the table size, which may not be mixed and matched. In other words, a context created for one size only works with APIs with the same size suffix.

Another general aspect of AEAD ciphers is that of additional authenticated data (AAD), which is data that gets absorbed into the authentication (i.e., MAC’ing) portion of the AEAD algorithm. The Crypto Interface for AES-GCM and ChaCha20-Poly1305 have APIs to support streaming of both the AAD and the data to be encrypted or decrypted. These APIs behave similarly to the streaming support described in other sections. Refer to the Crypto Interface API reference for more information.

To use the AES-GCM one shot API with the 4K table size:

  1. Create a context with an AES key of length 16, 24, or 32 bytes. The flag TRUE prepares the context for encryption rather than decryption.

    BulkCtx pCtx = NULL;
pCtx = CRYPTO_INTERFACE_GCM_createCtx_4k(pKeyData, keyDataLen, TRUE);

  2. Encrypt and tag the data. The nonce is used by the GCM specifications to create the initial counter for the underlying AES-CTR mode cipher. It is typically 12 bytes (but does not have to be), is only required to be non-zero, and is optional. The buffer of data pData is encrypted in-place and must have tagLen bytes of space available after it. The authentication tag is placed at the end of the data in the pData buffer, i.e., at location pData+dataLen. The tagLen value must be 4, 8, 12, 13, 14, 15, or 16 as specified by the GCM specifications. Again, TRUE must be passed for the encrypt flag:

    CRYPTO_INTERFACE_GCM_cipher_4k(pCtx, pNonce, nonceLen, pAad, aadLen, pData, dataLen, tagLen, TRUE);

    Important

    When decrypting with this API, the tag should be located after the data. The dataLen value should be the length of the data itself (not including the length of the tag). A negative error code is returned if the tag is not verified as valid. Ensure that the return status is OK before accepting that the decrypted data is valid.

  3. Clean up the context.

    CRYPTO_INTERFACE_GCM_deleteCtx_4k(&pCtx);

Complete example

A complete example may be found at:

${MSS_SRC_PKG}/src/crypto_interface/example/crypto_interface_aes_gcm_example.c
In this section: