HAL PKA How to Use ¶

group PKA_How_To_Use

An explanation on PKA overall usage :

• PKA is the abbreviation of public key accelerator. It’s intended for the computation of cryptographic public key primitives, specifically those related to RSA, Diffie-Hellmann or ECC (elliptic curve cryptography) over GF(p) (Galois fields). To achieve high performance at a reasonable cost, these operations are executed in the Montgomery domain.

• For a given operation, all needed computations are performed within the accelerator, so no further hardware/software elaboration is needed to process the inputs or the outputs.

This file provides firmware functions to manage the following functionalities of PKA peripheral:

• Initialization and De-initialization functions

• Configuration functions

• Process management functions

• Callback functions

• State and Error functions

How to use the PKA HAL module driver ¶

Initialization and de-initialization functions: ¶

• Declare a hal_pka_handle_t handle structure, for example: hal_pka_handle_t hpka.

• Use HAL_PKA_Init() function to initialize the PKA handle and associate the physical instance.

• Use HAL_PKA_DeInit() function to abort any ongoing operation then reset the state.

Configuration functions ¶

• Use HAL_PKA_SetConfigModExp() function to configure the Modular exponentiation operating mode.

• Use HAL_PKA_SetConfigModExpFast() function to configure the Modular exponentiation (fast) operating mode.

• Use HAL_PKA_SetConfigModExpProtect() function to configure the Modular exponentiation (protected) operating mode.

• Use HAL_PKA_SetConfigAdd() function to configure the Arithmetic addition operating mode.

• Use HAL_PKA_SetConfigSub() function to configure the Arithmetic subtraction operating mode.

• Use HAL_PKA_SetConfigCmp() function to configure the Arithmetic comparison operating mode.

• Use HAL_PKA_SetConfigMul() function to configure the Arithmetic multiplication operating mode.

• Use HAL_PKA_SetConfigModAdd() function to configure the Modular addition operating mode.

• Use HAL_PKA_SetConfigModSub() function to configure the Modular subtraction operating mode.

• Use HAL_PKA_SetConfigModInv() function to configure the Modular inversion operating mode.

• Use HAL_PKA_SetConfigModRed() function to configure the Modular reduction operating mode.

• Use HAL_PKA_SetConfigMontgomeryMul() function to configure the Montgomery multiplication operating mode.

• Use HAL_PKA_SetConfigMontgomery() function to configure the Montgomery parameter operating mode.

• Use HAL_PKA_ECDSA_SetConfigSignature() function to configure the elliptic curves over prime fields signature operating mode.

• Use HAL_PKA_ECDSA_SetConfigVerifSignature() function to configure the elliptic curves over prime fields verification operating mode.

• Use HAL_PKA_RSA_SetConfigCRTExp() function to configure the RSA CRT exponentiation operating mode.

• Use HAL_PKA_RSA_SetConfigSignature() function to configure the RSA signature operating mode.

• Use HAL_PKA_RSA_SetConfigVerifSignature() function to configure the RSA verification operating mode.

• Use HAL_PKA_ECC_SetConfigPointCheck() function to configure the Point on elliptic curve check operating mode.

• Use HAL_PKA_ECC_SetConfigMul() function to configure the ECC scalar multiplication operating mode.

• Use HAL_PKA_ECC_SetConfigDoubleBaseLadder() function to configure the ECC double base ladder operating mode.

• Use HAL_PKA_ECC_SetConfigProjectiveToAffine() function to configure the ECC projective to affine operating mode.

• Use HAL_PKA_ECC_SetConfigCompleteAdd() function to configure the ECC complete addition operating mode.

Process management functions ¶

• Use HAL_PKA_Compute() function to execute the operation in blocking mode.

• Use HAL_PKA_Compute_IT() function to execute the operation in interrupt mode.

• Use HAL_PKA_IRQHandler() function called under PKA NVIC vector interrupt subroutine to handle any PKA interrupt.

• Use HAL_PKA_Abort() function to abort any on-going operation. This API must not be called from an interrupt service routine.

• Use HAL_PKA_GetResultModExp() function to retrieve the result of the Modular exponentiation operation.

• Use HAL_PKA_GetResultModExpFast() function to retrieve the result of the Modular exponentiation (Fast) operation.

• Use HAL_PKA_GetResultModExpProtected() function to retrieve the result of the Modular exponentiation (Protected) operation.

• Use HAL_PKA_GetResultAdd() function to retrieve the result of the addition operation.

• Use HAL_PKA_GetResultSub() function to retrieve the result of the subtraction operation.

• Use HAL_PKA_GetResultMul() function to retrieve the result of the multiplication operation.

• Use HAL_PKA_GetResultCmp() function to retrieve the result of the comparison operation.

• Use HAL_PKA_GetResultModAdd() function to retrieve the result of the Modular addition operation.

• Use HAL_PKA_GetResultModSub() function to retrieve the result of the Modular subtraction operation.

• Use HAL_PKA_GetResultModInv() function to retrieve the result of the Modular inversion operation.

• Use HAL_PKA_GetResultModRed() function to retrieve the result of the Modular reduction operation.

• Use HAL_PKA_GetResultMontgomeryMul() function to retrieve the result of the Montgomery parameter operation.

• Use HAL_PKA_GetResultMontgomery() function to retrieve the result of the Montgomery parameter operation.

• Use HAL_PKA_ECDSA_GetResultSignature() function to retrieve the result of the elliptic curves over prime fields signature operation.

• Use HAL_PKA_ECDSA_IsValidVerifSignature() function to check if the signature is verified or not.

• Use HAL_PKA_RSA_GetResultCRTExp() function to retrieve the result of the RSA CRT exponentiation operation.

• Use HAL_PKA_RSA_GetResultSignature() function to retrieve the result of the RSA signature operation.

• Use HAL_PKA_RSA_IsValidVerifSignature() function to check if the signature is verified or not.

• Use HAL_PKA_ECC_IsPointCheckOnCurve() function to check if the point is on curve or not.

• Use HAL_PKA_ECC_GetResultMul() function to retrieve the result of the ECC scalar multiplication operation.

• Use HAL_PKA_ECC_GetResultDoubleBaseLadder() function to retrieve the result of the ECC double base ladder operation.

• Use HAL_PKA_ECC_GetResultProjectiveToAffine() function to retrieve the result of the ECC projective to affine operation.

• Use HAL_PKA_ECC_GetResultCompleteAdd() function to retrieve the result of the ECC complete addition operation.

Callback functions ¶

• The HAL_PKA_OperationCpltCallback() function is called when the process is complete.

• The HAL_PKA_ErrorCallback() function is called in case of an error.

• Use the function HAL_PKA_RegisterOperationCpltCallback() to register the PKA Operation Complete Callback to be used instead of the weak HAL_PKA_OperationCpltCallback() predefined callback.

• Use the function HAL_PKA_RegisterErrorCallback() to register the PKA Error Callback to be used instead of the weak HAL_PKA_ErrorCallback() predefined callback.

Peripheral state, Error functions ¶

• Use HAL_PKA_GetState() function to get the current state of the HAL PKA driver.

• Use HAL_PKA_GetLastErrorCodes() function to Get last error codes.

• Use HAL_PKA_SetUserData() function to set the PKA user data.

• Use HAL_PKA_GetUserData() function to get the PKA user data.

PKA RAM Erase function ¶

• Use HAL_PKA_RAMMassErase() to fully erase the content of PKA RAM.