Interface to The HSM IP in a BareMetal-based implementation. More...

Data Structures
struct	HSMBareMetal_AESOperationStruct
	Struct containing the parameters required for AES operations. More...

struct	HSMBareMetal_AssetOperationStruct
	Struct containing the parameters required for asset create and plaintext key load operations. More...

struct	HSMBareMetal_AssetPairKeyBlobStruct
	Struct containing the two buffers for symmetric key blob data. More...

struct	HSMBareMetal_AssetPairStruct
	Struct containing the two asset IDs returned for usage in a symmetric operation. More...

struct	HSMBareMetal_AsymAssetPairStruct
	Struct containing the two asset IDs returned for ECC operations. More...

struct	HSMBareMetal_CryptoKeyAssetStoreStruct
	Struct containing the AssetStore-based crypto key data. More...

struct	HSMBareMetal_CryptoKeyPlaintextStruct
	Struct containing the Plaintext-based crypto key data. More...

struct	HSMBareMetal_CryptoKeyStruct
	Struct containing the parameters required for AES operations. More...

struct	HSMBareMetal_ECCOperationStruct
	Struct containing the parameters required for ECC operations. More...

struct	HSMBareMetal_HASHOperationStruct
	Struct containing the parameters required for Hash operations. More...

struct	HSMBareMetal_MACOperationStruct
	Struct containing the parameters required for MAC operations. More...

struct	HSMBareMetal_RNGOperationStruct
	Struct containing the parameters required for RNG operations. More...

struct	HSMBareMetal_systemInfoVersionStruct
	Struct to store HSM system versions. More...

Macros
#define	HSM_KEYBLOB_SIZE(keyLength) (HSMBAREMETAL_AES_BLOCK_SIZE + keyLength)
	The expected size of an AES-SIV keyblob. More...

#define	HSMBAREMETAL_AES_BLOCK_SIZE 16
	The size of an HSM block for symmetric operations.

#define	HSMBAREMETAL_HUK_ASSET_NUMBER 0x61
	The Hardware Unique key (HUK) asset number in the HSM.

#define	HSMBAREMETAL_STATUS_ERROR ((int_fast16_t)-1)
	Generic error status code. More...

#define	HSMBAREMETAL_STATUS_FEATURE_NOT_SUPPORTED ((int_fast16_t)-13)
	The combination of parameters passed filtered to a feature that exists but is not supported yet.

#define	HSMBAREMETAL_STATUS_HSM_ALREADY_INITIALIZED ((int_fast16_t)-4)
	HSM IP is already initialized.

#define	HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED ((int_fast16_t)-2)
	HSM IP has not been initialized yet. Call HSMBareMetal_init()

#define	HSMBAREMETAL_STATUS_HUK_ALREADY_PROVISIONED ((int_fast16_t)-12)
	This device has already been provisioned with a Hardware Unique Key (HUK).

#define	HSMBAREMETAL_STATUS_HW_ERROR ((int_fast16_t)-3)
	HSM IP reported a Hardware error. This renders the IP non-functional. More...

#define	HSMBAREMETAL_STATUS_INVALID_INPUT_DATA_LENGTH ((int_fast16_t)-14)
	The input data length is not block aligned.

#define	HSMBAREMETAL_STATUS_INVALID_INPUT_PARAMETERS ((int_fast16_t)-6)
	One or more of the provided parameter(s) do not match the supported features.

#define	HSMBAREMETAL_STATUS_INVALID_MAC ((int_fast16_t)-5)
	The MAC verification failed. More...

#define	HSMBAREMETAL_STATUS_INVALID_MAC_LENGTH ((int_fast16_t)-15)
	The mac length is invalid.

#define	HSMBAREMETAL_STATUS_INVALID_PRIVATE_KEY_SIZE ((int_fast16_t)-8)
	Private key size is invalid.

#define	HSMBAREMETAL_STATUS_INVALID_PUBLIC_KEY_OCTET_VALUE ((int_fast16_t)-10)
	The public key's first byte is an invalid value.

#define	HSMBAREMETAL_STATUS_INVALID_PUBLIC_KEY_SIZE ((int_fast16_t)-9)
	Public key size is invalid.

#define	HSMBAREMETAL_STATUS_INVALID_SHARED_SECRET_KEY_SIZE ((int_fast16_t)-11)
	Shared secret key size is invalid.

#define	HSMBAREMETAL_STATUS_NRBG_ALREADY_IN_MODE ((int_fast16_t)-7)
	the NRBG engine is already in mode.

#define	HSMBAREMETAL_STATUS_SUCCESS ((int_fast16_t)0)
	Successful status code. More...

#define	HSMBareMetal_WAIT_FOREVER ~(0)
	Wait forever for a result token define.

Enumerations
enum	HSMBareMetal_AESOperationMode { HSMBareMetal_AES_MODE_ECB = 0, HSMBareMetal_AES_MODE_CBC = 1, HSMBareMetal_AES_MODE_CTR = 2, HSMBareMetal_AES_MODE_CCM = 5, HSMBareMetal_AES_MODE_GCM = 7 }
	Enum for AES operation modes.

enum	HSMBareMetal_AssetOperationType { HSMBareMetal_ASSET_OPERATION_TYPE_LOAD_PLAINTEXT = 0, HSMBareMetal_ASSET_OPERATION_TYPE_LOAD_IMPORT_KEY_BLOB = 1, HSMBareMetal_ASSET_OPERATION_TYPE_LOAD_EXPORT_KEY_BLOB = 2 }
	Enum for the Asset operation type.

enum	HSMBareMetal_ECCOperationCurveLength { HSMBareMetal_PK_CURVE_LENGTH_224 = 224, HSMBareMetal_PK_CURVE_LENGTH_255 = 255, HSMBareMetal_PK_CURVE_LENGTH_256 = 256, HSMBareMetal_PK_CURVE_LENGTH_384 = 384, HSMBareMetal_PK_CURVE_LENGTH_512 = 512, HSMBareMetal_PK_CURVE_LENGTH_521 = 521 }
	Enum for ECC operation curve lengths.

enum	HSMBareMetal_ECCOperationCurveType { HSMBareMetal_PK_CURVE_TYPE_SEC_P_224_R1 = 1, HSMBareMetal_PK_CURVE_TYPE_SEC_P_256_R1 = 2, HSMBareMetal_PK_CURVE_TYPE_SEC_P_384_R1 = 3, HSMBareMetal_PK_CURVE_TYPE_SEC_P_521_R1 = 4, HSMBareMetal_PK_CURVE_TYPE_BRP_P_256_R1 = 5, HSMBareMetal_PK_CURVE_TYPE_BRP_P_384_R1 = 6, HSMBareMetal_PK_CURVE_TYPE_BRP_P_512_R1 = 7, HSMBareMetal_PK_CURVE_TYPE_25519 = 8 }
	Enum for ECC operation curve types.

enum	HSMBareMetal_ECCOperationDigestLength { HSMBareMetal_PK_DIGEST_LENGTH_224 = 224, HSMBareMetal_PK_DIGEST_LENGTH_256 = 256, HSMBareMetal_PK_DIGEST_LENGTH_384 = 384, HSMBareMetal_PK_DIGEST_LENGTH_512 = 512 }
	Enum for ECC operation digest lengths.

enum	HSMBareMetal_ECCOperationMode { HSMBareMetal_PK_MODE_ECDH_GEN_PUB_KEY = 1, HSMBareMetal_PK_MODE_ECDH_GEN_SHRD_SCRT = 2, HSMBareMetal_PK_MODE_ECDSA_SIGN = 3, HSMBareMetal_PK_MODE_ECDSA_VERIFY = 4 }
	Enum for ECC operation modes.

enum	HSMBareMetal_entropyType { ENTROPY_TYPE_DRBG = 0x0000, ENTROPY_TYPE_CRNG = 0x7264, ENTROPY_TYPE_TRNG = 0x5244 }
	Enum for entropy type. More...

enum	HSMBareMetal_HASHOperationMode { HSMBareMetal_HASH_MODE_SHA2_224 = 2, HSMBareMetal_HASH_MODE_SHA2_256 = 3, HSMBareMetal_HASH_MODE_SHA2_384 = 4, HSMBareMetal_HASH_MODE_SHA2_512 = 5 }
	Enum for Hash operation modes (algorithms).

enum	HSMBareMetal_HASHOperationType { HSMBareMetal_HASH_TYPE_INIT_TO_FINAL = 0, HSMBareMetal_HASH_TYPE_CONT_TO_FINAL = 1, HSMBareMetal_HASH_TYPE_INIT_TO_CONT = 2, HSMBareMetal_HASH_TYPE_CONT_TO_CONT = 3 }
	Enum for Hash operation types (hash mode).

enum	HSMBareMetal_KeyInput { HSMBareMetal_KEY_INPUT_PLAINTEXT = 0, HSMBareMetal_KEY_INPUT_ASSETSTORE = 1 }
	Enum for the AES operation mode.

enum	HSMBareMetal_MACOperationMode { HSMBareMetal_MAC_MODE_HMAC_224 = 2, HSMBareMetal_MAC_MODE_HMAC_256 = 3, HSMBareMetal_MAC_MODE_HMAC_384 = 4, HSMBareMetal_MAC_MODE_HMAC_512 = 5, HSMBareMetal_MAC_MODE_CMAC = 8, HSMBareMetal_MAC_MODE_CBC_MAC = 9 }
	Enum for the MAC operation mode.

enum	HSMBareMetal_NRBGMode { NRBG_TYPE_CRNG = 1, NRBG_TYPE_TRNG = 0 }
	Enum for the current NRBG IP for the HSM to pull entropy from. More...

enum	HSMBareMetal_operationAlgorithm { HSMBareMetal_OPERATION_ALGO_AES = 1, HSMBareMetal_OPERATION_ALGO_MAC = 2, HSMBareMetal_OPERATION_ALGO_HASH = 3, HSMBareMetal_OPERATION_ALGO_ECC = 4 }
	Enum for operation algorithm. More...

enum	HSMBareMetal_operationDirection { HSMBareMetal_OPERATION_DIR_ENC_GEN = 1, HSMBareMetal_OPERATION_DIR_DEC_VRFY = 2 }
	Enum for the direction of an AES operation. More...

Functions
int_fast16_t	HSMBareMetal_AESOperation (HSMBareMetal_AESOperationStruct *operationStruct)
	Perform a Bare Metal AES Operation. More...

void	HSMBareMetal_AESOperation_init (HSMBareMetal_AESOperationStruct *operationStruct)
	Function to initialize an HSMBareMetal_AESOperation struct to its default (all zeroes)

int_fast16_t	HSMBareMetal_AssetOperation (HSMBareMetal_AssetOperationStruct *operationStruct)
	Perform a Bare Metal Asset Create and Load Operations. More...

void	HSMBareMetal_AssetOperation_init (HSMBareMetal_AssetOperationStruct *operationStruct)
	Function to initialize an HSMBareMetal_AssetOperation struct to its default (all zeroes)

int_fast16_t	HSMBareMetal_checkHSMStatus (void)
	Check HSM HW status. More...

void	HSMBareMetal_CryptoKeyPlaintext_initKey (HSMBareMetal_CryptoKeyStruct cryptoKey, uint8_t key, size_t keyLength)
	Initializes a CryptoKey with plaintext encoding. More...

int_fast16_t	HSMBareMetal_deInit (void)
	Close the HSMBareMetal Module. More...

int_fast16_t	HSMBareMetal_ECCOperation (HSMBareMetal_ECCOperationStruct *operationStruct)
	Perform a Bare Metal Public Key Operation. More...

void	HSMBareMetal_ECCOperation_init (HSMBareMetal_ECCOperationStruct *operationStruct)
	Function to initialize an HSMBareMetal_ECCOperation struct to its default (all zeroes)

int_fast16_t	HSMBareMetal_freeAssetPair (HSMBareMetal_AssetPairStruct keyAssetPair)
	Perform a Bare Metal Asset Delete Operations. More...

int_fast16_t	HSMBareMetal_freeKeyAsset (uint32_t *keyAssetID)
	Perform a Bare Metal Asset Delete Operation. More...

int_fast16_t	HSMBareMetal_getHSMFirmwareVersion (HSMBareMetal_systemInfoVersionStruct *firmwareVersionStruct)
	Returns the HSM FW image version number (major, minor, and patch) More...

int_fast16_t	HSMBareMetal_HASHOperation (HSMBareMetal_HASHOperationStruct *operationStruct)
	Perform a Bare Metal Hash Operation. More...

void	HSMBareMetal_HASHOperation_init (HSMBareMetal_HASHOperationStruct *operationStruct)
	Function to initialize an HSMBareMetal_HASHOperation struct to its default (all zeroes)

int_fast16_t	HSMBareMetal_init (void)
	Initialize HSMBareMetal Module. More...

int_fast16_t	HSMBareMetal_MACOperation (HSMBareMetal_MACOperationStruct *operationStruct)
	Perform a Bare Metal MAC Operation. More...

void	HSMBareMetal_MACOperation_init (HSMBareMetal_MACOperationStruct *operationStruct)
	Function to initialize an HSMBareMetal_MACOperation struct to its default (all zeroes)

int_fast16_t	HSMBareMetal_provisionHUK (void)
	Provision the Hardware Unique Key (HUK) for this device. More...

int_fast16_t	HSMBareMetal_RNGOperation (HSMBareMetal_RNGOperationStruct *operationStruct)
	Perform a Bare Metal Random Number Generation Operation. More...

void	HSMBareMetal_RNGOperation_init (HSMBareMetal_RNGOperationStruct *operationStruct)
	Function to initialize an HSMBareMetal_RNGOperation struct to its default (all zeroes)

int_fast16_t	HSMBareMetal_RNGSwitchNRBGMode (HSMBareMetal_NRBGMode NRBGMode)
	Switch the current NRBG engine: CRNG -> TRNG or vice-versa. More...

int_fast16_t	HSMBareMetal_searchStaticAsset (uint32_t assetNumber, uint32_t *assetId)
	Perform an HSM OTP search for static asset. More...

Detailed Description

Interface to The HSM IP in a BareMetal-based implementation.

This module provides cryptographic functions for use of the Hardware Security Module.

Summary and List of Features:

HSM initialization sequence.
- Turn on the HSM Clock.
- Initialize and link the designated HSM mailbox for token exchanges
- Boot up the HSM by sending a boot operation to the HSM to initialize the HSM FW.
HSM un-init sequence.
HSM HUK provisioning.
HSM Asset-related Operations:
- Dynamic Asset creation and plaintext-only load to the HSM internal AssetStore.
- Support for AES and MAC keys including HMAC.
- In-API key generation: (The user can request to generate key, create an asset, and load key in HSM AssetStore in one API)
- Loading plaintext, returning an asset ID pair, and extracting a Key blob pair for AES operations.
  - Please use the HSM_KEYBLOB_SIZE() macro to determine the appropriate size of key blob buffers.
- Importing a key blob pair for AES operations and returning an asset ID pair
HSM Cryptography-related Operations:
- AES operations, (CCM, GCM, CTR, ECB, CBC).
- MAC operations, (128-bit CMAC, 128-bit CBC-MAC, HMAC).
- Hash operations, (SHA2-224, SHA2-256, SHA2-384, SHA2-512).
- RNG operations, Deterministic (RECOMMENDED) and non-deterministic (Raw).
- ECC operations, (ECDH, ECDSA).
HSM Support for plaintext or AssetStore formats for keys for AES operations.
- (CCM, GCM, CTR, ECB, CBC):
  1. For plaintext, the symmetric key material can be provided as part of the AES operation.
  2. For AssetStore, the symmetric key material must be loaded as an HSM asset and the asset ID generated has to be provided as part of the AES operation.
- (CMAC, CBC-MAC, and HMAC):
  1. MAC-based operations that require the symmetric key to be pre-loaded in the HSM AssetStore and provide the asset ID as part of the MAC operation.
HSM Support for (CCM, GCM, CTR, ECB, CBC, CMAC, CBC-MAC) operations with the following key sizes:
- 128-bit (16 Bytes).
- 192-bit (24 Bytes).
- 256-bit (32 Bytes).
HSM Support for HMAC Algorithms:
- SHA2-224 with key sizes within range 14-64 Bytes.
- SHA2-256 with key sizes within range 14-64 Bytes.
- SHA2-384 with key sizes within range 24-128 Bytes.
- SHA2-512 with key sizes within range 32-128 Bytes.
HSM Support for HASH Algorithms:
- SHA2-224 with digest length 28 Bytes.
- SHA2-256 with digest length 32 Bytes.
- SHA2-384 with digest length 48 Bytes.
- SHA2-512 with digest length 64 Bytes.
- Multi-step hash operations are supported. To perform a multi-step hash operation, the user will need to create
- a series of operations with the operation Type in the following order:
  - INIT_TO_CONT (once)
  - CONT_TO_CONT (as many times as necessary)
  - CONT_TO_FINAL (once)
- Multi-step hash operations are supported for all digest lengths and sha2 algorithms.
- Performing a CONT_TO_CONT or CONT_TO_FINAL hash operation before an INIT_TO_CONT hash operation will result
- unexpected outputs.
HSM Support for RNG Operations:
- Size must be 0 < x < (2^16 Bytes).
- For DRBG data, size must be 32-bit aligned. (Multiple of 4 bytes).
- For NRBG data, size can be anywhere between 1-256 bytes and multiple of 256 bytes if larger than 256 bytes.
HSM Support for ECC Operations:
- ECDH public key generation.
- ECDH shared secret generation.
- ECDSA DS digest signature generation.
- ECDSA DS digest signature verification.
HSM Support for ECC Curve types:
- SEC_P_224_R1.
- SEC_P_256_R1.
- SEC_P_384_R1.
- SEC_P_521_R1.
- BRP_P_256_R1.
- BRP_P_384_R1.
- BRP_P_512_R1.
- CURVE25519.
HSM limitations:
- All buffer address must be word-aligned.
- Input plaintext length for (CCM, GCM, CBC, CTR, ECB, CMAC, CBC-MAC, SHA2, HMAC) shall be upto 2^21 -1 Bytes and block-size aligned.
- For non-final hash operations, the input data should be block-size aligned (128 bytes for SHA-2-384 and SHA-2-512 or 64 bytes for the other algorithms).
- For segmented hashing, the user must maintain the intermediate digest buffer to be passed between operations.
- Input for every ECC operation must be in big endian format.
- Input and output buffers shall be a multiple of block length. Meaning that while the input data can be of any length, the buffers for the input and output data should be rounded up to the nearest size that is a multiple of block size.
  - For example, input data size of 24 Bytes must be in a buffer that is of size 32 bytes.
- Additional Authenticated Data (AAD) for (CCM, GCM) length up to 2^16 - 2^8 Bytes.
- The combined length of the input data and the AAD for (CCM, GCM) shall not be zero.
- Nonce for (CCM) length for (7-13) Bytes.
- Initialization Vector (IV) for (CCM, CBC, CTR) length IS EXACTLY 16 Bytes.
- Tag length for AES-CCM shall be a multiple of 2 Bytes, [4, 6, 8, 10, 12, 14, 16].
- Tag for AES-GCM length should be the following [4, 8, 12, 13, 14, 15, 16] Bytes.
- MAC length (128-bit CMAC, 128-bit CBC-MAC) should be the following [2, 4, 6, 8, 10, 12, 14, 16] Bytes.
- For ECC operations:
  - ECDSA sign and verify operations do not support curve type: CURVE25519.
  - All input keys must be supplied in plaintext.
  - ECC operations takes in a digest (not the input buffer). Therefore, the input buffer must be hashed using HSMBareMetal_HASHOperation() API and supplying the digest in the ECC operation.
  - Digest length must match curve length. Ex. for SEC_P_384_R1 and BRP_P_384_R1 curve types, the digest must be generated using SHA2-384. For BRP_P_512_R1 and SEC_P_521_R1 curve types, the digest must be generated using SHA2-512.

NOTE: The above features do not support segmented operations. All operations are performed as a 'one-shot' operation. NOTE: the above features and their APIs are synchonous and conduct their operations in a polling return behavior-like fashion.

Usage

Before starting a BareMetal operation

Call HSMBareMetal_init() to initialize the HSM IP and the SW architecture.
Call HSMBareMetal_provisionHUK() to use any asset-related operations and specifically key blob-related operations.

Starting a BareMetal operation

The HSMBareMetal implementation provides a simplified approach to leverage the Hardware Security Module (HSM) functional capability while also bypassing the complex SW architecture of the HSM and the RTOS while offering a centralized suit of APIs to conduct all major cryptographic operations.

This implementation delivers multiple features in a switch-like approach. For example, it allows multiple modes of an Advanced Encryption Standard (AES) operations in one API by simply choosing from an Enum for all AEAD operations such as (CCM, GCM, CBC, CTR, ECB, CMAC, CBC-MAC), (ENC, DEC).

Examples

// Import the HSMBareMetal defintions
#include <ti/drivers/cryptoutils/hsm/HSMBareMetal.h>
int_fast16_t status;
HSMBareMetal_AssetOperationStruct assetOperationStruct;
HSMBareMetal_AESOperationStruct AESOperationStruct;
HSMBareMetal_AESOperationMode aesOperationMode = HSMBareMetal_AES_MODE_CCM;
HSMBareMetal_KeyInput keyInput = HSMBareMetal_KEY_INPUT_ASSETSTORE;
uint32_t encKeyAssetId   = 0U;
uint32_t decKeyAssetId   = 0U;
HSMBareMetal_AssetPairStruct assetPair;
assetPair.encGenKeyAssetID = &encKeyAssetId;
assetPair.decVrfyKeyAssetID = &decKeyAssetId;
uint8_t nonce[] = "Thisisanonce";
uint8_t aad[] = "This string will be authenticated but not encrypted.";
uint8_t plaintext[] = "This string will be encrypted and authenticated.";
uint8_t mac[16];
uint8_t ciphertext[sizeof(plaintext)];
uint8_t keyingMaterial[32] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
                              0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F,
                              0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
                              0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F};
status = HSMBareMetal_init();
if (status != HSMBAREMETAL_STATUS_SUCCESS)
{
    // handle error
}
if (keyInput == HSMBareMetal_KEY_INPUT_ASSETSTORE)
{
    HSMBareMetal_AssetOperation_init(&assetOperationStruct);
    assetOperationStruct.keyAssetIDs = assetPair;
    assetOperationStruct.isKeyGenerated = true;
    assetOperationStruct.key = &keyingMaterial[0];
    assetOperationStruct.keyLength = sizeof(keyingMaterial);
    assetOperationStruct.algorithm = HSMBareMetal_OPERATION_ALGO_AES;
    assetOperationStruct.aesOperationMode = aesOperationMode;
    status = HSMBareMetal_AssetOperation(&assetOperationStruct);
    if (status != HSMBAREMETAL_STATUS_SUCCESS)
    {
        // handle error
    }
}
HSMBareMetal_AESOperation_init(&AESOperationStruct);
if (keyInput == HSMBareMetal_KEY_INPUT_ASSETSTORE)
{
    AESOperationStruct.keyAssetID = encKeyAssetId;
}
else
{
    AESOperationStruct.key = (uint8_t *)keyingMaterial;
}
AESOperationStruct.keyLength = sizeof(keyingMaterial);
AESOperationStruct.isKeyInAssetStore = keyInput;
AESOperationStruct.input = plaintext;
AESOperationStruct.inputLength = sizeof(plaintext);
AESOperationStruct.aad = aad;
AESOperationStruct.aadLength = sizeof(aad);
AESOperationStruct.mac = mac;
AESOperationStruct.macLength = sizeof(mac);
AESOperationStruct.nonce = nonce;
AESOperationStruct.nonceLength = sizeof(nonce);
AESOperationStruct.output = ciphertext;
AESOperationStruct.operationMode = aesOperationMode;
AESOperationStruct.operationDirection = HSMBareMetal_OPERATION_DIR_ENC_GEN;
status = HSMBareMetal_AESOperation(&AESOperationStruct);
if (status != HSMBAREMETAL_STATUS_SUCCESS)
{
    // handle error
}
if (keyInput == HSMBareMetal_KEY_INPUT_ASSETSTORE)
{
    status = HSMBareMetal_freeAssetPair(assetPair);
}
HSMBareMetal_deInit();

Macro Definition Documentation

§ HSM_KEYBLOB_SIZE

#define HSM_KEYBLOB_SIZE ( keyLength ) (HSMBAREMETAL_AES_BLOCK_SIZE + keyLength)

The expected size of an AES-SIV keyblob.

Note: keyLength is the size of the Asset in octects (bytes).

§ HSMBAREMETAL_STATUS_ERROR

#define HSMBAREMETAL_STATUS_ERROR ((int_fast16_t)-1)

Generic error status code.

Functions return HSMBAREMETAL_STATUS_ERROR if the function was not executed successfully and no more specific error is applicable.

§ HSMBAREMETAL_STATUS_HW_ERROR

#define HSMBAREMETAL_STATUS_HW_ERROR ((int_fast16_t)-3)

HSM IP reported a Hardware error. This renders the IP non-functional.

To fix this, a hard reset must be performed on the device.

§ HSMBAREMETAL_STATUS_INVALID_MAC

#define HSMBAREMETAL_STATUS_INVALID_MAC ((int_fast16_t)-5)

The MAC verification failed.

A MAC operation-related error code.

Functions return HSMBAREMETAL_STATUS_INVALID_MAC if the MAC computed for the provided (key, message) pair did not match the MAC provided.

§ HSMBAREMETAL_STATUS_SUCCESS

#define HSMBAREMETAL_STATUS_SUCCESS ((int_fast16_t)0)

Successful status code.

Functions return HSMBAREMETAL_STATUS_SUCCESS if the function was executed successfully.

Enumeration Type Documentation

§ HSMBareMetal_entropyType

enum HSMBareMetal_entropyType

Enum for entropy type.

For key generation, users MUST choose #ENTROPY_TYPE_DRBG.

§ HSMBareMetal_NRBGMode

enum HSMBareMetal_NRBGMode

Enum for the current NRBG IP for the HSM to pull entropy from.

By default, the HSM is set to use the #NRBG_TYPE_CRNG.

§ HSMBareMetal_operationAlgorithm

enum HSMBareMetal_operationAlgorithm

Enum for operation algorithm.

These values to be used in Dynamic asset creation to determine the proper asset Policy for an HSM Key.

§ HSMBareMetal_operationDirection

enum HSMBareMetal_operationDirection

Enum for the direction of an AES operation.

Encryption/Decryption for (CCM, GCM, CBC, CTR, ECB)
Generate/Verify for (CMAC, CBC-MAC, HMAC)

Function Documentation

§ HSMBareMetal_AESOperation()

int_fast16_t HSMBareMetal_AESOperation ( HSMBareMetal_AESOperationStruct * operationStruct )

Perform a Bare Metal AES Operation.

Precondition: HSMBareMetal must be initialized using HSMBareMetal_init()

Parameters

[in] operationStruct Pointer to the operation's structure.

Return values

HSMBAREMETAL_STATUS_SUCCESS	The operation succeeded.
HSMBAREMETAL_STATUS_ERROR	The operation failed.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.
HSMBAREMETAL_STATUS_INVALID_INPUT_PARAMETERS	One or more of the input parameters is incorrect.

§ HSMBareMetal_AssetOperation()

int_fast16_t HSMBareMetal_AssetOperation ( HSMBareMetal_AssetOperationStruct * operationStruct )

Perform a Bare Metal Asset Create and Load Operations.

Precondition: HSMBareMetal must be initialized using HSMBareMetal_init()

!!!!Important!!!! When operationStruct.isKeyGenerated is set to true, the HSMBareMetal module will IGNORE the key input parameter and instead generate a random key internally and use that as the data for an asset create and load operations.

The user MUST specify buffers for both #HSMBareMetal_AssetPairStruct.encGenKeyAssetID and #HSMBareMetal_AssetPairStruct.decVrfyKeyAssetID inside of HSMBareMetal_AssetPairStruct. This API creates TWO assets and returns the corresponding asset IDs for them.

Parameters

[in] operationStruct Pointer to the operation's structure.

Return values

HSMBAREMETAL_STATUS_SUCCESS	The operation succeeded.
HSMBAREMETAL_STATUS_ERROR	The operation failed.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.
HSMBAREMETAL_STATUS_INVALID_INPUT_PARAMETERS	One or more of the input parameters is incorrect.

§ HSMBareMetal_checkHSMStatus()

int_fast16_t HSMBareMetal_checkHSMStatus ( void )

Check HSM HW status.

Return values

HSMBAREMETAL_STATUS_HSM_ALREADY_INITIALIZED	HSM is initialized properly and ready for use.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.

§ HSMBareMetal_CryptoKeyPlaintext_initKey()

void HSMBareMetal_CryptoKeyPlaintext_initKey	(	HSMBareMetal_CryptoKeyStruct *	cryptoKey,
		uint8_t *	key,
		size_t	keyLength
	)

Initializes a CryptoKey with plaintext encoding.

Parameters

[in]	cryptoKey	Pointer to a CryptoKey which will be initialized to type HSMBareMetal_KEY_INPUT_PLAINTEXT and ready for use
[in]	key	Pointer to keying material
[in]	keyLength	Length of keying material in bytes

§ HSMBareMetal_deInit()

int_fast16_t HSMBareMetal_deInit ( void )

Close the HSMBareMetal Module.

This operation turns off the HSM and clears all static objects.

§ HSMBareMetal_ECCOperation()

int_fast16_t HSMBareMetal_ECCOperation ( HSMBareMetal_ECCOperationStruct * operationStruct )

Perform a Bare Metal Public Key Operation.

Precondition: HSMBareMetal must be initialized using HSMBareMetal_init()

!!!!Important!!!! For ECC operations:

ECDSA sign and verify operations do not support curve type: CURVE25519.
All input keys must be supplied in plaintext.
ECC operations takes in a digest (not the input buffer). Therefore, the input buffer must be hashed using HSMBareMetal_HASHOperation() API and supplying the digest in the ECC operation.
Digest length must match curve length. Ex. For SEC_P_384_R1 and BRP_P_384_R1 curve types, the digest must be generated using SHA2-384. Ex. For BRP_P_512_R1 and SEC_P_521_R1 curve types, the digest must be generated using SHA2-512.

Parameters

[in] operationStruct Pointer to the operation's structure.

Return values

HSMBAREMETAL_STATUS_SUCCESS	The operation succeeded.
HSMBAREMETAL_STATUS_ERROR	The operation failed.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.
HSMBAREMETAL_STATUS_INVALID_INPUT_PARAMETERS	One or more of the input parameters is incorrect.

§ HSMBareMetal_freeAssetPair()

int_fast16_t HSMBareMetal_freeAssetPair ( HSMBareMetal_AssetPairStruct keyAssetPair )

Perform a Bare Metal Asset Delete Operations.

Precondition: HSMBareMetal must be initialized using HSMBareMetal_init() and a previous call to HSMBareMetal_AssetOperation()

Parameters

[in] keyAssetPair ENC/GEN and DEC/VRFY asset IDs

Return values

HSMBAREMETAL_STATUS_SUCCESS	The operation succeeded.
HSMBAREMETAL_STATUS_ERROR	The operation failed.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.
HSMBAREMETAL_STATUS_INVALID_INPUT_PARAMETERS	One or more of the input parameters is incorrect.

§ HSMBareMetal_freeKeyAsset()

int_fast16_t HSMBareMetal_freeKeyAsset ( uint32_t * keyAssetID )

Perform a Bare Metal Asset Delete Operation.

Precondition: HSMBareMetal must be initialized using HSMBareMetal_init() and a previous call to HSMBareMetal_AssetOperation()

Parameters

[in] keyAssetID Asset ID

Return values

HSMBAREMETAL_STATUS_SUCCESS	The operation succeeded.
HSMBAREMETAL_STATUS_ERROR	The operation failed.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.

§ HSMBareMetal_getHSMFirmwareVersion()

int_fast16_t HSMBareMetal_getHSMFirmwareVersion ( HSMBareMetal_systemInfoVersionStruct * firmwareVersionStruct )

Returns the HSM FW image version number (major, minor, and patch)

Precondition: HSMBareMetal must be initialized using HSMBareMetal_init()

This function sends a system info token and extracts HSM version numbers and returns the FW version.

Parameters

[in] firmwareVersionStruct firmware version structure

Return values

HSMBAREMETAL_STATUS_SUCCESS	System info token returned data successfully.
HSMBAREMETAL_STATUS_ERROR	Error. System info failed or HSMBareMetal is not initialized.

§ HSMBareMetal_HASHOperation()

int_fast16_t HSMBareMetal_HASHOperation ( HSMBareMetal_HASHOperationStruct * operationStruct )

Perform a Bare Metal Hash Operation.

Precondition: HSMBareMetal must be initialized using HSMBareMetal_init()

Parameters

[in] operationStruct Pointer to the operation's structure.

Return values

HSMBAREMETAL_STATUS_SUCCESS	The operation succeeded.
HSMBAREMETAL_STATUS_ERROR	The operation failed.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.
HSMBAREMETAL_STATUS_INVALID_INPUT_PARAMETERS	One or more of the input parameters is incorrect.

§ HSMBareMetal_init()

int_fast16_t HSMBareMetal_init ( void )

Initialize HSMBareMetal Module.

The initialization process include:

Turning on the HSM IP by enabling the clock.
Initializing the HSM Mailboxes and corresponding registers.
Booting the HSM (Sending a boot token and ensuring that the HSM FW image is accepted).

Return values

HSMBAREMETAL_STATUS_SUCCESS	Initialization process was successful
HSMBAREMETAL_STATUS_ERROR	Initialization process was unsuccessful.
HSMBAREMETAL_STATUS_HSM_ALREADY_INITIALIZED	HSM already initialized.

§ HSMBareMetal_MACOperation()

int_fast16_t HSMBareMetal_MACOperation ( HSMBareMetal_MACOperationStruct * operationStruct )

Perform a Bare Metal MAC Operation.

Precondition: HSMBareMetal must be initialized using HSMBareMetal_init()

Parameters

[in] operationStruct Pointer to the operation's structure.

Return values

HSMBAREMETAL_STATUS_SUCCESS	The operation succeeded.
HSMBAREMETAL_STATUS_ERROR	The operation failed.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.
HSMBAREMETAL_STATUS_INVALID_INPUT_PARAMETERS	One or more of the input parameters is incorrect.

§ HSMBareMetal_provisionHUK()

int_fast16_t HSMBareMetal_provisionHUK ( void )

Provision the Hardware Unique Key (HUK) for this device.

This is an operation that should be done only once per device lifetime.

Precondition: Must call HSMBareMetal_init() prior.

Return values

HSMBAREMETAL_STATUS_SUCCESS	The operation succeeded.
HSMBAREMETAL_STATUS_HUK_ALREADY_PROVISIONED	HUK already provisioned.
HSMBAREMETAL_STATUS_ERROR	The operation failed.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.

§ HSMBareMetal_RNGOperation()

int_fast16_t HSMBareMetal_RNGOperation ( HSMBareMetal_RNGOperationStruct * operationStruct )

Perform a Bare Metal Random Number Generation Operation.

Precondition: HSMBareMetal must be initialized using HSMBareMetal_init()

!!!!IMPORTANT!!!!

Size must be 0 < x < (2^16 Bytes).
For DRBG data, size must be 32-bit aligned. (Multiple of 4 bytes).
For NRBG data, size can be anywhere between 1-256 bytes and multiple of 256 bytes if larger than 256 bytes.

For symmetric key generation, users MUST choose #ENTROPY_TYPE_DRBG. However, the HSMBareMetal_AssetOperation() API provide an In-API key generation feature that generates a key, creates two assets (ENC/GEN and DEC/VRFY) and loads the key into both assets and returns an a pair of asset IDs.

Parameters

[in] operationStruct Pointer to the operation's structure.

Return values

HSMBAREMETAL_STATUS_SUCCESS	The operation succeeded.
HSMBAREMETAL_STATUS_ERROR	The operation failed.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.
HSMBAREMETAL_STATUS_INVALID_INPUT_PARAMETERS	One or more of the input parameters is incorrect.

§ HSMBareMetal_RNGSwitchNRBGMode()

int_fast16_t HSMBareMetal_RNGSwitchNRBGMode ( HSMBareMetal_NRBGMode NRBGMode )

Switch the current NRBG engine: CRNG -> TRNG or vice-versa.

Precondition: HSMBareMetal must be initialized using HSMBareMetal_init()

Parameters

[in] NRBGMode Used to select which NRBG noise source to use.

Return values

HSMBAREMETAL_STATUS_SUCCESS	The operation succeeded.
HSMBAREMETAL_STATUS_ERROR	The operation failed.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.
HSMBAREMETAL_STATUS_INVALID_INPUT_PARAMETERS	One or more of the input parameters is incorrect.

§ HSMBareMetal_searchStaticAsset()

int_fast16_t HSMBareMetal_searchStaticAsset	(	uint32_t	assetNumber,
		uint32_t *	assetId
	)

Perform an HSM OTP search for static asset.

This API searches the HSM OTP for the specified asset number and returns found or not found.

Parameters

[in]	assetNumber	Static asset number
[out]	assetId	The corresponding asset ID

Return values

HSMBAREMETAL_STATUS_SUCCESS	Asset found.
HSMBAREMETAL_STATUS_ERROR	Asset not found.
HSMBAREMETAL_STATUS_HSM_NOT_INITIALIZED	Call HSMBareMetal_init() first.
HSMBAREMETAL_STATUS_HW_ERROR	HSM in fatal mode. Reset Device.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Usage

Before starting a BareMetal operation

Starting a BareMetal operation

Examples

Macro Definition Documentation

§ HSM_KEYBLOB_SIZE

§ HSMBAREMETAL_STATUS_ERROR

§ HSMBAREMETAL_STATUS_HW_ERROR

§ HSMBAREMETAL_STATUS_INVALID_MAC

§ HSMBAREMETAL_STATUS_SUCCESS

Enumeration Type Documentation

§ HSMBareMetal_entropyType

§ HSMBareMetal_NRBGMode

§ HSMBareMetal_operationAlgorithm

§ HSMBareMetal_operationDirection

Function Documentation

§ HSMBareMetal_AESOperation()

§ HSMBareMetal_AssetOperation()

§ HSMBareMetal_checkHSMStatus()

§ HSMBareMetal_CryptoKeyPlaintext_initKey()

§ HSMBareMetal_deInit()

§ HSMBareMetal_ECCOperation()

§ HSMBareMetal_freeAssetPair()

§ HSMBareMetal_freeKeyAsset()

§ HSMBareMetal_getHSMFirmwareVersion()

§ HSMBareMetal_HASHOperation()

§ HSMBareMetal_init()

§ HSMBareMetal_MACOperation()

§ HSMBareMetal_provisionHUK()

§ HSMBareMetal_RNGOperation()

§ HSMBareMetal_RNGSwitchNRBGMode()

§ HSMBareMetal_searchStaticAsset()