HSMLPF3.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       HSMLPF3.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/SHA2LPF3HSM.h>

#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)
    #include <ti/drivers/EDDSA.h>
    #include <ti/drivers/eddsa/EDDSALPF3HSM.h>
#endif /* (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX) */

#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/ECDH.h>
#include <ti/drivers/ecdh/ECDHLPF3HSM.h>

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

#include <ti/drivers/TRNG.h>
#include <ti/drivers/trng/TRNGLPF3HSM.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 HSMLPF3_STATUS_SUCCESS ((int_fast16_t)0)

#define HSMLPF3_STATUS_ERROR ((int_fast16_t)-1)

#define HSMLPF3_STATUS_TIMEOUT ((int_fast16_t)-2)

#define HSMLPF3_STATUS_IN_SLEEP_MODE ((int_fast16_t)-3)

#define HSMLPF3_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-4)

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

/* Default TRNG parameters */
#define HSMLPF3_RNG_CONFG_TRNG_DEFAULT_AUTOSEED           0xFF
#define HSMLPF3_RNG_CONFG_TRNG_DEFAULT_SAMPLE_CYCLE       0x4BBE
#define HSMLPF3_RNG_CONFG_TRNG_MAX_SAMPLE_CYCLE           0x00
#define HSMLPF3_RNG_CONFG_DEFAULT_NOISEBLOCKS             0x01
#define HSMLPF3_RNG_CONFG_TRNG_DEFAULT_SCALE              0x01
#define HSMLPF3_RNG_CONFG_TRNG_DEFAULT_SAMPLEDIV          0x00
#define HSMLPF3_RNG_CONFG_TRNG_DEFAULT_REPCNTCUTOFF       0x09
#define HSMLPF3_RNG_CONFG_TRNG_DEFAULT_ADAPTPROP64CUTOFF  0x15
#define HSMLPF3_RNG_CONFG_TRNG_DEFAULT_ADAPTPROP512CUTOFF 0x47

/* Default CRNG parameters */
#define HSMLPF3_RNG_CONFG_CRNG_DEFAULT_AUTOSEED 0x1
#define HSMLPF3_RNG_CONFG_CRNG_DEFAULT_MIXCYCLE 0x2

#define HSMLPF3_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
{
    HSMLPF3_MODE_CRNG = 1,
    HSMLPF3_MODE_TRNG = 2,
} HSMLPF3_NRBGMode;

typedef enum
{
    HSMLPF3_RETURN_BEHAVIOR_CALLBACK = 1, 
    HSMLPF3_RETURN_BEHAVIOR_BLOCKING = 2, 
    HSMLPF3_RETURN_BEHAVIOR_POLLING = 4, 
} HSMLPF3_ReturnBehavior;

typedef void (*HSMLPF3_CallbackFxn)(uintptr_t arg0);

typedef struct
{
    Eip130Token_Command_t commandToken;
    Eip130Token_Result_t resultToken;
    HSMLPF3_ReturnBehavior returnBehavior;
    HSMLPF3_CallbackFxn callbackFxn;
    uintptr_t driverHandle;
} HSMLPF3_Operation;

void HSMLPF3_constructRTOSObjects(void);

void HSMLPF3_disableClock(void);

int_fast16_t HSMLPF3_sleep(void);

int_fast16_t HSMLPF3_wakeUp(void);

int_fast16_t HSMLPF3_init(void);

int_fast16_t HSMLPF3_provisionHUK(void);

bool HSMLPF3_acquireLock(uint32_t timeout, uintptr_t driverHandle);

void HSMLPF3_releaseLock(void);

int_fast16_t HSMLPF3_submitToken(HSMLPF3_ReturnBehavior retBehavior,
                                 HSMLPF3_CallbackFxn callbackFxn,
                                 uintptr_t driverHandle);

int_fast16_t HSMLPF3_waitForResult(void);

int_fast16_t HSMLPF3_cancelOperation(void);

bool HSMLPF3_isOperationInProgress(void);

HSMLPF3_NRBGMode HSMLPF3_getCurrentNRBGMode(void);

void HSMLPF3_updateInternalNRBGMode();

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

int32_t HSMLPF3_getResultCode(void);

uint32_t HSMLPF3_getResultAssetID(void);

void HSMLPF3_getResultDigest(uint8_t *digest, size_t digestLength);

void HSMLPF3_getAESEncryptTag(void *mac, size_t macLength);

void HSMLPF3_getAESIV(uint8_t *iv);

void HSMLPF3_getAESCMACSignMac(uint8_t *mac, uint8_t macLength);

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

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

void HSMLPF3_constructCreateAssetToken(uint64_t assetPolicy, uint32_t assetLength);

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

void HSMLPF3_constructDeleteAssetToken(uint32_t assetId);

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

void HSMLPF3_constructECDHGenPubPhysicalToken(ECDHLPF3HSM_Object *object);

void HSMLPF3_constructECDHGenShrdSecPhysicalToken(ECDHLPF3HSM_Object *object);

void HSMLPF3_constructECDHVerifyKeysPhysicalToken(ECDHLPF3HSM_Object *object);

void HSMLPF3_constructECDSASignPhysicalToken(ECDSALPF3HSM_Object *object);

#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)

void HSMLPF3_constructEDDSAGenPubKeyPhysicalToken(EDDSALPF3HSM_Object *object);

void HSMLPF3_constructEDDSASignInitialPhysicalToken(EDDSALPF3HSM_Object *object);

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

void HSMLPF3_constructEDDSASignUpdatePhysicalToken(EDDSALPF3HSM_Object *object);

void HSMLPF3_constructEDDSASignFinalizePhysicalToken(EDDSALPF3HSM_Object *object);

void HSMLPF3_constructEDDSAVerifyInitialPhysicalToken(EDDSALPF3HSM_Object *object);

void HSMLPF3_constructEDDSAVerifyFinalizePhysicalToken(EDDSALPF3HSM_Object *object);
#endif /* (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX) */

void HSMLPF3_constructGCMToken(const AESGCMLPF3HSM_Object *object, bool saveIV, bool loadIV);

void HSMLPF3_constructCCMToken(const AESCCMLPF3_Object *object, bool saveIV, bool loadIV);

void HSMLPF3_constructAESECBOneStepPhysicalToken(AESECBLPF3_Object *object, uint8_t *key);

void HSMLPF3_constructAESCTROneStepPhysicalToken(AESCTRLPF3_Object *object, uint8_t *key);

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

void HSMLPF3_constructCMACToken(AESCMACLPF3_Object *object, bool isFirst, bool isFinal);

#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)

void HSMLPF3_constructRNGSwitchNRBGWithDefaultsPhysicalToken(HSMLPF3_NRBGMode HSMLPF3_nrbgMode);

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

void HSMLPF3_constructRNGGetRandomNumberPhysicalToken(uintptr_t entropyBuffer, size_t entropyRequested);

void HSMLPF3_constructRNGGetRawRandomNumberPhysicalToken(uintptr_t entropyBuffer, size_t entropyRequested);