Secure-element implementation backed by libtropic. More...

Inheritance diagram for cdc::hal::Tropic01Element:

Public Member Functions
	Tropic01Element ()=default
bool	init () override
	Initializes PSA crypto and the libtropic device context.
bool	start () override
	Starts secure-element service when initialized.
void	stop () override
	Stops secure-element service and closes any active session.
core::ServiceState	getState () const override
const char *	getName () const override
bool	sessionStart () override
	Opens a secure session with the TROPIC01 chip.
void	sessionEnd () override
	Aborts the active secure session.
bool	isSessionActive () const override
void	sleep () override
	Requests secure-element sleep mode and marks session inactive.
SeResult	eccGenerate (uint8_t slot, EccCurve curve) override
	Generates an ECC key pair in the requested slot.
SeResult	eccImport (uint8_t slot, const uint8_t *privKey, EccCurve curve) override
	Imports an ECC private key into the requested slot.
SeResult	eccGetPublicKey (uint8_t slot, uint8_t pubKey, EccCurve curve) override
	Reads public key from ECC slot.
SeResult	eccDelete (uint8_t slot) override
	Erases ECC key material from slot.
bool	eccSlotUsed (uint8_t slot) const override
	Checks whether ECC slot currently contains a key.
bool	getFwVersion (uint8_t riscvVer[4], uint8_t spectVer[4]) override
	Reads RISC-V and SPECT firmware major version bytes.
uint16_t	getRmemSlotSize () const override
SeResult	ecdsaSign (uint8_t slot, const uint8_t msg, size_t msgLen, uint8_t sig, size_t *sigLen) override
	Signs a message using ECDSA key in slot.
SeResult	eddsaSign (uint8_t slot, const uint8_t msg, size_t msgLen, uint8_t sig) override
	Signs message using EdDSA key in slot.
SeResult	rmemRead (uint16_t slot, uint8_t data, uint16_t maxLen, uint16_t actualLen) override
	Reads raw R-memory slot data.
SeResult	rmemWrite (uint16_t slot, const uint8_t *data, uint16_t len) override
	Writes raw data to an R-memory slot.
SeResult	rmemErase (uint16_t slot) override
	Erases one R-memory slot.
bool	rmemSlotUsed (uint16_t slot) const override
	Checks whether R-memory slot contains data.
SeResult	rmemWriteWithHeader (uint16_t slot, uint8_t moduleId, const char name, uint8_t flags, const uint8_t payload, uint16_t payloadLen) override
	Writes payload to R-memory slot with metadata header.
SeResult	rmemReadWithHeader (uint16_t slot, RMemHeader headerOut, uint8_t payloadOut, uint16_t payloadMax, uint16_t *payloadLenOut) override
	Reads and validates headered R-memory record.
bool	getRandom (uint8_t *buffer, uint16_t size) override
	Fills buffer with random bytes from TROPIC TRNG with ESP fallback.
bool	getRandomStrict (uint8_t *buffer, uint16_t size) override
	Fills buffer with random bytes from TROPIC TRNG only; no fallback.
bool	getChipId (uint8_t *serialNum, uint8_t size) override
	Reads chip serial identifier.
Public Member Functions inherited from cdc::hal::ISecureElement
virtual	~ISecureElement ()=default
struct	__attribute__ ((packed)) RMemHeader
Public Member Functions inherited from cdc::core::IService
virtual	~IService ()=default

Additional Inherited Members
Static Public Attributes inherited from cdc::hal::ISecureElement
static constexpr uint8_t	ECC_SLOT_COUNT = 32
static constexpr uint16_t	RMEM_SLOT_COUNT = 512
static constexpr uint16_t	RMEM_SLOT_SIZE = 444
static constexpr uint16_t	RMEM_SLOT_SIZE_MAX = 475
static constexpr uint8_t	RMEM_NAME_LEN = 16

Detailed Description

Secure-element implementation backed by libtropic.

Definition at line 54 of file Tropic01Element.cpp.

Constructor & Destructor Documentation

◆ Tropic01Element()

cdc::hal::Tropic01Element::Tropic01Element ( )

default

Referenced by eccSlotUsed(), and rmemSlotUsed().

Member Function Documentation

◆ eccDelete()

SeResult cdc::hal::Tropic01Element::eccDelete ( uint8_t slot )

overridevirtual

Erases ECC key material from slot.

Implements cdc::hal::ISecureElement.

Definition at line 599 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, cdc::hal::ISecureElement::ECC_SLOT_COUNT, cdc::hal::ERROR, cdc::core::SystemLock::instance(), cdc::hal::INVALID_PARAM, and cdc::hal::SESSION_REQUIRED.

◆ eccGenerate()

SeResult cdc::hal::Tropic01Element::eccGenerate	(	uint8_t	slot,
		EccCurve	curve )

overridevirtual

Generates an ECC key pair in the requested slot.

Implements cdc::hal::ISecureElement.

Definition at line 510 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, curve, cdc::hal::ISecureElement::ECC_SLOT_COUNT, cdc::hal::ED25519, cdc::hal::ERROR, cdc::core::SystemLock::instance(), cdc::hal::INVALID_PARAM, and cdc::hal::SESSION_REQUIRED.

◆ eccGetPublicKey()

SeResult cdc::hal::Tropic01Element::eccGetPublicKey	(	uint8_t	slot,
		uint8_t *	pubKey,
		EccCurve *	curve )

overridevirtual

Reads public key from ECC slot.

Implements cdc::hal::ISecureElement.

Definition at line 585 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, curve, cdc::hal::ISecureElement::ECC_SLOT_COUNT, cdc::hal::ERROR, cdc::core::SystemLock::instance(), and cdc::hal::INVALID_PARAM.

◆ eccImport()

SeResult cdc::hal::Tropic01Element::eccImport	(	uint8_t	slot,
		const uint8_t *	privKey,
		EccCurve	curve )

overridevirtual

Imports an ECC private key into the requested slot.

Implements cdc::hal::ISecureElement.

Definition at line 537 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, curve, cdc::hal::ISecureElement::ECC_SLOT_COUNT, cdc::hal::ED25519, cdc::hal::ERROR, cdc::core::SystemLock::instance(), cdc::hal::INVALID_PARAM, and cdc::hal::SESSION_REQUIRED.

◆ eccSlotUsed()

bool cdc::hal::Tropic01Element::eccSlotUsed ( uint8_t slot ) const

overridevirtual

Checks whether ECC slot currently contains a key.

Implements cdc::hal::ISecureElement.

Definition at line 624 of file Tropic01Element.cpp.

References cdc::hal::ISecureElement::ECC_SLOT_COUNT, cdc::hal::OK, and Tropic01Element().

◆ ecdsaSign()

SeResult cdc::hal::Tropic01Element::ecdsaSign	(	uint8_t	slot,
		const uint8_t *	msg,
		size_t	msgLen,
		uint8_t *	sig,
		size_t *	sigLen )

overridevirtual

Signs a message using ECDSA key in slot.

Callers pass the raw message. ECDSA on the chip signs a 32-byte digest, so the message is hashed with SHA-256 here before signing.

Implements cdc::hal::ISecureElement.

Definition at line 642 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, cdc::hal::ISecureElement::ECC_SLOT_COUNT, cdc::hal::ERROR, cdc::core::SystemLock::instance(), cdc::hal::INVALID_PARAM, and cdc::hal::SESSION_REQUIRED.

◆ eddsaSign()

SeResult cdc::hal::Tropic01Element::eddsaSign	(	uint8_t	slot,
		const uint8_t *	msg,
		size_t	msgLen,
		uint8_t *	sig )

overridevirtual

Signs message using EdDSA key in slot.

Implements cdc::hal::ISecureElement.

Definition at line 678 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, cdc::hal::ISecureElement::ECC_SLOT_COUNT, cdc::hal::ERROR, cdc::core::SystemLock::instance(), cdc::hal::INVALID_PARAM, and cdc::hal::SESSION_REQUIRED.

◆ getChipId()

bool cdc::hal::Tropic01Element::getChipId	(	uint8_t *	serialNum,
		uint8_t	size )

overridevirtual

Reads chip serial identifier.

Implements cdc::hal::ISecureElement.

Definition at line 1002 of file Tropic01Element.cpp.

References cdc::core::SystemLock::instance().

◆ getFwVersion()

bool cdc::hal::Tropic01Element::getFwVersion	(	uint8_t	riscvVer[4],
		uint8_t	spectVer[4] )

overridevirtual

Reads RISC-V and SPECT firmware major version bytes.

Implements cdc::hal::ISecureElement.

Definition at line 1028 of file Tropic01Element.cpp.

References cdc::core::SystemLock::instance().

◆ getName()

const char * cdc::hal::Tropic01Element::getName ( ) const

inlineoverridevirtual

Get service name (for logging/debugging)

Implements cdc::core::IService.

Definition at line 63 of file Tropic01Element.cpp.

◆ getRandom()

bool cdc::hal::Tropic01Element::getRandom	(	uint8_t *	buffer,
		uint16_t	size )

overridevirtual

Fills buffer with random bytes from TROPIC TRNG with ESP fallback.

Always returns true on a non-empty request; a WARN is logged whenever the ESP32 TRNG fallback is taken so the origin is auditable in the log stream. Callers that require hardware-only entropy must use getRandomStrict().

Implements cdc::hal::ISecureElement.

Definition at line 945 of file Tropic01Element.cpp.

References cdc::core::SystemLock::instance(), LOG_W, and TAG.

◆ getRandomStrict()

bool cdc::hal::Tropic01Element::getRandomStrict	(	uint8_t *	buffer,
		uint16_t	size )

overridevirtual

Fills buffer with random bytes from TROPIC TRNG only; no fallback.

Implements cdc::hal::ISecureElement.

Definition at line 979 of file Tropic01Element.cpp.

References cdc::core::SystemLock::instance().

◆ getRmemSlotSize()

uint16_t cdc::hal::Tropic01Element::getRmemSlotSize ( ) const

inlineoverridevirtual

Get the user-data R-Memory slot size in bytes as reported by the chip for the running Application FW. Always >= RMEM_SLOT_SIZE and <= RMEM_SLOT_SIZE_MAX.

Implements cdc::hal::ISecureElement.

Definition at line 79 of file Tropic01Element.cpp.

◆ getState()

core::ServiceState cdc::hal::Tropic01Element::getState ( ) const

inlineoverridevirtual

Get current service state

Implements cdc::core::IService.

Definition at line 62 of file Tropic01Element.cpp.

◆ init()

bool cdc::hal::Tropic01Element::init ( )

overridevirtual

Initializes PSA crypto and the libtropic device context.

Returns: true on success, otherwise false.

Implements cdc::core::IService.

Definition at line 150 of file Tropic01Element.cpp.

References cdc::core::ERROR, cdc::core::INITIALIZED, cdc::core::SystemLock::instance(), LOG_E, LOG_I, cdc::hal::ISecureElement::RMEM_SLOT_SIZE, cdc::hal::ISecureElement::RMEM_SLOT_SIZE_MAX, cdc::core::STARTED, TAG, cdc::core::TR01_ALARM_MODE, TR01_CS_PIN, cdc::core::TR01_INIT_FAILED, cdc::core::SystemLock::triggerLockdown(), and cdc::core::UNINITIALIZED.

◆ isSessionActive()

bool cdc::hal::Tropic01Element::isSessionActive ( ) const

inlineoverridevirtual

Check if session is active

Implements cdc::hal::ISecureElement.

Definition at line 68 of file Tropic01Element.cpp.

◆ rmemErase()

SeResult cdc::hal::Tropic01Element::rmemErase ( uint16_t slot )

overridevirtual

Erases one R-memory slot.

Implements cdc::hal::ISecureElement.

Definition at line 776 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, cdc::hal::ERROR, cdc::core::SystemLock::instance(), cdc::hal::INVALID_PARAM, and cdc::hal::ISecureElement::RMEM_SLOT_COUNT.

◆ rmemRead()

SeResult cdc::hal::Tropic01Element::rmemRead	(	uint16_t	slot,
		uint8_t *	data,
		uint16_t	maxLen,
		uint16_t *	actualLen )

overridevirtual

Reads raw R-memory slot data.

Implements cdc::hal::ISecureElement.

Definition at line 723 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, cdc::hal::ERROR, cdc::core::SystemLock::instance(), cdc::hal::INVALID_PARAM, and cdc::hal::ISecureElement::RMEM_SLOT_COUNT.

◆ rmemReadWithHeader()

SeResult cdc::hal::Tropic01Element::rmemReadWithHeader	(	uint16_t	slot,
		RMemHeader *	headerOut,
		uint8_t *	payloadOut,
		uint16_t	payloadMax,
		uint16_t *	payloadLenOut )

overridevirtual

Reads and validates headered R-memory record.

Implements cdc::hal::ISecureElement.

Definition at line 872 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, cdc::hal::ERROR, cdc::core::SystemLock::instance(), cdc::hal::INVALID_PARAM, cdc::hal::OK, cdc::hal::ISecureElement::RMEM_SLOT_COUNT, and cdc::hal::ISecureElement::RMEM_SLOT_SIZE_MAX.

◆ rmemSlotUsed()

bool cdc::hal::Tropic01Element::rmemSlotUsed ( uint16_t slot ) const

overridevirtual

Checks whether R-memory slot contains data.

Implements cdc::hal::ISecureElement.

Definition at line 790 of file Tropic01Element.cpp.

References cdc::hal::OK, cdc::hal::ISecureElement::RMEM_SLOT_COUNT, and Tropic01Element().

◆ rmemWrite()

SeResult cdc::hal::Tropic01Element::rmemWrite	(	uint16_t	slot,
		const uint8_t *	data,
		uint16_t	len )

overridevirtual

Writes raw data to an R-memory slot.

Implements cdc::hal::ISecureElement.

Definition at line 750 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, cdc::hal::ERROR, cdc::core::SystemLock::instance(), cdc::hal::INVALID_PARAM, and cdc::hal::ISecureElement::RMEM_SLOT_COUNT.

◆ rmemWriteWithHeader()

SeResult cdc::hal::Tropic01Element::rmemWriteWithHeader	(	uint16_t	slot,
		uint8_t	moduleId,
		const char *	name,
		uint8_t	flags,
		const uint8_t *	payload,
		uint16_t	payloadLen )

overridevirtual

Writes payload to R-memory slot with metadata header.

Implements cdc::hal::ISecureElement.

Definition at line 829 of file Tropic01Element.cpp.

References cdc::hal::ALARM_MODE, cdc::hal::ERROR, flags, cdc::core::SystemLock::instance(), cdc::hal::INVALID_PARAM, moduleId, name, cdc::hal::OK, RMEM_HEADER_MAGIC, cdc::hal::ISecureElement::RMEM_SLOT_COUNT, cdc::hal::ISecureElement::RMEM_SLOT_SIZE_MAX, and cdc::hal::SLOT_EMPTY.

◆ sessionEnd()

void cdc::hal::Tropic01Element::sessionEnd ( )

overridevirtual

Aborts the active secure session.

Implements cdc::hal::ISecureElement.

Definition at line 369 of file Tropic01Element.cpp.

References LOG_I, and TAG.

Referenced by stop().

◆ sessionStart()

bool cdc::hal::Tropic01Element::sessionStart ( )

overridevirtual

Opens a secure session with the TROPIC01 chip.

Implements cdc::hal::ISecureElement.

Definition at line 278 of file Tropic01Element.cpp.

References cdc::core::SystemLock::instance().

◆ sleep()

void cdc::hal::Tropic01Element::sleep ( )

overridevirtual

Requests secure-element sleep mode and marks session inactive.

Implements cdc::hal::ISecureElement.

Definition at line 399 of file Tropic01Element.cpp.

References cdc::core::SystemLock::instance(), LOG_E, LOG_I, and TAG.

◆ start()

bool cdc::hal::Tropic01Element::start ( )

overridevirtual

Starts secure-element service when initialized.

Implements cdc::core::IService.

Definition at line 202 of file Tropic01Element.cpp.

References cdc::core::INITIALIZED, cdc::core::STARTED, and cdc::core::STOPPED.

◆ stop()

void cdc::hal::Tropic01Element::stop ( )

overridevirtual

Stops secure-element service and closes any active session.

Implements cdc::core::IService.

Definition at line 214 of file Tropic01Element.cpp.

References sessionEnd(), cdc::core::STARTED, and cdc::core::STOPPED.

The documentation for this class was generated from the following file:

components/cdc_hal/src/Tropic01Element.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Tropic01Element()

Member Function Documentation

◆ eccDelete()

◆ eccGenerate()

◆ eccGetPublicKey()

◆ eccImport()

◆ eccSlotUsed()

◆ ecdsaSign()

◆ eddsaSign()

◆ getChipId()

◆ getFwVersion()

◆ getName()

◆ getRandom()

◆ getRandomStrict()

◆ getRmemSlotSize()

◆ getState()

◆ init()

◆ isSessionActive()

◆ rmemErase()

◆ rmemRead()

◆ rmemReadWithHeader()

◆ rmemSlotUsed()

◆ rmemWrite()

◆ rmemWriteWithHeader()

◆ sessionEnd()

◆ sessionStart()

◆ sleep()

◆ start()

◆ stop()