#include <ISecureElement.h>

Inheritance diagram for cdc::hal::ISecureElement:

Public Member Functions
virtual	~ISecureElement ()=default
virtual bool	sessionStart ()=0
virtual void	sessionEnd ()=0
virtual bool	isSessionActive () const =0
virtual void	sleep ()=0
virtual SeResult	eccGenerate (uint8_t slot, EccCurve curve)=0
virtual SeResult	eccImport (uint8_t slot, const uint8_t *privKey, EccCurve curve)=0
virtual SeResult	eccGetPublicKey (uint8_t slot, uint8_t pubKey, EccCurve curve=nullptr)=0
virtual SeResult	eccDelete (uint8_t slot)=0
virtual bool	eccSlotUsed (uint8_t slot) const =0
virtual SeResult	ecdsaSign (uint8_t slot, const uint8_t msg, size_t msgLen, uint8_t sig, size_t *sigLen)=0
virtual SeResult	eddsaSign (uint8_t slot, const uint8_t msg, size_t msgLen, uint8_t sig)=0
virtual SeResult	rmemRead (uint16_t slot, uint8_t data, uint16_t maxLen, uint16_t actualLen)=0
virtual SeResult	rmemWrite (uint16_t slot, const uint8_t *data, uint16_t len)=0
virtual SeResult	rmemErase (uint16_t slot)=0
virtual bool	rmemSlotUsed (uint16_t slot) const =0
struct	__attribute__ ((packed)) RMemHeader
virtual SeResult	rmemWriteWithHeader (uint16_t slot, uint8_t moduleId, const char name, uint8_t flags, const uint8_t payload, uint16_t payloadLen)=0
virtual SeResult	rmemReadWithHeader (uint16_t slot, RMemHeader headerOut, uint8_t payloadOut, uint16_t payloadMax, uint16_t *payloadLenOut)=0
virtual bool	getRandom (uint8_t *buffer, uint16_t size)=0
virtual bool	getRandomStrict (uint8_t *buffer, uint16_t size)=0
virtual bool	getChipId (uint8_t *serialNum, uint8_t size)=0
virtual bool	getFwVersion (uint8_t riscvVer[4], uint8_t spectVer[4])=0
virtual uint16_t	getRmemSlotSize () const =0
Public Member Functions inherited from cdc::core::IService
virtual	~IService ()=default
virtual bool	init ()=0
virtual bool	start ()=0
virtual void	stop ()=0
virtual ServiceState	getState () const =0
virtual const char *	getName () const =0

Static Public Attributes
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 interface (TROPIC01)

Provides:

ECC key storage (32 slots)
ECDSA/EdDSA signing
R-Memory storage (512 slots, 476 bytes each)
Hardware TRNG

Definition at line 58 of file ISecureElement.h.

Constructor & Destructor Documentation

◆ ~ISecureElement()

virtual cdc::hal::ISecureElement::~ISecureElement ( )

virtualdefault

Member Function Documentation

◆ attribute()

struct cdc::hal::ISecureElement::__attribute__ ( (packed) )

inline

Definition at line 183 of file ISecureElement.h.

References __attribute__(), flags, moduleId, name, and RMEM_NAME_LEN.

Referenced by __attribute__().

◆ eccDelete()

virtual SeResult cdc::hal::ISecureElement::eccDelete ( uint8_t slot )

pure virtual

Delete key from slot

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

Referenced by cdc::core::wipeTropic().

◆ eccGenerate()

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

pure virtual

Generate new ECC key pair

Parameters

slot	Slot number (0-31)
curve	Curve type

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

References curve.

◆ eccGetPublicKey()

virtual SeResult cdc::hal::ISecureElement::eccGetPublicKey	(	uint8_t	slot,
		uint8_t *	pubKey,
		EccCurve *	curve = nullptr )

pure virtual

Get public key from slot

Parameters

slot	Slot number
pubKey	Output buffer (65 bytes for P256, 32 for Ed25519)
curve	Output: curve type of key

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

References curve.

Referenced by cdc::core::verify_payload_signature(), and verify_state_signature().

◆ eccImport()

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

pure virtual

Import existing private key

Parameters

slot	Slot number
privKey	Private key bytes (32 bytes)
curve	Curve type

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

References curve.

◆ eccSlotUsed()

virtual bool cdc::hal::ISecureElement::eccSlotUsed ( uint8_t slot ) const

pure virtual

Check if slot has a key

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

Referenced by cdc::core::wipeTropic().

◆ ecdsaSign()

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

pure virtual

ECDSA signature (P-256). Implementation hashes the message internally with SHA-256; callers MUST NOT pre-hash.

Parameters

slot	Key slot
Message transfer (badge-to-badge)	Message to sign (arbitrary length)
msgLen	Message length in bytes
sig	Output signature (raw R\|\|S, 64 bytes)
sigLen	Output signature length

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

◆ eddsaSign()

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

pure virtual

EdDSA signature (Ed25519)

Parameters

slot	Key slot
Message transfer (badge-to-badge)	Message to sign
msgLen	Message length
sig	Output signature (64 bytes)

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

◆ getChipId()

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

pure virtual

Get chip serial number

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

◆ getFwVersion()

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

pure virtual

Get firmware version. Buffers receive the 4-byte version as reported by the chip: index 3 = major, 2 = minor, 1 = patch, 0 = build.

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

◆ getRandom()

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

pure virtual

Get random bytes from hardware TRNG, with ESP32 TRNG fallback when the secure-element session is unavailable. A WARN is logged on fallback.

Parameters

buffer	Output buffer
size	Number of bytes

Returns: true if the buffer was filled (from either source)

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

◆ getRandomStrict()

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

pure virtual

Get random bytes from hardware TRNG without falling back. Returns false (and leaves the buffer untouched) when the TROPIC TRNG cannot be reached or returns an error. Use for keys/seeds where software RNG is unacceptable.

Parameters

buffer	Output buffer
size	Number of bytes

Returns: true only when bytes originated from the secure-element TRNG

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

◆ getRmemSlotSize()

virtual uint16_t cdc::hal::ISecureElement::getRmemSlotSize ( ) const

pure virtual

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.

Implemented in cdc::hal::Tropic01Element.

◆ isSessionActive()

virtual bool cdc::hal::ISecureElement::isSessionActive ( ) const

pure virtual

Check if session is active

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

Referenced by cdc::core::PinManager::isStorageAvailable(), and cdc::core::wipeTropic().

◆ rmemErase()

virtual SeResult cdc::hal::ISecureElement::rmemErase ( uint16_t slot )

pure virtual

Erase R-Memory slot

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

Referenced by cdc::core::wipeTropic().

◆ rmemRead()

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

pure virtual

Read from R-Memory slot

Parameters

slot	Slot number (0-511)
data	Output buffer
maxLen	Buffer size
actualLen	Output: actual data length

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

◆ rmemReadWithHeader()

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

pure virtual

Read R-Memory slot with common header + payload

Implemented in cdc::hal::Tropic01Element.

◆ rmemSlotUsed()

virtual bool cdc::hal::ISecureElement::rmemSlotUsed ( uint16_t slot ) const

pure virtual

Check if R-Memory slot has data

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

Referenced by cdc::core::wipeTropic().

◆ rmemWrite()

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

pure virtual

Write to R-Memory slot

Parameters

slot	Slot number
data	Data to write
len	Data length (max 476 bytes)

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

◆ rmemWriteWithHeader()

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

pure virtual

Write R-Memory slot with common header + payload

Implemented in cdc::hal::Tropic01Element.

References flags, moduleId, and name.

◆ sessionEnd()

virtual void cdc::hal::ISecureElement::sessionEnd ( )

pure virtual

End secure session

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

◆ sessionStart()

virtual bool cdc::hal::ISecureElement::sessionStart ( )

pure virtual

Start secure session (required before operations)

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

◆ sleep()

virtual void cdc::hal::ISecureElement::sleep ( )

pure virtual

Put chip to sleep

Implemented in cdc::hal::SecureElementStub, and cdc::hal::Tropic01Element.

Member Data Documentation

◆ ECC_SLOT_COUNT

uint8_t cdc::hal::ISecureElement::ECC_SLOT_COUNT = 32

staticconstexpr

Definition at line 61 of file ISecureElement.h.

Referenced by cdc::serial::cmdTr01EccDel(), cdc::serial::cmdTr01Slots(), cdc::hal::Tropic01Element::eccDelete(), cdc::hal::Tropic01Element::eccGenerate(), cdc::hal::Tropic01Element::eccGetPublicKey(), cdc::hal::Tropic01Element::eccImport(), cdc::hal::Tropic01Element::eccSlotUsed(), cdc::hal::Tropic01Element::ecdsaSign(), cdc::hal::Tropic01Element::eddsaSign(), and cdc::core::wipeTropic().

◆ RMEM_NAME_LEN

uint8_t cdc::hal::ISecureElement::RMEM_NAME_LEN = 16

staticconstexpr

Definition at line 70 of file ISecureElement.h.

Referenced by __attribute__(), cdc::mod_2fa::OathStore::addAccount(), cdc::mod_password::PasswordStore::addEntry(), cdc::mod_2fa::OathStore::findByName(), cdc::mod_2fa::OathStore::readAccount(), cdc::mod_2fa::OathStore::updateAccount(), and cdc::mod_password::PasswordStore::updateEntry().

◆ RMEM_SLOT_COUNT

uint16_t cdc::hal::ISecureElement::RMEM_SLOT_COUNT = 512

staticconstexpr

Definition at line 62 of file ISecureElement.h.

Referenced by cdc::serial::cmdTr01RmemDel(), cdc::serial::cmdTr01RmemRead(), cdc::hal::Tropic01Element::rmemErase(), cdc::hal::Tropic01Element::rmemRead(), cdc::hal::Tropic01Element::rmemReadWithHeader(), cdc::hal::Tropic01Element::rmemSlotUsed(), cdc::hal::Tropic01Element::rmemWrite(), cdc::hal::Tropic01Element::rmemWriteWithHeader(), and cdc::core::wipeTropic().

◆ RMEM_SLOT_SIZE

uint16_t cdc::hal::ISecureElement::RMEM_SLOT_SIZE = 444

staticconstexpr

Definition at line 67 of file ISecureElement.h.

Referenced by cdc::hal::Tropic01Element::init().

◆ RMEM_SLOT_SIZE_MAX

uint16_t cdc::hal::ISecureElement::RMEM_SLOT_SIZE_MAX = 475

staticconstexpr

Definition at line 69 of file ISecureElement.h.

Referenced by cdc::hal::Tropic01Element::init(), cdc::hal::Tropic01Element::rmemReadWithHeader(), and cdc::hal::Tropic01Element::rmemWriteWithHeader().

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

components/cdc_hal/include/cdc_hal/ISecureElement.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~ISecureElement()

Member Function Documentation

◆ __attribute__()

◆ eccDelete()

◆ eccGenerate()

◆ eccGetPublicKey()

◆ eccImport()

◆ eccSlotUsed()

◆ ecdsaSign()

◆ eddsaSign()

◆ getChipId()

◆ getFwVersion()

◆ getRandom()

◆ getRandomStrict()

◆ getRmemSlotSize()

◆ isSessionActive()

◆ rmemErase()

◆ rmemRead()

◆ rmemReadWithHeader()

◆ rmemSlotUsed()

◆ rmemWrite()

◆ rmemWriteWithHeader()

◆ sessionEnd()

◆ sessionStart()

◆ sleep()

Member Data Documentation

◆ ECC_SLOT_COUNT

◆ RMEM_NAME_LEN

◆ RMEM_SLOT_COUNT

◆ RMEM_SLOT_SIZE

◆ RMEM_SLOT_SIZE_MAX

◆ attribute()