HSMXXF3.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023-2025, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*!****************************************************************************
 *  @file       HSMXXF3.h
 *
 *  @brief      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/devices/DeviceFamily.h>
#include <ti/drivers/SHA2.h>
#include <ti/drivers/sha2/SHA2XXF3HSM.h>

#include <ti/drivers/AESGCM.h>
#include <ti/drivers/aesgcm/AESGCMXXF3HSM.h>

#include <ti/drivers/AESECB.h>
#include <ti/drivers/aesecb/AESECBXXF3.h>

#include <ti/drivers/AESCTR.h>
#include <ti/drivers/aesctr/AESCTRXXF3.h>

#include <ti/drivers/AESCBC.h>
#include <ti/drivers/aescbc/AESCBCXXF3.h>

#include <ti/drivers/AESCMAC.h>
#include <ti/drivers/aescmac/AESCMACXXF3.h>

#include <ti/drivers/AESCCM.h>
#include <ti/drivers/aesccm/AESCCMXXF3.h>

#include <ti/drivers/ECDH.h>
#include <ti/drivers/ecdh/ECDHXXF3HSM.h>

#include <ti/drivers/ECDSA.h>
#include <ti/drivers/ecdsa/ECDSAXXF3HSM.h>

#include <ti/drivers/EDDSA.h>
#include <ti/drivers/eddsa/EDDSAXXF3HSM.h>

#include <ti/drivers/TRNG.h>
#include <ti/drivers/trng/TRNGXXF3HSM.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>

#define HSMXXF3_STATUS_SUCCESS ((int_fast16_t)0)

#define HSMXXF3_STATUS_ERROR ((int_fast16_t)-1)

#define HSMXXF3_STATUS_TIMEOUT ((int_fast16_t)-2)

#define HSMXXF3_STATUS_IN_SLEEP_MODE ((int_fast16_t)-3)

#define HSMXXF3_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-4)

/* Co-processor ID for LAES */
#define HSMXXF3_LAES_COPROCESSOR_ID 0x1

/* The following defines are the default RNG configuration parameters */

/* Default TRNG parameters */
#define HSMXXF3_RNG_CONFG_TRNG_DEFAULT_AUTOSEED           0xFF
#define HSMXXF3_RNG_CONFG_TRNG_DEFAULT_SAMPLE_CYCLE       0x4BBE
#define HSMXXF3_RNG_CONFG_TRNG_MAX_SAMPLE_CYCLE           0x00
#define HSMXXF3_RNG_CONFG_DEFAULT_NOISEBLOCKS             0x01
#define HSMXXF3_RNG_CONFG_TRNG_DEFAULT_SCALE              0x01
#define HSMXXF3_RNG_CONFG_TRNG_DEFAULT_SAMPLEDIV          0x00
#define HSMXXF3_RNG_CONFG_TRNG_DEFAULT_REPCNTCUTOFF       0x09
#define HSMXXF3_RNG_CONFG_TRNG_DEFAULT_ADAPTPROP64CUTOFF  0x15
#define HSMXXF3_RNG_CONFG_TRNG_DEFAULT_ADAPTPROP512CUTOFF 0x47

/* Default CRNG parameters */
#define HSMXXF3_RNG_CONFG_CRNG_DEFAULT_AUTOSEED 0x1
#define HSMXXF3_RNG_CONFG_CRNG_DEFAULT_MIXCYCLE 0x2

#define HSMXXF3_RETVAL_MASK MASK_8_BITS

#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC35XX)
    /* Power state defines from LPF3 to WFF3 mapping. */
    #define PowerLPF3_ENTERING_STANDBY PowerWFF3_ENTERING_SLEEP
    #define PowerLPF3_AWAKE_STANDBY    PowerWFF3_AWAKE_SLEEP
    #define PowerLPF3_DISALLOW_STANDBY PowerWFF3_DISALLOW_SLEEP
#endif

typedef enum
{
    HSMXXF3_MODE_CRNG = 1,
    HSMXXF3_MODE_TRNG = 2,
} HSMXXF3_NRBGMode;

typedef enum
{
    HSMXXF3_RETURN_BEHAVIOR_CALLBACK = 1, 
    HSMXXF3_RETURN_BEHAVIOR_BLOCKING = 2, 
    HSMXXF3_RETURN_BEHAVIOR_POLLING = 4, 
} HSMXXF3_ReturnBehavior;

typedef void (*HSMXXF3_CallbackFxn)(uintptr_t arg0);

typedef struct
{
    Eip130Token_Command_t commandToken;
    Eip130Token_Result_t resultToken;
    HSMXXF3_ReturnBehavior returnBehavior;
    HSMXXF3_CallbackFxn callbackFxn;
    uintptr_t driverHandle;
} HSMXXF3_Operation;

void HSMXXF3_constructRTOSObjects(void);

void HSMXXF3_disableClock(void);

int_fast16_t HSMXXF3_sleep(void);

int_fast16_t HSMXXF3_wakeUp(void);

int_fast16_t HSMXXF3_init(void);

bool HSMXXF3_isStandaloneDMASupportEnabled(void);

int_fast16_t HSMXXF3_provisionHUK(void);

bool HSMXXF3_acquireLock(uint32_t timeout, uintptr_t driverHandle);

void HSMXXF3_releaseLock(void);

int_fast16_t HSMXXF3_submitToken(HSMXXF3_ReturnBehavior retBehavior,
                                 HSMXXF3_CallbackFxn callbackFxn,
                                 uintptr_t driverHandle);

int_fast16_t HSMXXF3_waitForResult(void);

int_fast16_t HSMXXF3_cancelOperation(void);

bool HSMXXF3_isOperationInProgress(void);

HSMXXF3_NRBGMode HSMXXF3_getCurrentNRBGMode(void);

void HSMXXF3_updateInternalNRBGMode();

/*
 *  ================ APIs to handle result token data ================
 */

int32_t HSMXXF3_getResultCode(void);

uint32_t HSMXXF3_getResultAssetID(void);

void HSMXXF3_getResultDigest(uint8_t *digest, size_t digestLength);

void HSMXXF3_getAESEncryptTag(void *mac, size_t macLength);

void HSMXXF3_getAESIV(uint8_t *iv);

void HSMXXF3_getAESCMACSignMac(uint8_t *mac, uint8_t macLength);

void HSMXXF3_getPublicDataRead(uint32_t assetId, const uint8_t *data, uint8_t dataLength);

/*
 *  ================ APIs to construct key/asset management-related command tokens ================
 */

void HSMXXF3_constructCreateAssetToken(uint64_t assetPolicy, uint32_t assetLength);

void HSMXXF3_constructLoadPlaintextAssetToken(const uint8_t *input_p, const uint32_t inputLength, uint32_t assetId);

void HSMXXF3_constructDeleteAssetToken(uint32_t assetId);

int_fast16_t HSMXXF3_constructExportAssetCopToken(uint32_t assetId, uint16_t copID, uint16_t copOffset);

/*
 *  ================ APIs to construct driver-specific command tokens ================
 */
void HSMXXF3_constructSHA2PhysicalToken(SHA2XXF3HSM_Object *object);

void HSMXXF3_constructECDHGenPubPhysicalToken(ECDHXXF3HSM_Object *object);

void HSMXXF3_constructECDHGenShrdSecPhysicalToken(ECDHXXF3HSM_Object *object);

void HSMXXF3_constructECDHVerifyKeysPhysicalToken(ECDHXXF3HSM_Object *object);

void HSMXXF3_constructECDSAPhysicalToken(ECDSAXXF3HSM_Object *object);

void HSMXXF3_constructEDDSAGenPubKeyPhysicalToken(EDDSAXXF3HSM_Object *object);

void HSMXXF3_constructEDDSASignInitialPhysicalToken(EDDSAXXF3HSM_Object *object);

void HSMXXF3_constructEDDSAIntermediateHashPhysicalToken(const uint8_t *input,
                                                         size_t inputLength,
                                                         uint32_t tempAssetID);

void HSMXXF3_constructEDDSASignUpdatePhysicalToken(EDDSAXXF3HSM_Object *object);

void HSMXXF3_constructEDDSASignFinalizePhysicalToken(EDDSAXXF3HSM_Object *object);

void HSMXXF3_constructEDDSAVerifyInitialPhysicalToken(EDDSAXXF3HSM_Object *object);

void HSMXXF3_constructEDDSAVerifyFinalizePhysicalToken(EDDSAXXF3HSM_Object *object);

void HSMXXF3_constructGCMToken(const AESGCMXXF3HSM_Object *object, bool saveIV, bool loadIV);

void HSMXXF3_constructCCMToken(const AESCCMXXF3_Object *object, bool saveIV, bool loadIV);

void HSMXXF3_constructAESECBOneStepPhysicalToken(AESECBXXF3_Object *object, uint8_t *key);

void HSMXXF3_constructAESCTROneStepPhysicalToken(AESCTRXXF3_Object *object, uint8_t *key);

/*
 *  @brief  Constructs an AES-CBC one-step command token
 *
 *  @param  [in] object             The AESCBCXXF3 object that contains necessary data
 *  @param  [in] key                Pointer to key material if it has been retrieved in plaintext
 */
void HSMXXF3_constructAESCBCOneStepPhysicalToken(AESCBCXXF3_Object *object, uint8_t *key);

void HSMXXF3_constructCMACToken(AESCMACXXF3_Object *object, bool isFirst, bool isFinal);

#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)

void HSMXXF3_constructRNGSwitchNRBGWithDefaultsPhysicalToken(HSMXXF3_NRBGMode HSMXXF3_nrbgMode);

void HSMXXF3_constructRNGReseedDRBGPhysicalToken(void);
#endif /* (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX) */

void HSMXXF3_constructRNGGetRandomNumberPhysicalToken(uintptr_t entropyBuffer, size_t entropyRequested);

void HSMXXF3_constructRNGGetRawRandomNumberPhysicalToken(uintptr_t entropyBuffer, size_t entropyRequested);