![]() |
![]() |
Interface to for all HSM-related operations.
This module provides functions for use of the Hardware Security Module.
The HSM initialization procedure must first enable the clock, then initialize the mailbox, and finally boot the device.
APIs are provided to synchronize access to the HSM and submit command tokens, constructed by TI crypto drivers.
Additional APIs to construct command tokens, interpret result token data as well as additional key/asset management operations.
#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/SHA2.h>
#include <ti/drivers/sha2/SHA2LPF3HSM.h>
#include <ti/drivers/ECDSA.h>
#include <ti/drivers/ecdsa/ECDSALPF3HSM.h>
#include <ti/drivers/AESGCM.h>
#include <ti/drivers/aesgcm/AESGCMLPF3HSM.h>
#include <ti/drivers/AESECB.h>
#include <ti/drivers/aesecb/AESECBLPF3.h>
#include <ti/drivers/AESCTR.h>
#include <ti/drivers/aesctr/AESCTRLPF3.h>
#include <ti/drivers/AESCBC.h>
#include <ti/drivers/aescbc/AESCBCLPF3.h>
#include <ti/drivers/AESCMAC.h>
#include <ti/drivers/aescmac/AESCMACLPF3.h>
#include <ti/drivers/AESCCM.h>
#include <ti/drivers/aesccm/AESCCMLPF3.h>
#include <ti/drivers/dpl/SemaphoreP.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
#include <third_party/hsmddk/include/Kit/EIP130/TokenHelper/incl/eip130_token_common.h>
Go to the source code of this file.
Data Structures | |
struct | HSMLPF3_Operation |
Struct to hold metadata for a crypto driver's operation. More... | |
Macros | |
#define | HSMLPF3_STATUS_SUCCESS ((int_fast16_t)0) |
Successful status code. More... | |
#define | HSMLPF3_STATUS_ERROR ((int_fast16_t)-1) |
Generic error status code. More... | |
#define | HSMLPF3_STATUS_TIMEOUT ((int_fast16_t)-2) |
Timeout for polling mode response. More... | |
#define | AES_MODE_ENCRYPT 1U |
#define | AES_MODE_DECRYPT 0U |
#define | HSMLPF3_RETVAL_MASK MASK_8_BITS |
Typedefs | |
typedef void(* | HSMLPF3_CallbackFxn) (uintptr_t arg0) |
Pointer to crypto driver post-processing functions. More... | |
Enumerations | |
enum | HSMLPF3_ReturnBehavior { HSMLPF3_RETURN_BEHAVIOR_CALLBACK = 1, HSMLPF3_RETURN_BEHAVIOR_BLOCKING = 2, HSMLPF3_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which HSMLPF3_waitForResult() function calls return after performing an calling HSMLPF3_submitToken(). More... | |
Functions | |
void | HSMLPF3_constructRTOSObjects (void) |
Initializes the HWI and semaphores for HSMLPF3. More... | |
void | HSMLPF3_disableClock (void) |
Disables clock for HSM, effectively powering it off. More... | |
int_fast16_t | HSMLPF3_sleep (void) |
Puts the HSM to sleep, lowering its power consumption. More... | |
int_fast16_t | HSMLPF3_init (void) |
Initializes the HSM and HSMLPF3 driver for token submissions. More... | |
bool | HSMLPF3_acquireLock (uint32_t timeout, uintptr_t driverHandle) |
Acquires the HSMLPF3_accessSemaphore. More... | |
void | HSMLPF3_releaseLock (void) |
Releases the lock on HSM access. More... | |
int_fast16_t | HSMLPF3_submitToken (HSMLPF3_ReturnBehavior retBehavior, HSMLPF3_CallbackFxn callbackFxn, uintptr_t driverHandle) |
Submits a token to the HSM mailbox. More... | |
int_fast16_t | HSMLPF3_waitForResult (void) |
Waits for HSM response to previously submitted token. More... | |
int_fast16_t | HSMLPF3_cancelOperation (void) |
Cancels the operation currently in progress. More... | |
bool | HSMLPF3_isOperationInProgress (void) |
returns the value of HSMLPF3_operationInProgress More... | |
int32_t | HSMLPF3_getResultCode (void) |
Get operation result code. More... | |
uint32_t | HSMLPF3_getResultAssetID (void) |
Fetches the asset ID from the HSM's result token. More... | |
void | HSMLPF3_getResultDigest (uint32_t *digest, size_t digestLength) |
Copies a hash operation's digest to user space. More... | |
void | HSMLPF3_getAESEncryptTag (uint8_t *mac) |
Fetches the AES tag. More... | |
void | HSMLPF3_getAESIV (uint8_t *iv) |
Fetches the AES IV. More... | |
void | HSMLPF3_getAESCMACSignMac (uint8_t *mac, uint8_t macLength) |
Fetches the Final mac from result token. More... | |
void | HSMLPF3_constructCreateAssetToken (uint64_t assetPolicy, uint32_t assetLength) |
Constructs an asset create command token. More... | |
void | HSMLPF3_constructLoadPlaintextAssetToken (const uint8_t *input_p, const uint32_t inputLength, uint32_t assetId) |
Constructs an asset load plaintext command token. More... | |
void | HSMLPF3_constructDeleteAssetToken (uint32_t assetId) |
Constructs an asset delete command token. More... | |
void | HSMLPF3_constructSHA2PhysicalToken (SHA2LPF3HSM_Object *object) |
Constructs a SHA2 onestep/segmented command token. More... | |
void | HSMLPF3_constructECDSASignPhysicalToken (ECDSALPF3HSM_Object *object) |
Constructs a ECDSA sign/verify command token. More... | |
void | HSMLPF3_constructECDHnumLoadPhysicalToken (const uint8_t *buffer, uint8_t index, uint8_t length) |
Constructs a ECDH num load command token. More... | |
void | HSMLPF3_constructECDHnumSetPhysicalToken (uint8_t length) |
Constructs a ECDH num set command token. More... | |
void | HSMLPF3_constructECDHPKAOperationPhysicalToken (uint8_t operation, uint8_t *input, uint8_t *output, uint32_t inputLength) |
Constructs a ECDH PK command token. More... | |
void | HSMLPF3_constructAESGCMOneStepPhysicalToken (AESGCMLPF3HSM_Object *object) |
Constructs an AES-GCM one-step/segmented command token. More... | |
void | HSMLPF3_constructAESGCMSegmentedAADPhysicalToken (AESGCMLPF3HSM_Object *object) |
Populate the command token to reflect an AES-GCM segmented AAD operation. More... | |
void | HSMLPF3_constructAESGCMSegmentedDataPhysicalToken (AESGCMLPF3HSM_Object *object) |
Populate the command token to reflect an AES-GCM segmented or final data operation. More... | |
void | HSMLPF3_constructAESCCMOneStepPhysicalToken (const AESCCMLPF3_Object *object) |
Constructs an AES-CCM one-step/segmented command token. More... | |
void | HSMLPF3_constructAESCCMSegmentedAADPhysicalToken (const AESCCMLPF3_Object *object) |
Populate the command token to reflect an AES-CCM segmented AAD operation. More... | |
void | HSMLPF3_constructAESCCMSegmentedDataPhysicalToken (const AESCCMLPF3_Object *object) |
Populate the command token to reflect an AES-CCM segmented or final data operation. More... | |
void | HSMLPF3_constructAESECBOneStepPhysicalToken (AESECBLPF3_Object *object) |
Constructs an AES-ECB one-step command token. More... | |
void | HSMLPF3_constructAESCTROneStepPhysicalToken (AESCTRLPF3_Object *object) |
Constructs an AES-CTR one-step command token. More... | |
void | HSMLPF3_constructAESCBCOneStepPhysicalToken (AESCBCLPF3_Object *object) |
void | HSMLPF3_constructAESCMACOneStepPhysicalToken (AESCMACLPF3_Object *object) |
Constructs an AES-CMAC one-step command token. More... | |
void | HSMLPF3_constructAESCMACUpdatePhysicalToken (AESCMACLPF3_Object *object, bool isInitWithDefault) |
Constructs an AES-CMAC update command token. More... | |
#define HSMLPF3_STATUS_SUCCESS ((int_fast16_t)0) |
Successful status code.
Functions return HSMLPF3_STATUS_SUCCESS if the function was executed successfully.
#define HSMLPF3_STATUS_ERROR ((int_fast16_t)-1) |
Generic error status code.
Functions return HSMLPF3_STATUS_ERROR if the function was not executed successfully and no more specific error is applicable.
#define HSMLPF3_STATUS_TIMEOUT ((int_fast16_t)-2) |
Timeout for polling mode response.
Functions return HSMLPF3_STATUS_TIMEOUT if the HSMLPF3_ReturnBehavior is set to HSMLPF3_RETURN_BEHAVIOR_POLLING and the HSM does not provide an output token in sufficient time.
#define AES_MODE_ENCRYPT 1U |
#define AES_MODE_DECRYPT 0U |
#define HSMLPF3_RETVAL_MASK MASK_8_BITS |
typedef void(* HSMLPF3_CallbackFxn) (uintptr_t arg0) |
Pointer to crypto driver post-processing functions.
Crypto drivers pass an HSMLPF3_CallbackFxn as a parameter to HSMLPF3_submitToken(). In callback mode, the HSMLPF3 HWI will call the drivers' post-processing functions, as stored in the HSMLPF3_Operation struct.
The way in which HSMLPF3_waitForResult() function calls return after performing an calling HSMLPF3_submitToken().
HSMLPF3_waitForResult() has restrictions on the context from which it may be called, depending on the return behavior.
Task | Hwi | Swi | |
---|---|---|---|
HSMLPF3_RETURN_BEHAVIOR_CALLBACK | X | X | X |
HSMLPF3_RETURN_BEHAVIOR_BLOCKING | X | ||
HSMLPF3_RETURN_BEHAVIOR_POLLING | X | X | X |
Enumerator | |
---|---|
HSMLPF3_RETURN_BEHAVIOR_CALLBACK | The HSMLPF3_waitForResult() call will return immediately while the HSM operation goes on in the background. The registered callback function is called after the operation completes. The callback function is a driver-specific post-processing function that will be called from the common HWI. |
HSMLPF3_RETURN_BEHAVIOR_BLOCKING | The HSMLPF3_waitForResult() call will block while the HSM operation goes on in the background. The HWI will post the semaphore. HSM operation results are available after the function returns. |
HSMLPF3_RETURN_BEHAVIOR_POLLING | The HSMLPF3_waitForResult() call will continuously poll a flag while the HSM operation goes on in the background. The HWI will set the flag. SHA2 operation results are available after the function returns. |
void HSMLPF3_constructRTOSObjects | ( | void | ) |
Initializes the HWI and semaphores for HSMLPF3.
This function registers a hardware interrupt for result tokens from the HSM, and constructs the HSMLPF3_accessSemaphore and HSMLPF3_operationSemaphore.
This function should be called from driver init() functions.
void HSMLPF3_disableClock | ( | void | ) |
Disables clock for HSM, effectively powering it off.
This function provides an alternative to putting the HSM to sleep when it no longer needs to be used.
int_fast16_t HSMLPF3_sleep | ( | void | ) |
Puts the HSM to sleep, lowering its power consumption.
This function submits a sleep token to the HSM, and waits for a successful token result.
Calling this function when the HSM is already asleep will still submit a sleep token.
HSMLPF3_STATUS_SUCCESS | HSM put to sleep successfully. |
HSMLPF3_STATUS_ERROR | Error. Error output token, or HSM in bad state. |
int_fast16_t HSMLPF3_init | ( | void | ) |
Initializes the HSM and HSMLPF3 driver for token submissions.
This function enables the HSM clock, initializes the HSM mailbox, boots the HSM, and performs extra initialization for the token submission process. The return value reflects if any of these operations fail.
This function should be called in driver construct() functions.
HSMLPF3_STATUS_SUCCESS | HSM booted and initialized successfully. |
HSMLPF3_STATUS_ERROR | Error. Failed boot or mailbox initiailization. |
bool HSMLPF3_acquireLock | ( | uint32_t | timeout, |
uintptr_t | driverHandle | ||
) |
Acquires the HSMLPF3_accessSemaphore.
This function will attempt to take the HSMLPF3_accessSemaphore. The calling driver must decide whether timeout is SemaphoreP_NO_WAIT or another value.
[in] | timeout | Amount of time to wait for semaphore to be posted. |
[in] | driverHandle | The driver's handle. |
Returns | True on success, False on timeout |
void HSMLPF3_releaseLock | ( | void | ) |
Releases the lock on HSM access.
This function will release the HSMLPF3_accessSemaphore. It will also clear the HSMLPF3_Operation.driverHandle member.
int_fast16_t HSMLPF3_submitToken | ( | HSMLPF3_ReturnBehavior | retBehavior, |
HSMLPF3_CallbackFxn | callbackFxn, | ||
uintptr_t | driverHandle | ||
) |
Submits a token to the HSM mailbox.
This function will convert the provided logical token into a physical token for the HSM to process. It will also save the operation metadata to the HSMLPF3 driver, for use in HSMLPF3_waitForResult().
[in] | retBehavior | Driver's return behavior for use in HSMLPF3_waitForResult(). |
[in] | callbackFxn | Pointer to driver's result post-processing function. This post-processing function will call the user-provided callback function, if the driver is in callback mode. |
[in] | driverHandle | The driver's handle. |
HSMLPF3_STATUS_SUCCESS | Token successfully written to HSM mailbox. |
HSMLPF3_STATUS_ERROR | Error. Invalid token or unsuccessful write to mailbox. |
int_fast16_t HSMLPF3_waitForResult | ( | void | ) |
Waits for HSM response to previously submitted token.
This function is responsible for reporting the result back to the driver that submitted an operation request. Depending on the return behavior provided in HSMLPF3_submitToken(), this function will poll a flag, block on an operation semaphore, or return immediately.
HSMLPF3_STATUS_SUCCESS | Successfully waited for the result. |
HSMLPF3_STATUS_ERROR | Error. Provided return behavior invalid. |
int_fast16_t HSMLPF3_cancelOperation | ( | void | ) |
Cancels the operation currently in progress.
This API checks to see if there is an operation currently running. If so, wait on the HSM to finish in polling mode and clear the appropriate interrupts.
HSMLPF3_STATUS_SUCCESS | Successfully canceled operation in progress. |
HSMLPF3_STATUS_ERROR | Error. |
bool HSMLPF3_isOperationInProgress | ( | void | ) |
returns the value of HSMLPF3_operationInProgress
true | Operation in progress |
false | No operation in progress |
int32_t HSMLPF3_getResultCode | ( | void | ) |
Get operation result code.
This API should be called during a driver's post processing sequence after a call to HSMLPF3_submitToken() that submits an asset creation token.
Result | token return code. |
uint32_t HSMLPF3_getResultAssetID | ( | void | ) |
Fetches the asset ID from the HSM's result token.
This API should be called during a driver's post processing sequence after a call to HSMLPF3_submitToken() that submits an asset creation token.
Asset | Identification Number |
void HSMLPF3_getResultDigest | ( | uint32_t * | digest, |
size_t | digestLength | ||
) |
Copies a hash operation's digest to user space.
[in] | digest | User specified destination address |
[in] | digestLength | User's digest length |
void HSMLPF3_getAESEncryptTag | ( | uint8_t * | mac | ) |
Fetches the AES tag.
[in] | object | Pointer to copy tag to |
void HSMLPF3_getAESIV | ( | uint8_t * | iv | ) |
Fetches the AES IV.
[in] | object | Pointer to copy iv to |
void HSMLPF3_getAESCMACSignMac | ( | uint8_t * | mac, |
uint8_t | macLength | ||
) |
Fetches the Final mac from result token.
[in] | mac | Buffer to copy mac to |
[in] | macLength | Length of the mac |
void HSMLPF3_constructCreateAssetToken | ( | uint64_t | assetPolicy, |
uint32_t | assetLength | ||
) |
Constructs an asset create command token.
[in] | assetPolicy | User's asset policy to create an asset |
[in] | assetLength | User's asset length to allocate on HSM RAM |
void HSMLPF3_constructLoadPlaintextAssetToken | ( | const uint8_t * | input_p, |
const uint32_t | inputLength, | ||
uint32_t | assetId | ||
) |
Constructs an asset load plaintext command token.
[in] | input_p | User's asset policy to create an asset |
[in] | inputLength | User's key material length which should be consistent with the key length passed during an asset create operation |
[in] | assetId | Asset ID to load the key material to on HSM RAM |
void HSMLPF3_constructDeleteAssetToken | ( | uint32_t | assetId | ) |
Constructs an asset delete command token.
[in] | assetId | Asset ID to load the key material to on HSM RAM |
void HSMLPF3_constructSHA2PhysicalToken | ( | SHA2LPF3HSM_Object * | object | ) |
Constructs a SHA2 onestep/segmented command token.
[in] | object | SHA2LPF3HSM object |
void HSMLPF3_constructECDSASignPhysicalToken | ( | ECDSALPF3HSM_Object * | object | ) |
Constructs a ECDSA sign/verify command token.
[in] | object | ECDSALPF3HSM object |
void HSMLPF3_constructECDHnumLoadPhysicalToken | ( | const uint8_t * | buffer, |
uint8_t | index, | ||
uint8_t | length | ||
) |
Constructs a ECDH num load command token.
[in] | buffer | Input data to load on to the HSM |
[in] | index | Input index to pass on to the HSM |
[in] | length | Input data length |
void HSMLPF3_constructECDHnumSetPhysicalToken | ( | uint8_t | length | ) |
Constructs a ECDH num set command token.
[in] | length | Curve length to notify the HSM about |
void HSMLPF3_constructECDHPKAOperationPhysicalToken | ( | uint8_t | operation, |
uint8_t * | input, | ||
uint8_t * | output, | ||
uint32_t | inputLength | ||
) |
Constructs a ECDH PK command token.
[in] | operation | Operation type |
[in] | input | Input data address |
[in] | output | Output data address |
[in] | inputLength | Input data length |
void HSMLPF3_constructAESGCMOneStepPhysicalToken | ( | AESGCMLPF3HSM_Object * | object | ) |
Constructs an AES-GCM one-step/segmented command token.
[in] | object | The AESGCMLPF3HSM object that contains necessary data |
void HSMLPF3_constructAESGCMSegmentedAADPhysicalToken | ( | AESGCMLPF3HSM_Object * | object | ) |
Populate the command token to reflect an AES-GCM segmented AAD operation.
[in] | object | The AESGCMLPF3HSM object that contains necessary data |
void HSMLPF3_constructAESGCMSegmentedDataPhysicalToken | ( | AESGCMLPF3HSM_Object * | object | ) |
Populate the command token to reflect an AES-GCM segmented or final data operation.
[in] | object | The AESGCMLPF3HSM object that contains necessary data |
void HSMLPF3_constructAESCCMOneStepPhysicalToken | ( | const AESCCMLPF3_Object * | object | ) |
Constructs an AES-CCM one-step/segmented command token.
[in] | object | The AESCCMLPF3HSM object that contains necessary data |
void HSMLPF3_constructAESCCMSegmentedAADPhysicalToken | ( | const AESCCMLPF3_Object * | object | ) |
Populate the command token to reflect an AES-CCM segmented AAD operation.
[in] | object | The AESCCMLPF3HSM object that contains necessary data |
void HSMLPF3_constructAESCCMSegmentedDataPhysicalToken | ( | const AESCCMLPF3_Object * | object | ) |
Populate the command token to reflect an AES-CCM segmented or final data operation.
[in] | object | The AESCCMLPF3HSM object that contains necessary data |
void HSMLPF3_constructAESECBOneStepPhysicalToken | ( | AESECBLPF3_Object * | object | ) |
Constructs an AES-ECB one-step command token.
[in] | object | The AESECBLPF3 object that contains necessary data |
void HSMLPF3_constructAESCTROneStepPhysicalToken | ( | AESCTRLPF3_Object * | object | ) |
Constructs an AES-CTR one-step command token.
[in] | object | The AESCTRLPF3 object that contains necessary data |
void HSMLPF3_constructAESCBCOneStepPhysicalToken | ( | AESCBCLPF3_Object * | object | ) |
void HSMLPF3_constructAESCMACOneStepPhysicalToken | ( | AESCMACLPF3_Object * | object | ) |
Constructs an AES-CMAC one-step command token.
[in] | object | The AESCMACLPF3 object that contains necessary data |
void HSMLPF3_constructAESCMACUpdatePhysicalToken | ( | AESCMACLPF3_Object * | object, |
bool | isInitWithDefault | ||
) |
Constructs an AES-CMAC update command token.
[in] | object | The AESCMACLPF3 object that contains necessary data |