Data Structures | Macros | Typedefs | Enumerations | Functions
HSMLPF3.h File Reference

Detailed Description

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>
Include dependency graph for HSMLPF3.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...
 

Macro Definition Documentation

§ HSMLPF3_STATUS_SUCCESS

#define HSMLPF3_STATUS_SUCCESS   ((int_fast16_t)0)

Successful status code.

Functions return HSMLPF3_STATUS_SUCCESS if the function was executed successfully.

§ HSMLPF3_STATUS_ERROR

#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.

§ HSMLPF3_STATUS_TIMEOUT

#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.

§ AES_MODE_ENCRYPT

#define AES_MODE_ENCRYPT   1U

§ AES_MODE_DECRYPT

#define AES_MODE_DECRYPT   0U

§ HSMLPF3_RETVAL_MASK

#define HSMLPF3_RETVAL_MASK   MASK_8_BITS

Typedef Documentation

§ HSMLPF3_CallbackFxn

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.

Enumeration Type Documentation

§ HSMLPF3_ReturnBehavior

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.

Function Documentation

§ HSMLPF3_constructRTOSObjects()

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.

Postcondition
HSMLPF3_init()

§ HSMLPF3_disableClock()

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.

§ HSMLPF3_sleep()

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.

Precondition
HSMLPF3_init() has to be called first.
Return values
HSMLPF3_STATUS_SUCCESSHSM put to sleep successfully.
HSMLPF3_STATUS_ERRORError. Error output token, or HSM in bad state.

§ HSMLPF3_init()

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.

Precondition
HSMLPF3_constructRTOSObjects()
Postcondition
HSMLPF3_acquireLock()
Return values
HSMLPF3_STATUS_SUCCESSHSM booted and initialized successfully.
HSMLPF3_STATUS_ERRORError. Failed boot or mailbox initiailization.

§ HSMLPF3_acquireLock()

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.

Parameters
[in]timeoutAmount of time to wait for semaphore to be posted.
[in]driverHandleThe driver's handle.
Precondition
HSMLPF3_init() has to be called first.
Postcondition
HSMLPF3_submitToken()
Return values
ReturnsTrue on success, False on timeout

§ HSMLPF3_releaseLock()

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.

Precondition
HSMLPF3_init() has to be called first.

§ HSMLPF3_submitToken()

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().

Parameters
[in]retBehaviorDriver's return behavior for use in HSMLPF3_waitForResult().
[in]callbackFxnPointer 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]driverHandleThe driver's handle.
Precondition
HSMLPF3_acquireLock() has to be successfully called first.
Postcondition
HSMLPF3_waitForResult()
Return values
HSMLPF3_STATUS_SUCCESSToken successfully written to HSM mailbox.
HSMLPF3_STATUS_ERRORError. Invalid token or unsuccessful write to mailbox.

§ HSMLPF3_waitForResult()

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.

Precondition
HSMLPF3_submitToken() has to be called first.
Return values
HSMLPF3_STATUS_SUCCESSSuccessfully waited for the result.
HSMLPF3_STATUS_ERRORError. Provided return behavior invalid.

§ HSMLPF3_cancelOperation()

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.

Return values
HSMLPF3_STATUS_SUCCESSSuccessfully canceled operation in progress.
HSMLPF3_STATUS_ERRORError.

§ HSMLPF3_isOperationInProgress()

bool HSMLPF3_isOperationInProgress ( void  )

returns the value of HSMLPF3_operationInProgress

Return values
trueOperation in progress
falseNo operation in progress

§ HSMLPF3_getResultCode()

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.

Return values
Resulttoken return code.

§ HSMLPF3_getResultAssetID()

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.

Return values
AssetIdentification Number

§ HSMLPF3_getResultDigest()

void HSMLPF3_getResultDigest ( uint32_t *  digest,
size_t  digestLength 
)

Copies a hash operation's digest to user space.

Parameters
[in]digestUser specified destination address
[in]digestLengthUser's digest length

§ HSMLPF3_getAESEncryptTag()

void HSMLPF3_getAESEncryptTag ( uint8_t *  mac)

Fetches the AES tag.

Parameters
[in]objectPointer to copy tag to

§ HSMLPF3_getAESIV()

void HSMLPF3_getAESIV ( uint8_t *  iv)

Fetches the AES IV.

Parameters
[in]objectPointer to copy iv to

§ HSMLPF3_getAESCMACSignMac()

void HSMLPF3_getAESCMACSignMac ( uint8_t *  mac,
uint8_t  macLength 
)

Fetches the Final mac from result token.

Parameters
[in]macBuffer to copy mac to
[in]macLengthLength of the mac

§ HSMLPF3_constructCreateAssetToken()

void HSMLPF3_constructCreateAssetToken ( uint64_t  assetPolicy,
uint32_t  assetLength 
)

Constructs an asset create command token.

Parameters
[in]assetPolicyUser's asset policy to create an asset
[in]assetLengthUser's asset length to allocate on HSM RAM

§ HSMLPF3_constructLoadPlaintextAssetToken()

void HSMLPF3_constructLoadPlaintextAssetToken ( const uint8_t *  input_p,
const uint32_t  inputLength,
uint32_t  assetId 
)

Constructs an asset load plaintext command token.

Precondition
A successfully conducted asset creation operation that returned an assetID.
Parameters
[in]input_pUser's asset policy to create an asset
[in]inputLengthUser's key material length which should be consistent with the key length passed during an asset create operation
[in]assetIdAsset ID to load the key material to on HSM RAM

§ HSMLPF3_constructDeleteAssetToken()

void HSMLPF3_constructDeleteAssetToken ( uint32_t  assetId)

Constructs an asset delete command token.

Parameters
[in]assetIdAsset ID to load the key material to on HSM RAM
Precondition
A successfully conducted asset creation operation that returned an assetID.

§ HSMLPF3_constructSHA2PhysicalToken()

void HSMLPF3_constructSHA2PhysicalToken ( SHA2LPF3HSM_Object *  object)

Constructs a SHA2 onestep/segmented command token.

Parameters
[in]objectSHA2LPF3HSM object

§ HSMLPF3_constructECDSASignPhysicalToken()

void HSMLPF3_constructECDSASignPhysicalToken ( ECDSALPF3HSM_Object object)

Constructs a ECDSA sign/verify command token.

Parameters
[in]objectECDSALPF3HSM object

§ HSMLPF3_constructECDHnumLoadPhysicalToken()

void HSMLPF3_constructECDHnumLoadPhysicalToken ( const uint8_t *  buffer,
uint8_t  index,
uint8_t  length 
)

Constructs a ECDH num load command token.

Parameters
[in]bufferInput data to load on to the HSM
[in]indexInput index to pass on to the HSM
[in]lengthInput data length

§ HSMLPF3_constructECDHnumSetPhysicalToken()

void HSMLPF3_constructECDHnumSetPhysicalToken ( uint8_t  length)

Constructs a ECDH num set command token.

Parameters
[in]lengthCurve length to notify the HSM about

§ HSMLPF3_constructECDHPKAOperationPhysicalToken()

void HSMLPF3_constructECDHPKAOperationPhysicalToken ( uint8_t  operation,
uint8_t *  input,
uint8_t *  output,
uint32_t  inputLength 
)

Constructs a ECDH PK command token.

Parameters
[in]operationOperation type
[in]inputInput data address
[in]outputOutput data address
[in]inputLengthInput data length

§ HSMLPF3_constructAESGCMOneStepPhysicalToken()

void HSMLPF3_constructAESGCMOneStepPhysicalToken ( AESGCMLPF3HSM_Object object)

Constructs an AES-GCM one-step/segmented command token.

Parameters
[in]objectThe AESGCMLPF3HSM object that contains necessary data

§ HSMLPF3_constructAESGCMSegmentedAADPhysicalToken()

void HSMLPF3_constructAESGCMSegmentedAADPhysicalToken ( AESGCMLPF3HSM_Object object)

Populate the command token to reflect an AES-GCM segmented AAD operation.

Parameters
[in]objectThe AESGCMLPF3HSM object that contains necessary data

§ HSMLPF3_constructAESGCMSegmentedDataPhysicalToken()

void HSMLPF3_constructAESGCMSegmentedDataPhysicalToken ( AESGCMLPF3HSM_Object object)

Populate the command token to reflect an AES-GCM segmented or final data operation.

Parameters
[in]objectThe AESGCMLPF3HSM object that contains necessary data

§ HSMLPF3_constructAESCCMOneStepPhysicalToken()

void HSMLPF3_constructAESCCMOneStepPhysicalToken ( const AESCCMLPF3_Object object)

Constructs an AES-CCM one-step/segmented command token.

Parameters
[in]objectThe AESCCMLPF3HSM object that contains necessary data

§ HSMLPF3_constructAESCCMSegmentedAADPhysicalToken()

void HSMLPF3_constructAESCCMSegmentedAADPhysicalToken ( const AESCCMLPF3_Object object)

Populate the command token to reflect an AES-CCM segmented AAD operation.

Parameters
[in]objectThe AESCCMLPF3HSM object that contains necessary data

§ HSMLPF3_constructAESCCMSegmentedDataPhysicalToken()

void HSMLPF3_constructAESCCMSegmentedDataPhysicalToken ( const AESCCMLPF3_Object object)

Populate the command token to reflect an AES-CCM segmented or final data operation.

Parameters
[in]objectThe AESCCMLPF3HSM object that contains necessary data

§ HSMLPF3_constructAESECBOneStepPhysicalToken()

void HSMLPF3_constructAESECBOneStepPhysicalToken ( AESECBLPF3_Object object)

Constructs an AES-ECB one-step command token.

Parameters
[in]objectThe AESECBLPF3 object that contains necessary data

§ HSMLPF3_constructAESCTROneStepPhysicalToken()

void HSMLPF3_constructAESCTROneStepPhysicalToken ( AESCTRLPF3_Object object)

Constructs an AES-CTR one-step command token.

Parameters
[in]objectThe AESCTRLPF3 object that contains necessary data

§ HSMLPF3_constructAESCBCOneStepPhysicalToken()

void HSMLPF3_constructAESCBCOneStepPhysicalToken ( AESCBCLPF3_Object object)

§ HSMLPF3_constructAESCMACOneStepPhysicalToken()

void HSMLPF3_constructAESCMACOneStepPhysicalToken ( AESCMACLPF3_Object object)

Constructs an AES-CMAC one-step command token.

Parameters
[in]objectThe AESCMACLPF3 object that contains necessary data

§ HSMLPF3_constructAESCMACUpdatePhysicalToken()

void HSMLPF3_constructAESCMACUpdatePhysicalToken ( AESCMACLPF3_Object object,
bool  isInitWithDefault 
)

Constructs an AES-CMAC update command token.

Parameters
[in]objectThe AESCMACLPF3 object that contains necessary data
© Copyright 1995-2024, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale