HAL CCB How to Use

group CCB_How_To_Use

The CCB main features:

The CCB HAL driver is designed to implement specialized coupling and chaining operations that secure these three PKA operations (modular exponentiation, scalar multiplication, ECDSA signature) within dedicated sequences. To perform these operations, the CCB driver requires PKA, SAES and RNG peripherals.

• Each PKA protected operation involves two processes:

  • A blob creation which is a one-time sequence to protect private keys used in PKA protected operations.

  • A blob usage, which is a sequence that can be executed many times to run a PKA protected operation.

• The driver can encrypt, with AES-256, any PKA blob encryption key, which makes the PKA encrypted blob usable only on this device.

How to use the HAL CCB driver

• The CCB driver is secure because it ensures isolation and protects the confidentiality and integrity of private keys.

• The CCB driver allows applications to access its services through dedicated APIs, providing controlled access to protected operations.

The HAL CCB driver can be used as follows:

• Initialize the CCB handle by calling the HAL_CCB_Init() API which performs the following operations:

  • Associate the instance to the handle.

  • Enable the CCB clock interface (when USE_HAL_CCB_CLK_ENABLE_MODEL compilation flag is set to HAL_CLK_ENABLE_PERIPH_ONLY or HAL_CLK_ENABLE_PERIPH_PWR_SYSTEM in the stm32c5xx_hal_conf.h module)

  • Initialize the handle state to the HAL_CCB_STATE_IDLE.

• De-initialize the CCB peripheral by calling the HAL_CCB_DeInit() API, which performs the following operations:

  • Disable of the CCB peripheral.

  • De-initialize the current handle object.

  • Reset the handle state to the HAL_CCB_STATE_RESET.

• Blob creation operation:

  • Wrap a private key, either a clear text (plaintext) user-supplied key or an RNG-generated key, using either a hardware key or a wrapped symmetric software key to create the key blob.

• When using a hardware key as a wrapper:

  • Call either:

    • HAL_CCB_ECDSA_HW_WrapPrivateKey() to wrap a clear text key for ECDSA purposes.

    • HAL_CCB_ECDSA_HW_GenerateWrapPrivateKey() to wrap an RNG-generated key for ECDSA purposes.

• For both APIs, specify the hardware key type. Similar APIs are provided to support ECC and RSA operations.

• When using a software key as a wrapper:

  • First wrap this software key using HAL_CCB_ECDSA_WrapSymmetricKey().

  • The result (wrapped software key) is then used as a wrapper to create the blob.

  • Call either:

    • HAL_CCB_ECDSA_SW_WrapPrivateKey() to wrap a clear text key for ECDSA purposes.

    • HAL_CCB_ECDSA_SW_GenerateWrapPrivateKey() to wrap an RNG-generated key for ECDSA purposes. Similar APIs are provided to support ECC and RSA operations.

• Blob usage operation:

  • Unwrap the created key blob to execute PKA protected operations:

  • When using a hardware-wrapped key blob:

    • The user can call either:

      • HAL_CCB_ECDSA_HW_Sign() to sign a message using the hardware-wrapped ECDSA private key blob.

      • HAL_CCB_ECDSA_HW_ComputePublicKey() to compute the public key using the hardware-wrapped ECDSA private key blob.

      • HAL_CCB_ECC_HW_ComputeScalarMul() to perform ECC scalar multiplication using the hardware-wrapped ECC private key blob.

      • HAL_CCB_RSA_HW_ComputeModularExp() to perform RSA modular exponentiation using the hardware-wrapped RSA private key blob.

    • For HW APIs, specify the hardware key type.

  • When using a software-wrapped key blob:

    • The user can call either:

      • HAL_CCB_ECDSA_SW_Sign() to sign a message using the software-wrapped ECDSA private key blob.

      • HAL_CCB_ECDSA_SW_ComputePublicKey() to compute the public key from the software-wrapped ECDSA private key blob.

      • HAL_CCB_ECC_SW_ComputeScalarMul() to perform ECC scalar multiplication using the software-wrapped ECC private key blob.

      • HAL_CCB_RSA_SW_ComputeModularExp() to perform RSA modular exponentiation using the software-wrapped RSA private key blob.

• Set the compilation flag USE_HAL_CCB_USER_DATA to 1U in the stm32c5xx_hal_conf.h module to allow storing (into the handle) and retrieving the user data respectively through the HAL_CCB_SetUserData() and HAL_CCB_GetUserData() APIs.

Note

No configuration is required after initializing the CCB driver. Once the CCB handle is initialized using the HAL_CCB_Init() API, the driver is ready to start a process.