CryptoAuthLib
Microchip CryptoAuthentication Library
atca_basic_aes_gcm.c File Reference

CryptoAuthLib Basic API methods for AES GCM mode. More...

#include "atca_basic_aes_gcm.h"
#include "atca_compiler.h"

Functions

ATCA_STATUS atcab_aes_gcm_init (atca_aes_gcm_ctx_t *ctx, uint16_t key_id, uint8_t key_block, const uint8_t *iv, size_t iv_size)
 Initialize context for AES GCM operation with an existing IV, which is common when starting a decrypt operation. More...
 
ATCA_STATUS atcab_aes_gcm_init_rand (atca_aes_gcm_ctx_t *ctx, uint16_t key_id, uint8_t key_block, size_t rand_size, const uint8_t *free_field, size_t free_field_size, uint8_t *iv)
 Initialize context for AES GCM operation with a IV composed of a random and optional fixed(free) field, which is common when starting an encrypt operation. More...
 
ATCA_STATUS atcab_aes_gcm_aad_update (atca_aes_gcm_ctx_t *ctx, const uint8_t *aad, uint32_t aad_size)
 Process Additional Authenticated Data (AAD) using GCM mode and a key within the ATECC608A device. More...
 
ATCA_STATUS atcab_aes_gcm_encrypt_update (atca_aes_gcm_ctx_t *ctx, const uint8_t *plaintext, uint32_t plaintext_size, uint8_t *ciphertext)
 Encrypt data using GCM mode and a key within the ATECC608A device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function. More...
 
ATCA_STATUS atcab_aes_gcm_encrypt_finish (atca_aes_gcm_ctx_t *ctx, uint8_t *tag, size_t tag_size)
 Complete a GCM encrypt operation returning the authentication tag. More...
 
ATCA_STATUS atcab_aes_gcm_decrypt_update (atca_aes_gcm_ctx_t *ctx, const uint8_t *ciphertext, uint32_t ciphertext_size, uint8_t *plaintext)
 Decrypt data using GCM mode and a key within the ATECC608A device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function. More...
 
ATCA_STATUS atcab_aes_gcm_decrypt_finish (atca_aes_gcm_ctx_t *ctx, const uint8_t *tag, size_t tag_size, bool *is_verified)
 Complete a GCM decrypt operation verifying the authentication tag. More...
 

Variables

const char * atca_basic_aes_gcm_version = "1.0"
 

Detailed Description

CryptoAuthLib Basic API methods for AES GCM mode.

The AES command supports 128-bit AES encryption or decryption of small messages or data packets in ECB mode. Also can perform GFM (Galois Field Multiply) calculation in support of AES-GCM.

Note
List of devices that support this command - ATECC608A. Refer to device datasheet for full details.

Function Documentation

◆ atcab_aes_gcm_aad_update()

ATCA_STATUS atcab_aes_gcm_aad_update ( atca_aes_gcm_ctx_t ctx,
const uint8_t *  aad,
uint32_t  aad_size 
)

Process Additional Authenticated Data (AAD) using GCM mode and a key within the ATECC608A device.

This can be called multiple times. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function. When there is AAD to include, this should be called before atcab_aes_gcm_encrypt_update() or atcab_aes_gcm_decrypt_update().

Parameters
[in]ctxAES GCM context
[in]aadAdditional authenticated data to be added
[in]aad_sizeSize of aad in bytes
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_gcm_decrypt_finish()

ATCA_STATUS atcab_aes_gcm_decrypt_finish ( atca_aes_gcm_ctx_t ctx,
const uint8_t *  tag,
size_t  tag_size,
bool *  is_verified 
)

Complete a GCM decrypt operation verifying the authentication tag.

Parameters
[in]ctxAES GCM context structure.
[in]tagExpected authentication tag.
[in]tag_sizeSize of tag in bytes (12 to 16 bytes).
[out]is_verifiedReturns whether or not the tag verified.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_gcm_decrypt_update()

ATCA_STATUS atcab_aes_gcm_decrypt_update ( atca_aes_gcm_ctx_t ctx,
const uint8_t *  ciphertext,
uint32_t  ciphertext_size,
uint8_t *  plaintext 
)

Decrypt data using GCM mode and a key within the ATECC608A device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function.

Parameters
[in]ctxAES GCM context structure.
[in]ciphertextCiphertext to be decrypted.
[in]ciphertext_sizeSize of ciphertext in bytes.
[out]plaintextDecrypted data is returned here.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_gcm_encrypt_finish()

ATCA_STATUS atcab_aes_gcm_encrypt_finish ( atca_aes_gcm_ctx_t ctx,
uint8_t *  tag,
size_t  tag_size 
)

Complete a GCM encrypt operation returning the authentication tag.

Parameters
[in]ctxAES GCM context structure.
[out]tagAuthentication tag is returned here.
[in]tag_sizeTag size in bytes (12 to 16 bytes).
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_gcm_encrypt_update()

ATCA_STATUS atcab_aes_gcm_encrypt_update ( atca_aes_gcm_ctx_t ctx,
const uint8_t *  plaintext,
uint32_t  plaintext_size,
uint8_t *  ciphertext 
)

Encrypt data using GCM mode and a key within the ATECC608A device. atcab_aes_gcm_init() or atcab_aes_gcm_init_rand() should be called before the first use of this function.

Parameters
[in]ctxAES GCM context structure.
[in]plaintextPlaintext to be encrypted (16 bytes).
[in]plaintext_sizeSize of plaintext in bytes.
[out]ciphertextEncrypted data is returned here.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_gcm_init()

ATCA_STATUS atcab_aes_gcm_init ( atca_aes_gcm_ctx_t ctx,
uint16_t  key_id,
uint8_t  key_block,
const uint8_t *  iv,
size_t  iv_size 
)

Initialize context for AES GCM operation with an existing IV, which is common when starting a decrypt operation.

Parameters
[in]ctxAES GCM context to be initialized.
[in]key_idKey location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]key_blockIndex of the 16-byte block to use within the key location for the actual key.
[in]ivInitialization vector.
[in]iv_sizeSize of IV in bytes. Standard is 12 bytes.
Returns
ATCA_SUCCESS on success, otherwise an error code.

◆ atcab_aes_gcm_init_rand()

ATCA_STATUS atcab_aes_gcm_init_rand ( atca_aes_gcm_ctx_t ctx,
uint16_t  key_id,
uint8_t  key_block,
size_t  rand_size,
const uint8_t *  free_field,
size_t  free_field_size,
uint8_t *  iv 
)

Initialize context for AES GCM operation with a IV composed of a random and optional fixed(free) field, which is common when starting an encrypt operation.

Parameters
[in]ctxAES CTR context to be initialized.
[in]key_idKey location. Can either be a slot number or ATCA_TEMPKEY_KEYID for TempKey.
[in]key_blockIndex of the 16-byte block to use within the key location for the actual key.
[in]rand_sizeSize of the random field in bytes. Minimum and recommended size is 12 bytes. Max is 32 bytes.
[in]free_fieldFixed data to include in the IV after the random field. Can be NULL if not used.
[in]free_field_sizeSize of the free field in bytes.
[out]ivInitialization vector is returned here. Its size will be rand_size and free_field_size combined.
Returns
ATCA_SUCCESS on success, otherwise an error code.

Variable Documentation

◆ atca_basic_aes_gcm_version

const char* atca_basic_aes_gcm_version = "1.0"