lt_l2_api_structs.h File Reference

Layer 2 structure declaration. More...

#include "libtropic_common.h"

Include dependency graph for lt_l2_api_structs.h:

Data Structures
struct	lt_l2_get_info_req_t
	Request to obtain information about TROPIC01. The type of information obtained is distinguished by OBJECT_ID. More...
struct	lt_l2_get_info_rsp_t
	Request to obtain information about TROPIC01. The type of information obtained is distinguished by OBJECT_ID. More...
struct	lt_l2_handshake_req_t
	Request to execute a Secure Channel Handshake and establish a new Secure Channel Session (TROPIC01 moves to Secure Channel Mode). More...
struct	lt_l2_handshake_rsp_t
	Request to execute a Secure Channel Handshake and establish a new Secure Channel Session (TROPIC01 moves to Secure Channel Mode). More...
struct	lt_l2_encrypted_cmd_req_t
	Request to execute an L3 Command. More...
struct	lt_l2_encrypted_cmd_rsp_t
	Request to execute an L3 Command. More...
struct	lt_l2_encrypted_session_abt_req_t
	Request to abort current Secure Channel Session and execution of L3 command (TROPIC01 moves to Idle Mode). More...
struct	lt_l2_encrypted_session_abt_rsp_t
	Request to abort current Secure Channel Session and execution of L3 command (TROPIC01 moves to Idle Mode). More...
struct	lt_l2_resend_req_t
	Request for TROPIC01 to resend the last L2 Response. More...
struct	lt_l2_resend_rsp_t
	Request for TROPIC01 to resend the last L2 Response. More...
struct	lt_l2_sleep_req_t
	Request for TROPIC01 to go to Sleep Mode or Deep Sleep Mode. More...
struct	lt_l2_sleep_rsp_t
	Request for TROPIC01 to go to Sleep Mode or Deep Sleep Mode. More...
struct	lt_l2_startup_req_t
	Request for TROPIC01 to reset. More...
struct	lt_l2_startup_rsp_t
	Request for TROPIC01 to reset. More...
struct	lt_l2_mutable_fw_update_req_t
	Request to start updating mutable FW. Supported only in Start-up mode (i.e. after Startup_Req with MAINTENANCE_REBOOT). Possible to update only same or newer version. NOTE: Chip automatically selects memory space for FW storage and erases it. More...
struct	lt_l2_mutable_fw_update_rsp_t
	Response on lt_l2_mutable_fw_update_req_t. More...
struct	lt_l2_mutable_fw_update_data_req_t
	Request to write a chunk of the new mutable FW into memory bank Supported only in Start-up mode after Mutable_FW_Update_Req successfully processed. More...
struct	lt_l2_mutable_fw_update_data_rsp_t
	response on lt_l2_mutable_fw_update_data_req_t More...
struct	lt_l2_mutable_fw_erase_req_t
	Request to erase the mutable FW stored in a R-Memory bank. Supported only in Start-up mode (i.e. after Startup_Req with MAINTENANCE_REBOOT). More...
struct	lt_l2_mutable_fw_erase_rsp_t
	Request to erase the mutable FW stored in a R-Memory bank. Supported only in Start-up mode (i.e. after Startup_Req with MAINTENANCE_REBOOT). More...
struct	lt_l2_get_log_req_t
	Get log from FW running on RISCV CPU. More...
struct	lt_l2_get_log_rsp_t
	Get log from FW running on RISCV CPU. More...

Macros
#define	LT_L2_GET_INFO_REQ_ID   0x01
	Request ID.
#define	LT_L2_GET_INFO_REQ_LEN   2u
	Request length.
#define	LT_L2_GET_INFO_REQ_OBJECT_ID_X509_CERTIFICATE   0x00
	The X.509 chip certificate read from I-Memory and signed by Tropic Square (max length of 512B).
#define	LT_L2_GET_INFO_REQ_BLOCK_INDEX_DATA_CHUNK_0_127   0x00
	Request for data bytes 0-127 of the object.
#define	LT_L2_GET_INFO_REQ_BLOCK_INDEX_DATA_CHUNK_128_255   0x01
	Request for data bytes 128-255 of the object (only needed for the X.509 certificate).
#define	LT_L2_GET_INFO_REQ_BLOCK_INDEX_DATA_CHUNK_256_383   0x02
	Request for data bytes 128-383 of object (only needed for the X.509 certificate).
#define	LT_L2_GET_INFO_REQ_BLOCK_INDEX_DATA_CHUNK_384_511   0x03
	Request for data bytes 384-511 of object (only needed for the X.509 certificate).
#define	LT_L2_GET_INFO_REQ_OBJECT_ID_CHIP_ID   0x01
	The chip ID - the chip silicon revision and unique device ID (max length of 128B).
#define	LT_L2_GET_INFO_REQ_OBJECT_ID_RISCV_FW_VERSION   0x02
	The RISCV current running FW version (4 Bytes)
#define	LT_L2_GET_INFO_REQ_OBJECT_ID_SPECT_FW_VERSION   0x04
	The SPECT FW version (4 Bytes)
#define	LT_L2_GET_INFO_REQ_OBJECT_ID_FW_BANK   0xb0
	The FW header read from the selected bank id (shown as an index). Supported only in Start-up mode.
#define	LT_L2_GET_INFO_RSP_LEN_MIN   1u
	Response length.
#define	LT_L2_HANDSHAKE_REQ_ID   0x02
	Request ID.
#define	LT_L2_HANDSHAKE_REQ_LEN   33u
	Request length.
#define	LT_L2_HANDSHAKE_REQ_PKEY_INDEX_PAIRING_KEY_SLOT_0   0x00
	Corresponds to $S_{H0Pub}$.
#define	LT_L2_HANDSHAKE_REQ_PKEY_INDEX_PAIRING_KEY_SLOT_1   0x01
	Corresponds to $S_{H1Pub}$.
#define	LT_L2_HANDSHAKE_REQ_PKEY_INDEX_PAIRING_KEY_SLOT_2   0x02
	Corresponds to $S_{H2Pub}$.
#define	LT_L2_HANDSHAKE_REQ_PKEY_INDEX_PAIRING_KEY_SLOT_3   0x03
	Corresponds to $S_{H3Pub}$.
#define	LT_L2_HANDSHAKE_RSP_LEN   48u
	Response length.
#define	LT_L2_ENCRYPTED_CMD_REQ_ID   0x04
	Request ID.
#define	LT_L2_ENCRYPTED_CMD_REQ_LEN_MIN   19u
	Request length.
#define	LT_L2_ENCRYPTED_CMD_REQ_CMD_CIPHERTEXT_LEN_MIN   1u
#define	LT_L2_ENCRYPTED_CMD_REQ_CMD_CIPHERTEXT_LEN_MAX   4096u
#define	LT_L2_ENCRYPTED_CMD_RSP_LEN_MIN   19u
	Response length.
#define	LT_L2_ENCRYPTED_SESSION_ABT_ID   0x08
	Request ID.
#define	LT_L2_ENCRYPTED_SESSION_ABT_LEN   0u
	Request length.
#define	LT_L2_ENCRYPTED_SESSION_ABT_RSP_LEN   0u
	Response length.
#define	LT_L2_RESEND_REQ_ID   0x10
	Request ID.
#define	LT_L2_RESEND_REQ_LEN   0u
	Request length.
#define	LT_L2_RESEND_RSP_LEN   0u
	Response length.
#define	LT_L2_SLEEP_REQ_ID   0x20
	Request ID.
#define	LT_L2_SLEEP_REQ_LEN   1u
	Request length.
#define	LT_L2_SLEEP_REQ_SLEEP_KIND_SLEEP_MODE   0x05
	Sleep Mode.
#define	LT_L2_SLEEP_REQ_SLEEP_KIND_DEEP_SLEEP_MODE   0x0a
	Deep Sleep Mode.
#define	LT_L2_SLEEP_RSP_LEN   0u
	Response length.
#define	LT_L2_STARTUP_REQ_ID   0xb3
	Request ID.
#define	LT_L2_STARTUP_REQ_LEN   1u
	Request length.
#define	LT_L2_STARTUP_REQ_STARTUP_ID_REBOOT   0x01
	Restart, then initialize as if a power-cycle was applied.
#define	LT_L2_STARTUP_REQ_STARTUP_ID_MAINTENANCE_REBOOT   0x03
	Restart, then initialize. Stay in Start-up mode and do not load the mutable FW from R-Memory.
#define	LT_L2_STARTUP_RSP_LEN   0u
	Response length.
#define	LT_L2_MUTABLE_FW_UPDATE_REQ_ID   0xb0
	Request ID.
#define	LT_L2_MUTABLE_FW_UPDATE_REQ_LEN   0x68
	Request min length.
#define	LT_L2_MUTABLE_FW_UPDATE_RSP_LEN   0u
	Response length.
#define	LT_L2_MUTABLE_FW_UPDATE_REQ_TYPE_FW_TYPE_CPU   1
	Firmware type for RISC-V main CPU.
#define	LT_L2_MUTABLE_FW_UPDATE_REQ_TYPE_FW_TYPE_SPECT   2
	Firmware type for SPECT coprocessor.
#define	TS_L2_MUTABLE_FW_UPDATE_DATA_REQ   0xb1
	Request ID.
#define	LT_L2_MUTABLE_FW_ERASE_REQ_ID   0xb2
	Request ID.
#define	LT_L2_MUTABLE_FW_ERASE_REQ_LEN   1u
	Request length.
#define	LT_L2_MUTABLE_FW_ERASE_REQ_BANK_ID_FW1   0x01
	Firmware bank 1.
#define	LT_L2_MUTABLE_FW_ERASE_REQ_BANK_ID_FW2   0x02
	Firmware bank 2.
#define	LT_L2_MUTABLE_FW_ERASE_REQ_BANK_ID_SPECT1   0x11
	SPECT bank 1.
#define	LT_L2_MUTABLE_FW_ERASE_REQ_BANK_ID_SPECT2   0x12
	SPECT bank 2.
#define	LT_L2_MUTABLE_FW_ERASE_RSP_LEN   0u
	Response length.
#define	LT_L2_GET_LOG_REQ_ID   0xa2
	Request ID.
#define	LT_L2_GET_LOG_REQ_LEN   0u
	Request length.
#define	LT_L2_GET_LOG_RSP_LEN_MIN   0u
	Response length.

Detailed Description

Author

Tropic Square s.r.o.

---

Data Structure Documentation

lt_l2_get_info_req_t

struct lt_l2_get_info_req_t

NOTE: If Start-up mode is active, TROPIC01 executes the immutable FW. Any version identification then has the highest bit set to 1. SPECT_FW_VERSION then returns a dummy value of 0x80000000 because the SPECT FW is part of the immutable FW.

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	object_id	The Identifier of the requested object.
uint8_t	block_index	The index of the 128 Byte long block to request.
uint8_t	crc[2]	Checksum

lt_l2_get_info_rsp_t

struct lt_l2_get_info_rsp_t

NOTE: If Start-up mode is active, TROPIC01 executes the immutable FW. Any version identification then has the highest bit set to 1. SPECT_FW_VERSION then returns a dummy value of 0x80000000 because the SPECT FW is part of the immutable FW.

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	object[128]	The data content of the requested object block.
uint8_t	crc[2]	Checksum

lt_l2_handshake_req_t

struct lt_l2_handshake_req_t

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	e_hpub[32]	The Host MCU's Ephemeral X25519 public key. A little endian encoding of the x-coordinate from the public Curve25519 point. Ephemeral Key of Host MCU.
uint8_t	pkey_index	The index of the Pairing Key slot to establish a Secure Channel Session with (TROPIC01 fetches $S_{HiPub}$ from the Pairing Key slot specified in this field). Pairing Key slot
uint8_t	crc[2]	Checksum

lt_l2_handshake_rsp_t

struct lt_l2_handshake_rsp_t

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	e_tpub[32]	TROPIC01's X25519 Ephemeral key. Ephemeral Key of TROPIC01.
uint8_t	t_tauth[16]	The Secure Channel Handshake Authentication Tag. Authentication Tag
uint8_t	crc[2]	Checksum

lt_l2_encrypted_cmd_req_t

struct lt_l2_encrypted_cmd_req_t

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	l3_chunk[255]	Contains a chunk of encrypted command
uint8_t	crc[2]	Checksum

lt_l2_encrypted_cmd_rsp_t

struct lt_l2_encrypted_cmd_rsp_t

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	l3_chunk[255]	The size of the RES_CIPHERTEXT L3 Field in bytes. Contains a chunk of encrypted command
uint8_t	crc[2]	Checksum

lt_l2_encrypted_session_abt_req_t

struct lt_l2_encrypted_session_abt_req_t

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	crc[2]	Checksum

lt_l2_encrypted_session_abt_rsp_t

struct lt_l2_encrypted_session_abt_rsp_t

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	crc[2]	Checksum

lt_l2_resend_req_t

struct lt_l2_resend_req_t

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	crc[2]	Checksum

lt_l2_resend_rsp_t

struct lt_l2_resend_rsp_t

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	crc[2]	Checksum

lt_l2_sleep_req_t

struct lt_l2_sleep_req_t

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	sleep_kind	The type of Sleep mode TROPIC01 moves to. Sleep Kind
uint8_t	crc[2]	Checksum

lt_l2_sleep_rsp_t

struct lt_l2_sleep_rsp_t

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	crc[2]	Checksum

lt_l2_startup_req_t

struct lt_l2_startup_req_t

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	startup_id	The request ID
uint8_t	crc[2]	Checksum

lt_l2_startup_rsp_t

struct lt_l2_startup_rsp_t

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	crc[2]	Checksum

lt_l2_mutable_fw_update_req_t

struct lt_l2_mutable_fw_update_req_t

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	signature[64]	Signature of SHA256 hash of all following data in this packet
uint8_t	hash[32]	SHA256 HASH of first FW chunk of data sent using Mutable_FW_Update_Data
uint16_t	type	FW type which is going to be updated
uint8_t	padding	Padding, zero value
uint8_t	header_version	Version of used header
uint32_t	version	Version of FW
uint8_t	crc[2]	Checksum

lt_l2_mutable_fw_update_rsp_t

struct lt_l2_mutable_fw_update_rsp_t

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	crc[2]	Checksum

lt_l2_mutable_fw_update_data_req_t

struct lt_l2_mutable_fw_update_data_req_t

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	hash[32]	SHA256 HASH of the next FW chunk of data sent using Mutable_FW_Update_Data
uint16_t	offset	The offset of the specific bank to write the FW chunk data to
uint8_t	data[220]	The binary data to write. Data size should be a multiple of 4
uint8_t	crc[2]	Checksum

lt_l2_mutable_fw_update_data_rsp_t

struct lt_l2_mutable_fw_update_data_rsp_t

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	crc[2]	Checksum

lt_l2_mutable_fw_erase_req_t

struct lt_l2_mutable_fw_erase_req_t

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	bank_id	The Identifier of the bank to erase. The same choices as above.
uint8_t	crc[2]	Checksum

lt_l2_mutable_fw_erase_rsp_t

struct lt_l2_mutable_fw_erase_rsp_t

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	crc[2]	Checksum

lt_l2_get_log_req_t

struct lt_l2_get_log_req_t

Data Fields
uint8_t	req_id	Request ID byte
uint8_t	req_len	Length byte
uint8_t	crc[2]	Checksum

lt_l2_get_log_rsp_t

struct lt_l2_get_log_rsp_t

Data Fields
uint8_t	chip_status	CHIP_STATUS byte
uint8_t	status	L2 status byte
uint8_t	rsp_len	Length of incoming data
uint8_t	log_msg[GET_LOG_MAX_MSG_LEN]	Log message of RISC-V FW
uint8_t	crc[2]	Checksum