SecureElement / TROPIC01

ECC key slots and retained-memory storage on the TROPIC01. More...

Macros
#define	ECC_CURVE_P256   0
#define	ECC_CURVE_ED25519   1
#define	HOST_RMEM_NAME_MAX   15
#define	HOST_ECC_NAME_MAX   15

Functions
int	host_rmem_read_named (const char *name, uint8_t *buf, size_t *len)
	Read a named retained-memory slot.
int	host_rmem_write_named (const char *name, const uint8_t *buf, size_t len)
	Write up to host_rmem_slot_size() bytes into a named rmem slot.
int	host_rmem_erase_named (const char *name)
	Erase the contents of a named rmem slot.
bool	host_rmem_name_used (const char *name)
	True if the named rmem slot currently holds data.
uint16_t	host_rmem_slot_size (void)
	Maximum payload bytes per rmem slot.
int	host_ecc_generate (const char *name, uint8_t curve)
	Generate a fresh ECC key for the named slot.
int	host_ecc_import (const char *name, const uint8_t *priv, uint8_t curve)
	Import an externally-generated private key for the named slot.
int	host_ecc_pubkey (const char *name, uint8_t *pub, uint8_t curve)
	Export the public key for the named slot.
int	host_ecc_delete (const char *name)
	Erase the named ECC key and free its pool slot.
bool	host_ecc_exists (const char *name)
	True when the named ECC key currently holds a key.
int	host_ecdsa_sign (const char *name, const uint8_t *msg, size_t len, uint8_t sig[64])
	ECDSA-sign Message transfer (badge-to-badge) with the P-256 named key; writes 64-byte raw sig.
int	host_eddsa_sign (const char *name, const uint8_t *msg, size_t len, uint8_t sig[64])
	Ed25519-sign Message transfer (badge-to-badge) with the named key; writes 64-byte signature.
int	host_se_chip_id (uint8_t *serial, size_t *len)
	Read the TROPIC01 chip serial / identity blob.
int	host_se_fw_version (uint8_t *riscv, uint8_t *spect)
	Read TROPIC01 firmware versions for the RISC-V CPU and SPECT core.

Detailed Description

ECC key slots and retained-memory storage on the TROPIC01.

ECC slots hold private keys that never leave the chip. Retained-memory (rmem) slots offer persistent named storage shared across reboots and plugin reinstalls; declare names in the plugin manifest under capabilities.rmem.

Macro Definition Documentation

ECC_CURVE_ED25519

#define ECC_CURVE_ED25519   1

Definition at line 237 of file host_api.h.

ECC_CURVE_P256

#define ECC_CURVE_P256   0

Definition at line 236 of file host_api.h.

HOST_ECC_NAME_MAX

#define HOST_ECC_NAME_MAX   15

Definition at line 281 of file host_api.h.

Referenced by host_ecc_generate(), and cdc::plugin_manager::CapabilityChecker::validate().

HOST_RMEM_NAME_MAX

#define HOST_RMEM_NAME_MAX   15

Definition at line 249 of file host_api.h.

Referenced by host_rmem_write_named().

Function Documentation

host_ecc_delete()

int host_ecc_delete

(

const char *

name

)

Erase the named ECC key and free its pool slot.

Definition at line 300 of file host_api_se.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and name.

Referenced by cdc::plugin_manager::w_host_ecc_delete().

host_ecc_exists()

bool host_ecc_exists

(

const char *

name

)

True when the named ECC key currently holds a key.

Definition at line 314 of file host_api_se.cpp.

References name.

Referenced by cdc::plugin_manager::w_host_ecc_exists().

host_ecc_generate()

int host_ecc_generate	(	const char *	name,
		uint8_t	curve )

Generate a fresh ECC key for the named slot.

Definition at line 270 of file host_api_se.cpp.

References curve, HOST_ECC_NAME_MAX, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NO_MEMORY, HOST_ERR_NOT_FOUND, and name.

Referenced by cdc::plugin_manager::w_host_ecc_generate().

host_ecc_import()

int host_ecc_import	(	const char *	name,
		const uint8_t *	priv,
		uint8_t	curve )

Import an externally-generated private key for the named slot.

Definition at line 283 of file host_api_se.cpp.

References HOST_ERR_NOT_SUPPORTED.

Referenced by cdc::plugin_manager::w_host_ecc_import().

host_ecc_pubkey()

int host_ecc_pubkey	(	const char *	name,
		uint8_t *	pub,
		uint8_t	curve )

Export the public key for the named slot.

Definition at line 288 of file host_api_se.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and name.

Referenced by cdc::plugin_manager::w_host_ecc_pubkey().

host_ecdsa_sign()

int host_ecdsa_sign	(	const char *	name,
		const uint8_t *	msg,
		size_t	len,
		uint8_t	sig[64] )

ECDSA-sign Message transfer (badge-to-badge) with the P-256 named key; writes 64-byte raw sig.

Definition at line 325 of file host_api_se.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and name.

Referenced by cdc::plugin_manager::w_host_ecdsa_sign().

host_eddsa_sign()

int host_eddsa_sign	(	const char *	name,
		const uint8_t *	msg,
		size_t	len,
		uint8_t	sig[64] )

Ed25519-sign Message transfer (badge-to-badge) with the named key; writes 64-byte signature.

Definition at line 338 of file host_api_se.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and name.

Referenced by cdc::plugin_manager::w_host_eddsa_sign().

host_rmem_erase_named()

int host_rmem_erase_named

(

const char *

name

)

Erase the contents of a named rmem slot.

Definition at line 239 of file host_api_se.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and name.

Referenced by cdc::plugin_manager::w_host_rmem_erase_named().

host_rmem_name_used()

bool host_rmem_name_used

(

const char *

name

)

True if the named rmem slot currently holds data.

Definition at line 254 of file host_api_se.cpp.

References name.

Referenced by cdc::plugin_manager::w_host_rmem_name_used().

host_rmem_read_named()

int host_rmem_read_named	(	const char *	name,
		uint8_t *	buf,
		size_t *	len )

Read a named retained-memory slot.

Parameters

name	NUL-terminated name, max HOST_RMEM_NAME_MAX bytes.
buf	Output buffer.
len	In: capacity of buf; out: bytes actually read.

Definition at line 197 of file host_api_se.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_OK, and name.

Referenced by cdc::plugin_manager::w_host_rmem_read_named().

host_rmem_slot_size()

uint16_t host_rmem_slot_size

(

void

)

Maximum payload bytes per rmem slot.

Definition at line 264 of file host_api_se.cpp.

Referenced by cdc::plugin_manager::w_host_rmem_slot_size().

host_rmem_write_named()

int host_rmem_write_named	(	const char *	name,
		const uint8_t *	buf,
		size_t	len )

Write up to host_rmem_slot_size() bytes into a named rmem slot.

Definition at line 218 of file host_api_se.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_ERR_RMEM_FULL, HOST_RMEM_NAME_MAX, and name.

Referenced by cdc::plugin_manager::w_host_rmem_write_named().

host_se_chip_id()

int host_se_chip_id	(	uint8_t *	serial,
		size_t *	len )

Read the TROPIC01 chip serial / identity blob.

Parameters

serial	Output buffer.
len	In: capacity; out: bytes written.

Definition at line 350 of file host_api_se.cpp.

References HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_se_chip_id().

host_se_fw_version()

int host_se_fw_version	(	uint8_t *	riscv,
		uint8_t *	spect )

Read TROPIC01 firmware versions for the RISC-V CPU and SPECT core.

Definition at line 361 of file host_api_se.cpp.

References HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_se_fw_version().