HAL PKA Functions

Initialization and de-initialization functions

group PKA_Exported_Functions_Group1

This sub-section provides a set of functions allowing to initialize and de-initialize the PKA peripheral:

  • Call the function HAL_PKA_Init() to initialize the HAL PKA handle and associate a PKA peripheral instance.

  • Call the function HAL_PKA_DeInit() to de-initialize the HAL PKA instance by stopping any ongoing process and resetting the state machine.

Functions

hal_status_t HAL_PKA_Init ( hal_pka_handle_t * hpka , hal_pka_t instance )

Initialize the PKA handle and associate physical instance.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter when hpka pointer is NULL.

  • HAL_OK – PKA is successfully initialized.

void HAL_PKA_DeInit ( hal_pka_handle_t * hpka )

De-initialize the PKA handle by aborting any PKA operation in progress.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

Configuration functions

group PKA_Exported_Functions_Group2

This sub-section provides a set of functions allowing to configure the PKA operations.

PKA Modular exponentiation configuration functions

Functions

hal_status_t HAL_PKA_SetConfigModExp ( hal_pka_handle_t * hpka , const hal_pka_mod_exp_config_t * p_config )

Set the Modular exponentiation configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Modular exponentiation is successfully configured.

hal_status_t HAL_PKA_SetConfigModExpFast ( hal_pka_handle_t * hpka , const hal_pka_mod_exp_fast_config_t * p_config )

Set the Modular exponentiation (fast) Mode configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Modular exponentiation (fast) is successfully configured.

hal_status_t HAL_PKA_SetConfigModExpProtect ( hal_pka_handle_t * hpka , const hal_pka_mod_exp_protect_config_t * p_config )

Set the Modular exponentiation (protected) configuration. Useful when a secret information is involved (RSA decryption).

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Modular exponentiation (protected) is successfully configured.

hal_status_t HAL_PKA_ECDSA_SetConfigSignature ( hal_pka_handle_t * hpka , const hal_pka_ecdsa_signature_config_t * p_config )

Set the message signature configuration using elliptic curves over prime fields.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Signature of a message is successfully configured.

hal_status_t HAL_PKA_ECDSA_SetConfigVerifSignature ( hal_pka_handle_t * hpka , const hal_pka_ecdsa_verif_config_t * p_config )

Set the configuration for verifying the validity of a signature using elliptic curves over prime fields.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – The verification of signature validity is successfully configured.

hal_status_t HAL_PKA_RSA_SetConfigCRTExp ( hal_pka_handle_t * hpka , const hal_pka_rsa_crt_exp_config_t * p_config )

Set the RSA CRT exponentiation configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – RSA CRT exponentiation is successfully configured.

hal_status_t HAL_PKA_RSA_SetConfigSignature ( hal_pka_handle_t * hpka , const hal_pka_rsa_signature_config_t * p_config )

Set the message signature configuration using RSA CRT exponentiation.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – RSA CRT exponentiation is successfully configured.

hal_status_t HAL_PKA_RSA_SetConfigVerifSignature ( hal_pka_handle_t * hpka , const hal_pka_rsa_verif_config_t * p_config )

Set the configuration for verifying the validity of a signature using RSA CRT exponentiation.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – The verification of signature validity is successfully configured.

hal_status_t HAL_PKA_SetConfigAdd ( hal_pka_handle_t * hpka , const hal_pka_add_config_t * p_config )

Set Arithmetic Addition Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Arithmetic Addition is successfully configured.

hal_status_t HAL_PKA_SetConfigSub ( hal_pka_handle_t * hpka , const hal_pka_sub_config_t * p_config )

Set Arithmetic subtraction Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Arithmetic subtraction is successfully configured.

hal_status_t HAL_PKA_SetConfigCmp ( hal_pka_handle_t * hpka , const hal_pka_cmp_config_t * p_config )

Set comparison Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Comparison is successfully configured.

hal_status_t HAL_PKA_SetConfigMul ( hal_pka_handle_t * hpka , const hal_pka_mul_config_t * p_config )

Set Arithmetic multiplication Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Arithmetic multiplication is successfully configured.

hal_status_t HAL_PKA_SetConfigModAdd ( hal_pka_handle_t * hpka , const hal_pka_mod_add_config_t * p_config )

Set Modular Addition Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Modular Addition is successfully configured.

hal_status_t HAL_PKA_SetConfigModSub ( hal_pka_handle_t * hpka , const hal_pka_mod_sub_config_t * p_config )

Set Modular subtraction Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Modular subtraction is successfully configured.

hal_status_t HAL_PKA_SetConfigModInv ( hal_pka_handle_t * hpka , const hal_pka_mod_inv_config_t * p_config )

Set Modular Inversion Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Modular Inversion is successfully configured.

hal_status_t HAL_PKA_SetConfigModRed ( hal_pka_handle_t * hpka , const hal_pka_mod_red_config_t * p_config )

Set the Modular Reduction configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Modular reduction is successfully configured.

hal_status_t HAL_PKA_SetConfigMontgomeryMul ( hal_pka_handle_t * hpka , const hal_pka_montgomery_mul_config_t * p_config )

Set Montgomery multiplication Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Montgomery multiplication is successfully configured.

hal_status_t HAL_PKA_SetConfigMontgomery ( hal_pka_handle_t * hpka , const hal_pka_montgomery_config_t * p_config )

Set Montgomery parameter Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Montgomery parameter is successfully configured.

hal_status_t HAL_PKA_ECC_SetConfigPointCheck ( hal_pka_handle_t * hpka , const hal_pka_point_check_config_t * p_config )

Set Point on elliptic curve check configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – Point on elliptic curve check is successfully configured.

hal_status_t HAL_PKA_ECC_SetConfigMul ( hal_pka_handle_t * hpka , const hal_pka_ecc_mul_config_t * p_config )

Set the ECC scalar multiplication configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – ECC scalar multiplication is successfully configured.

hal_status_t HAL_PKA_ECC_SetConfigDoubleBaseLadder ( hal_pka_handle_t * hpka , const hal_pka_ecc_double_base_ladder_config_t * p_config )

Set ECC double base ladder Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – ECC double base ladder is successfully configured.

hal_status_t HAL_PKA_ECC_SetConfigProjectiveToAffine ( hal_pka_handle_t * hpka , const hal_pka_ecc_projective_to_affine_config_t * p_config )

Set ECC projective to affine Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – ECC projective to affine is successfully configured.

hal_status_t HAL_PKA_ECC_SetConfigCompleteAdd ( hal_pka_handle_t * hpka , const hal_pka_ecc_complete_add_config_t * p_config )

Set ECC complete addition Configuration.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when p_config pointer is NULL.

  • HAL_ERROR – PKA is not correctly initialized.

  • HAL_OK – ECC complete addition is successfully configured.

Process management functions

group PKA_Exported_Functions_Group3

This sub-section provides a set of functions allowing to manage the calculation data for an operation.

PKA calculating process functions

PKA Modular exponentiation result functions

Functions

hal_status_t HAL_PKA_Compute ( hal_pka_handle_t * hpka , uint32_t timeout_ms )

Generic function to start a PKA operation in blocking mode.

Parameters :

  • hpka – PKA handle.

  • timeout_ms – Timeout duration.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when hpka pointer or timeout_ms are NULL.

  • HAL_TIMEOUT – In case of user timeout.

  • HAL_ERROR – PKA error is occurred.

  • HAL_BUSY – PKA state is active when calling this API.

  • HAL_OK – Operation is successfully computed.

hal_status_t HAL_PKA_Compute_IT ( hal_pka_handle_t * hpka )

Generic function to start a PKA operation in non-blocking mode with interrupt.

Parameters :

hpka – PKA handle.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when hpka pointer is NULL.

  • HAL_BUSY – PKA state is active when calling this API.

  • HAL_OK – Operation is successfully computed.

void HAL_PKA_IRQHandler ( hal_pka_handle_t * hpka )

This function handles PKA event interrupt request.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

hal_status_t HAL_PKA_Abort ( hal_pka_handle_t * hpka )

Abort any ongoing operation.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter return when hpka pointer is NULL.

  • HAL_OK – Operation is successfully aborted.

uint32_t HAL_PKA_GetResultModExp ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve Modular exponentiation operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultModExpFast ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve Modular exponentiation (Fast) operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultModExpProtected ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve Modular exponentiation (Protected) operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of result error or invalid parameter.

uint32_t HAL_PKA_ECDSA_GetResultSignature ( hal_pka_handle_t * hpka , hal_pka_ecdsa_signature_result_t * p_result , hal_pka_ecdsa_signature_result_ext_config_t * p_result_ext )

Retrieve ECDSA signaure operation result.

Parameters :
Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of result error or invalid parameter.

hal_pka_ecdsa_signature_status_t HAL_PKA_ECDSA_IsValidVerifSignature ( const hal_pka_handle_t * hpka )

Retrieve ECDSA verification signature result.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

Return values :

  • PKA_ECDSA_SIGNATURE_VALID – Signature validated.

  • PKA_ECDSA_SIGNATURE_NOT_VALID – In case of signature not validated or invalid parameter.

uint32_t HAL_PKA_RSA_GetResultCRTExp ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve RSA CRT exponentiation operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_RSA_GetResultSignature ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve RSA signature operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

hal_pka_rsa_signature_status_t HAL_PKA_RSA_IsValidVerifSignature ( hal_pka_handle_t * hpka , const uint8_t * p_hash )

Retrieve RSA verification signature result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_hash – Pointer to hashed message provided by the user.

Return values :

  • PKA_RSA_SIGNATURE_VALID – Signature validated.

  • PKA_RSA_SIGNATURE_NOT_VALID – In case of signature not validated or invalid parameter.

uint32_t HAL_PKA_GetResultAdd ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve Addition operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultSub ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve subtraction operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultMul ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve multiplication operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultCmp ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve comparison operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • PKA_CMP_RESULT_SIZE – Size of the comparison result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultModAdd ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve Modular Addition operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultModSub ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve Modular subtraction operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultModRed ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve Modular Reduction operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultModInv ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve Modular Inversion operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultMontgomeryMul ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve Montgomery multiplication operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

uint32_t HAL_PKA_GetResultMontgomery ( hal_pka_handle_t * hpka , uint8_t * p_result )

Retrieve Montgomery parameter operation result.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_result – Pointer to operation result.

Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

hal_pka_ecc_point_status_t HAL_PKA_ECC_IsPointCheckOnCurve ( const hal_pka_handle_t * hpka )

Retrieve Point on elliptic curve check operation result.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

Return values :

  • PKA_ECC_POINT_ON_CURVE – ECC point is on curve.

  • PKA_ECC_POINT_NOT_ON_CURVE – In case of ECC point is not on curve or invalid parameter.

uint32_t HAL_PKA_ECC_GetResultMul ( hal_pka_handle_t * hpka , hal_pka_ecc_mul_result_t * p_result )

Retrieve ECC scalar multiplication operation result.

Parameters :
Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of result error or invalid parameter.

uint32_t HAL_PKA_ECC_GetResultDoubleBaseLadder ( hal_pka_handle_t * hpka , hal_pka_ecc_double_base_ladder_result_t * p_result )

Retrieve ECC double base ladder operation result.

Parameters :
Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of result error or invalid parameter.

uint32_t HAL_PKA_ECC_GetResultProjectiveToAffine ( hal_pka_handle_t * hpka , hal_pka_ecc_projective_to_affine_result_t * p_result )

Retrieve ECC projective to affine operation result.

Parameters :
Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of result error or invalid parameter.

uint32_t HAL_PKA_ECC_GetResultCompleteAdd ( hal_pka_handle_t * hpka , hal_pka_ecc_complete_add_result_t * p_result )

Retrieve ECC complete addition operation result.

Parameters :
Return values :

  • size_byte – Size of result in byte.

  • 0 – In case of invalid parameter.

Callback functions

group PKA_Exported_Functions_Group4

This sub-section provides a set of callback functions allowing to register the PKA operation and error callbacks:

Functions

void HAL_PKA_OperationCpltCallback ( hal_pka_handle_t * hpka )

Process completed callback.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

void HAL_PKA_ErrorCallback ( hal_pka_handle_t * hpka )

Error callback.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

hal_status_t HAL_PKA_RegisterOperationCpltCallback ( hal_pka_handle_t * hpka , hal_pka_cb_t p_callback )

Register the PKA command complete Callback TO be used instead of the weak HAL_PKA_OperCpltCallback() predefined callback.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_PKA_RegisterErrorCallback ( hal_pka_handle_t * hpka , hal_pka_cb_t p_callback )

Register the PKA Error Callback to be used instead of the weak HAL_PKA_ErrorCallback() predefined callback.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – Register completed successfully.

State and Error functions

group PKA_Exported_Functions_Group5

This sub-section provides a set of functions allowing to get the PKA state, error code, and data information :

Functions

hal_pka_state_t HAL_PKA_GetState ( const hal_pka_handle_t * hpka )

Retrieve the PKA global state.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

Return values :

hal_pka_state_t – PKA state

uint32_t HAL_PKA_GetLastErrorCodes ( const hal_pka_handle_t * hpka )

Retrieve the PKA error code.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

Return values :

PKA – error code.

void HAL_PKA_SetUserData ( hal_pka_handle_t * hpka , const void * p_user_data )

Store the user data into the pka handle.

Parameters :

  • hpka – Pointer to hal_pka_handle_t PKA handle.

  • p_user_data – Pointer to the user data.

const void * HAL_PKA_GetUserData ( const hal_pka_handle_t * hpka )

Retrieve the user data from the pka handle.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

Return values :

Pointer – to the user data.

PKA RAM Mass Erase function

group PKA_Exported_Functions_Group6

This sub-section provides a function called HAL_PKA_RAMMassErase() allowing to erase the content of the PKA RAM.

Functions

hal_status_t HAL_PKA_RAMMassErase ( hal_pka_handle_t * hpka )

Erase the content of PKA RAM.

Parameters :

hpka – Pointer to hal_pka_handle_t PKA handle.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – The content of PKA RAM is fully and successfully erased.