HSMLPF3.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023-2024, 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/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>

#define HSMLPF3_STATUS_SUCCESS ((int_fast16_t)0)

#define HSMLPF3_STATUS_ERROR ((int_fast16_t)-1)

#define HSMLPF3_STATUS_TIMEOUT ((int_fast16_t)-2)

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;

#define AES_MODE_ENCRYPT 1U
#define AES_MODE_DECRYPT 0U

#define HSMLPF3_RETVAL_MASK MASK_8_BITS

void HSMLPF3_constructRTOSObjects(void);

void HSMLPF3_disableClock(void);

int_fast16_t HSMLPF3_sleep(void);

int_fast16_t HSMLPF3_init(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);

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

int32_t HSMLPF3_getResultCode(void);

uint32_t HSMLPF3_getResultAssetID(void);

void HSMLPF3_getResultDigest(uint32_t *digest, size_t digestLength);

void HSMLPF3_getAESEncryptTag(uint8_t *mac);

void HSMLPF3_getAESIV(uint8_t *iv);

void HSMLPF3_getAESCMACSignMac(uint8_t *mac, uint8_t macLength);

/*
 *  ================ 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_constructECDSASignPhysicalToken(ECDSALPF3HSM_Object *object);

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

void HSMLPF3_constructECDHnumSetPhysicalToken(uint8_t length);

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

void HSMLPF3_constructAESGCMOneStepPhysicalToken(AESGCMLPF3HSM_Object *object);

void HSMLPF3_constructAESGCMSegmentedAADPhysicalToken(AESGCMLPF3HSM_Object *object);

void HSMLPF3_constructAESGCMSegmentedDataPhysicalToken(AESGCMLPF3HSM_Object *object);

void HSMLPF3_constructAESCCMOneStepPhysicalToken(const AESCCMLPF3_Object *object);

void HSMLPF3_constructAESCCMSegmentedAADPhysicalToken(const AESCCMLPF3_Object *object);

void HSMLPF3_constructAESCCMSegmentedDataPhysicalToken(const AESCCMLPF3_Object *object);

void HSMLPF3_constructAESECBOneStepPhysicalToken(AESECBLPF3_Object *object);

void HSMLPF3_constructAESCTROneStepPhysicalToken(AESCTRLPF3_Object *object);

/*
 *  @brief  Constructs an AES-CBC one-step command token
 *
 *  @param  [in] object             The AESCBCLPF3 object that contains necessary data
 */
void HSMLPF3_constructAESCBCOneStepPhysicalToken(AESCBCLPF3_Object *object);

void HSMLPF3_constructAESCMACOneStepPhysicalToken(AESCMACLPF3_Object *object);

void HSMLPF3_constructAESCMACUpdatePhysicalToken(AESCMACLPF3_Object *object, bool isInitWithDefault);