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.