AES Engine API

group group_ble_common_Encryption_api_functions

BLE sub system AES Engine is exposed through this API.

Functions

cy_en_ble_api_result_t Cy_BLE_GenerateRandomNumber(cy_stc_ble_stack_random_num_param_t *param)

This function generates 8-byte random number that complies with pseudo random number generation in accordance with [FIPS PUB 140-2].

Random number generation function is used during security procedures documented in Bluetooth 5.0 core specification, Volume 3, Part H. The function accepts an application-specific seed for the DRBG (Deterministic Random number generator) function.

Generated random number is informed through event ‘CY_BLE_EVT_RANDOM_NUM_GEN_COMPLETE’

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

If BLE Stack resources are unavailable.

Parameters

param – parameter is of type ‘cy_stc_ble_stack_random_num_param_t’ param->seed: Seed for DRBG. Setting the seed to zero is functionally equivalent to not setting the application-specific seed.

Returns

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

cy_en_ble_api_result_t Cy_BLE_AesEncrypt(cy_stc_ble_aes_encrypt_info_t *param)

This function does AES encryption on the given plain text data using the given 128-bit key.

The output of AES processing is copied to encryptedData buffer. Refer to Bluetooth 5.0 core specification, Volume 3, Part H, section 2.2 for more details on usage of AES key.

Completion of the function is informed through the ‘CY_BLE_EVT_AES_ENCRYPT_COMPLETE’ event. A (uint8_t*) type parameter is returned along with the event. This is the pointer to the encrypted data (128-bit).

param->aesKey: Pointer to the AES Key (128-bit) that is to be used for AES encryption.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

On specifying NULL as input parameter.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

AES engine is being used internally or BLE Stack resources are unavailable.

Parameters

param – Parameter of type ‘cy_stc_ble_aes_encrypt_info_t’. param->plainData: Pointer to the data containing plain text (128-bit) that is to be encrypted.

Returns

cy_en_ble_api_result_t : Return value indicates whether the function succeeded or failed. Following are the possible error codes.

cy_en_ble_api_result_t Cy_BLE_AesCcmEncrypt(cy_stc_ble_aes_ccm_encrypt_info_t *param)

This function does AES-CCM encryption on the given data using the given 16-bit key and 13-bit nonce.

Encrypted data is informed through the (cy_stc_ble_aes_ccm_param_t*) type parameter returned along with the ‘CY_BLE_EVT_AES_CCM_ENCRYPT_COMPLETE’ event. This parameter consists of the MIC value generated during encryption along with a pointer to the encrypted data.

Errors codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

One of the inputs is a null pointer.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

If Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

If BLE Stack resources are unavailable.

Parameters

param – Parameter is of type ‘cy_stc_ble_aes_ccm_encrypt_info_t

Returns

cy_en_ble_api_result_t: Return value indicates whether the function succeeded or failed. Following are the possible error codes.

cy_en_ble_api_result_t Cy_BLE_AesCcmDecrypt(cy_stc_ble_aes_ccm_decrypt_info_t *param)

This function decrypts the given AES-CCM encrypted data.

It requires the 16-bit key, and 13-bit nonce along with the 4-bit MIC value generated during AES CCM encryption.

Decrypted data is informed through the (cy_stc_ble_aes_ccm_param_t*) type parameter returned along with the ‘CY_BLE_EVT_AES_CCM_DECRYPT_COMPLETE’ event.

Error codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

One of the inputs is a NULL pointer.

CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED

Memory allocation failed.

CY_BLE_ERROR_INSUFFICIENT_RESOURCES

BLE Stack resources are unavailable.

Parameters

param – Parameter is of type ‘cy_stc_ble_aes_ccm_decrypt_info_t

Returns

cy_en_ble_api_result_t: Return value indicates whether the function succeeded or failed. Following are the possible error codes.

cy_en_ble_api_result_t Cy_BLE_GenerateAesCmac(cy_stc_ble_aes_cmac_generate_param_t *cmacGenParam)

This function enables the application to generate the AES CMAC of 16 bytes for a given variable length message and CMAC Key.

If the function call resulted in CY_BLE_SUCCESS, then, CY_BLE_EVT_AES_CMAC_GEN_COMPLETE event indicates completion of cmac generation.

Error codes

Description

CY_BLE_SUCCESS

On successful operation.

CY_BLE_ERROR_INVALID_PARAMETER

One of the inputs is a NULL pointer, the 'buffer' can be NULL only if 'size' is zero.

CY_BLE_ERROR_INVALID_OPERATION

Application has already initiated AES CMAC operation that is pending completion.

Parameters

cmacGenParam – Parameter is of type ‘cy_stc_ble_aes_cmac_generate_param_t ‘ cmacGenParam->mac: is a pointer to the generated cmac value. Application can get the generated cmac value from this location after completion of CMAC generation.

Returns

cy_en_ble_api_result_t: Return value indicates whether the function succeeded or failed. Following are the possible error codes.