libtropic_common.h File Reference

Shared definitions and functions commonly used by more libtropic's layers. More...

#include <stdbool.h>
#include <stdint.h>
#include "libtropic_macros.h"
#include "tropic01_application_co.h"
#include "tropic01_bootloader_co.h"

Include dependency graph for libtropic_common.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	lt_l3_gen_frame_t
	Generic L3 command and result frame. More...
struct	lt_l2_state_t
struct	lt_l3_state_t
struct	lt_tr01_attrs_t
	Configures attributes that are different among TROPIC01's Application FW versions. More...
struct	lt_handle_t
struct	lt_cert_store_t
	Certificate store contents. More...
struct	lt_ser_num_t
	Structure used to parse content of CHIP_ID field. More...
struct	lt_chip_id_t
	Data in this struct comes from BP (batch package) yml file. CHIP_INFO is read into this struct. More...
struct	lt_header_boot_v1_t
	When in MAINTENANCE mode, it is possible to read firmware header from a firmware bank. Returned data differs based on bootloader version. This header layout is returned by bootloader version v1.0.1. More...
struct	lt_header_boot_v2_t
	When in MAINTENANCE mode, it is possible to read firmware header from a firmware bank. Returned data differs based on bootloader version. This header layout is returned by bootloader version v2.0.1. More...
struct	lt_host_eph_keys_t
	Stores Host MCU ephemeral keys. More...
struct	lt_config_obj_desc_t
	This structure is used in this example to simplify looping through all config addresses and printing out them into debug. More...
struct	lt_config_t
	Structure to hold all configuration objects. More...

Macros
#define	TR01_L1_CHIP_STATUS_SIZE   1u
	Size of CHIP_STATUS field.
#define	TR01_L1_LEN_MIN   TR01_L1_CHIP_STATUS_SIZE
	Maximal number of data bytes in one L1 transfer.
#define	TR01_L1_LEN_MAX   (TR01_L1_CHIP_STATUS_SIZE + TR01_L2_MAX_FRAME_SIZE)
	Maximal number of data bytes in one L1 transfer.
#define	TR01_L2_REQ_ID_OFFSET   0u
	Offset of REQ_ID field.
#define	TR01_L2_REQ_LEN_OFFSET   1u
	Offset of REQ_LEN field.
#define	TR01_L2_REQ_DATA_REQ_CRC_OFFSET   2u
	Offset of REQ_DATA field or REQ_CRC field in case of zero data length.
#define	TR01_L2_CHIP_STATUS_OFFSET   0u
	Offset of CHIP_STATUS field.
#define	TR01_L2_STATUS_OFFSET   1u
	Offset of STATUS field.
#define	TR01_L2_RSP_LEN_OFFSET   2u
	Offset of RSP_LEN field.
#define	TR01_L2_RSP_DATA_RSP_CRC_OFFSET   3u
	Offset of RSP_DATA field or RSP_CRC field in case of zero data length.
#define	TR01_L2_REQ_ID_SIZE   1u
	Size of REQ_ID field.
#define	TR01_L2_REQ_RSP_LEN_SIZE   1u
	Size of REQ_LEN or RSP_LEN field.
#define	TR01_L2_REQ_RSP_CRC_SIZE   2u
	Size of REQ_CRC or RSP_CRC field.
#define	TR01_L2_STATUS_SIZE   1u
	Size of STATUS field.
#define	TR01_L2_CHUNK_MAX_DATA_SIZE   252u
	Maximal size of data field in one L2 transfer.
#define	TR01_L2_MAX_FRAME_SIZE    (TR01_L2_STATUS_SIZE + TR01_L2_REQ_RSP_LEN_SIZE + TR01_L2_CHUNK_MAX_DATA_SIZE + TR01_L2_REQ_RSP_CRC_SIZE)
	Maximal size of one l2 frame.
#define	TR01_L3_IV_SIZE   12u
	Size of IV.
#define	TR01_L3_SIZE_SIZE   2u
	Size of CMD_SIZE and RES_SIZE fields.
#define	TR01_L3_TAG_SIZE   16u
	Size of CMD_TAG and RES_TAG fields.
#define	TR01_L3_CMD_ID_SIZE   1u
	Size of CMD_ID field.
#define	TR01_L3_RESULT_SIZE   1u
	Size of the RESULT field in L3 Result.
#define	TR01_L3_CMD_CIPHERTEXT_MAX_SIZE   4112u
	Max size of L3 Command ciphertext.
#define	TR01_L3_RES_CIPHERTEXT_MAX_SIZE   4097u
	Max size of L3 Result ciphertext.
#define	TR01_L3_CIPHERTEXT_MAX_SIZE   LT_COMPTIME_MAX(TR01_L3_CMD_CIPHERTEXT_MAX_SIZE, TR01_L3_RES_CIPHERTEXT_MAX_SIZE)
	Max size of ciphertext for both L3 Commands and L3 Responses.
#define	TR01_L3_PACKET_MAX_SIZE   (TR01_L3_SIZE_SIZE + TR01_L3_CIPHERTEXT_MAX_SIZE + TR01_L3_TAG_SIZE)
	Max possible size of one unit of transport on L3 (for both Commands and Responses).
#define	LT_SIZE_OF_L3_BUFF   TR01_L3_PACKET_MAX_SIZE
#define	TR01_AES256_KEY_LEN   32
	Length of key used by AES256.
#define	LT_TR01_REBOOT_DELAY_MS   250
#define	TR01_L2_GET_INFO_REQ_CERT_SIZE_TOTAL   3840
	Maximal size of TROPIC01's certificate.
#define	TR01_L2_GET_INFO_REQ_CERT_SIZE_SINGLE   700
#define	LT_CERT_STORE_VERSION   1
#define	LT_NUM_CERTIFICATES   4
#define	TR01_L2_GET_INFO_CHIP_ID_SIZE   128
	Maximal size of returned CHIP ID.
#define	TR01_CHIP_PKG_BARE_SILICON_ID   0x8000
	Package type ID for bare silicon.
#define	TR01_CHIP_PKG_QFN32_ID   0x80AA
	Package type ID for QFN32.
#define	TR01_FAB_ID_TROPIC_SQUARE_LAB   0xF00
#define	TR01_FAB_ID_EPS_BRNO   0x001
#define	TR01_L2_GET_INFO_RISCV_FW_SIZE   4
	Maximal size of returned RISCV fw version.
#define	TR01_L2_GET_INFO_SPECT_FW_SIZE   4
	Maximal size of returned SPECT fw version.
#define	TR01_L2_GET_INFO_FW_HEADER_SIZE_BOOT_V1   20
	Maximal size of returned fw header.
#define	TR01_L2_GET_INFO_FW_HEADER_SIZE_BOOT_V2   52
#define	TR01_L2_GET_INFO_FW_HEADER_SIZE_BOOT_V2_EMPTY_BANK   0
#define	TR01_L2_GET_INFO_FW_HEADER_SIZE   TR01_L2_GET_INFO_FW_HEADER_SIZE_BOOT_V2
	Maximal size of returned fw header.
#define	TR01_X25519_KEY_LEN   32
	Length of key used in X25519 function.
#define	TR01_X25519_KEY_BITS   255
	Bit size of Curve25519 used for X25519 (Useful for crypto backends which expect bit-size).
#define	TR01_STPUB_LEN   TR01_X25519_KEY_LEN
	Length of TROPIC01 X25519 public key for a Secure Channel Handshake.
#define	TR01_STPRIV_LEN   TR01_X25519_KEY_LEN
	Length of TROPIC01 X25519 private key for a Secure Channel Handshake.
#define	TR01_SHIPUB_LEN   TR01_X25519_KEY_LEN
	Length of X25519 public key of the Host MCU to execute a Secure Channel Handshake on Pairing Key slot i.
#define	TR01_SHIPRIV_LEN   TR01_X25519_KEY_LEN
	Length of X25519 private key of the Host MCU to execute a Secure Channel Handshake on Pairing Key slot i.
#define	TR01_ETPRIV_LEN   TR01_X25519_KEY_LEN
	Length of TROPIC01 ephemeral private key.
#define	TR01_ETPUB_LEN   TR01_X25519_KEY_LEN
	Length of TROPIC01 ephemeral public key.
#define	TR01_EHPRIV_LEN   TR01_X25519_KEY_LEN
	Length of Host MCU ephemeral private key.
#define	TR01_EHPUB_LEN   TR01_X25519_KEY_LEN
	Length of Host MCU ephemeral public key.
#define	TR01_L2_SLEEP_KIND_SLEEP   0x05
	Basic sleep mode.
#define	TR01_GET_LOG_MAX_MSG_LEN   255
	Maximal length of TROPIC01's log message.
#define	TR01_PING_LEN_MAX   4096
	Maximal length of Ping command message.
#define	TR01_R_MEM_DATA_SIZE_MIN   (1)
	Minimal size of one data slot in bytes.
#define	TR01_R_MEM_DATA_SLOT_MAX   (511)
	Index of last data slot. TROPIC01 contains 512 slots indexed 0-511.
#define	TR01_RANDOM_VALUE_GET_LEN_MAX   255
	Maximum number of random bytes requested at once.
#define	TR01_CURVE_P256_PUBKEY_LEN   64
	Length of public keys for P256 curve.
#define	TR01_CURVE_ED25519_PUBKEY_LEN   32
	Length of public keys for ED25519 curve.
#define	TR01_CURVE_PRIVKEY_LEN   32
	Common length of private keys for both P256 and ED25519 curves.
#define	TR01_ECDSA_EDDSA_SIGNATURE_LENGTH   64
	Length of the EC signature (RS) for both ECDSA and EDDSA.
#define	TR01_MCOUNTER_VALUE_MAX   0xFFFFFFFE
	Maximal allowed value of the monotonic counter.
#define	TR01_MAC_AND_DESTROY_DATA_SIZE   32u
	The size of returned MAC-and-Destroy data (secret/key)
#define	TR01_MACANDD_ROUNDS_MAX   128
	Maximal number of Mac And Destroy tries possible with TROPIC01.
#define	TR01_SERIAL_CODE_SIZE   32u
	Maximal size of returned serial code.
#define	LT_TO_PAIRING_KEY_SH0(x)   ((x) << 0)
	Macro to control which session can access command targeting content of pairing key SH0.
#define	LT_TO_PAIRING_KEY_SH1(x)   ((x) << 8)
	Macro to control which session can access command targeting content of pairing key SH1.
#define	LT_TO_PAIRING_KEY_SH2(x)   ((x) << 16)
	Macro to control which session can access command targeting content of pairing key SH2.
#define	LT_TO_PAIRING_KEY_SH3(x)   ((x) << 24)
	Macro to control which session can access command targeting content of pairing key SH3.
#define	LT_TO_MCOUNTER_0_3(x)   ((x) << 0)
	Macro to control which session can access command targeting counter 0-3.
#define	LT_TO_MCOUNTER_4_7(x)   ((x) << 8)
	Macro to control which session can access command targeting counter 4-7.
#define	LT_TO_MCOUNTER_8_11(x)   ((x) << 16)
	Macro to control which session can access command targeting counter 8-11.
#define	LT_TO_MCOUNTER_12_15(x)   ((x) << 24)
	Macro to control which session can access command targeting counter 12-15.
#define	LT_TO_ECC_KEY_SLOT_0_7(x)   ((x) << 0)
	Macro to control which session can access command targeting ECC_SLOT 0-7.
#define	LT_TO_ECC_KEY_SLOT_8_15(x)   ((x) << 8)
	Macro to control which session can access command targeting ECC_SLOT 8-15.
#define	LT_TO_ECC_KEY_SLOT_16_23(x)   ((x) << 16)
	Macro to control which session can access command targeting ECC_SLOT 16-23.
#define	LT_TO_ECC_KEY_SLOT_24_31(x)   ((x) << 24)
	Macro to control which session can access command targeting ECC_SLOT 24-31.
#define	LT_TO_MACANDD_SLOT_0_31(x)   ((x) << APPLICATION_CO_CFG_UAP_MAC_AND_DESTROY_MACANDD_0_31_POS)
	Macro to control which session can access command targeting MACANDD slot 0-31.
#define	LT_TO_MACANDD_SLOT_32_63(x)   ((x) << APPLICATION_CO_CFG_UAP_MAC_AND_DESTROY_MACANDD_32_63_POS)
	Macro to control which session can access command targeting MACANDD slot 32-63.
#define	LT_TO_MACANDD_SLOT_64_95(x)   ((x) << APPLICATION_CO_CFG_UAP_MAC_AND_DESTROY_MACANDD_64_95_POS)
	Macro to control which session can access command targeting MACANDD slot 64-95.
#define	LT_TO_MACANDD_SLOT_96_127(x)   ((x) << APPLICATION_CO_CFG_UAP_MAC_AND_DESTROY_MACANDD_96_127_POS)
	Macro to control which session can access command targeting MACANDD slot 96-127.
#define	LT_SESSION_SH0_HAS_ACCESS   (uint8_t)0x01
	Macro to control if session SH0 has access to a specific command.
#define	LT_SESSION_SH1_HAS_ACCESS   (uint8_t)0x02
	Macro to control if session SH1 has access to a specific command.
#define	LT_SESSION_SH2_HAS_ACCESS   (uint8_t)0x04
	Macro to control if session SH2 has access to a specific command.
#define	LT_SESSION_SH3_HAS_ACCESS   (uint8_t)0x08
	Macro to control if session SH3 has access to a specific command.
#define	LT_CONFIG_OBJ_CNT   27
	Number of configuration objects in lt_config_t.

Typedefs
typedef struct lt_l3_gen_frame_t	lt_l3_gen_frame_t
	Generic L3 command and result frame.
typedef enum lt_startup_id_t	lt_startup_id_t
	Values for the Startup_Req command, which TROPIC01 uses to determine the mode to reboot into.
typedef enum lt_tr01_mode_t	lt_tr01_mode_t
	Interprets TROPIC01's Chip Modes and CHIP_STATUS values (described in the TROPIC01 datasheet) and defines new modes (not described in the TROPIC01 datasheet) based on them. These modes are practical when working with the chip.
typedef struct lt_l2_state_t	lt_l2_state_t
typedef enum lt_secure_session_status_t	lt_secure_session_status_t
	Used to indicate whether the Secure Session is on or off.
typedef struct lt_l3_state_t	lt_l3_state_t
typedef struct lt_tr01_attrs_t	lt_tr01_attrs_t
	Configures attributes that are different among TROPIC01's Application FW versions.
typedef struct lt_handle_t	lt_handle_t
typedef enum lt_ret_t	lt_ret_t
	Enum return type.
typedef enum lt_cert_kind_t	lt_cert_kind_t
typedef struct lt_cert_store_t	lt_cert_store_t
	Certificate store contents.
typedef struct lt_ser_num_t	lt_ser_num_t
	Structure used to parse content of CHIP_ID field.
typedef struct lt_chip_id_t	lt_chip_id_t
	Data in this struct comes from BP (batch package) yml file. CHIP_INFO is read into this struct.
typedef enum lt_bank_id_t	lt_bank_id_t
	BANK ID.
typedef struct lt_header_boot_v1_t	lt_header_boot_v1_t
	When in MAINTENANCE mode, it is possible to read firmware header from a firmware bank. Returned data differs based on bootloader version. This header layout is returned by bootloader version v1.0.1.
typedef struct lt_header_boot_v2_t	lt_header_boot_v2_t
	When in MAINTENANCE mode, it is possible to read firmware header from a firmware bank. Returned data differs based on bootloader version. This header layout is returned by bootloader version v2.0.1.
typedef enum lt_pkey_index_t	lt_pkey_index_t
	Pairing key indexes corresponds to S_HiPub.
typedef struct lt_host_eph_keys_t	lt_host_eph_keys_t
	Stores Host MCU ephemeral keys.
typedef enum lt_config_obj_addr_t	lt_config_obj_addr_t
	CONFIGURATION_OBJECTS_REGISTERS memory map.
typedef enum lt_config_obj_idx_t	lt_config_obj_idx_t
	CONFIGURATION_OBJECTS_REGISTERS index map to lt_config_t.
typedef enum lt_ecc_slot_t	lt_ecc_slot_t
	ECC key slot indexes.
typedef enum lt_ecc_curve_type_t	lt_ecc_curve_type_t
	ECC key type.
typedef enum lt_ecc_key_origin_t	lt_ecc_key_origin_t
	ECC key origin.
typedef enum lt_mcounter_index_t	lt_mcounter_index_t
	Use to choose one from 16 counters.
typedef enum lt_mac_and_destroy_slot_t	lt_mac_and_destroy_slot_t
	Mac-and-Destroy slot indexes.
typedef struct lt_config_obj_desc_t	lt_config_obj_desc_t
	This structure is used in this example to simplify looping through all config addresses and printing out them into debug.
typedef struct lt_config_t	lt_config_t
	Structure to hold all configuration objects.

Enumerations
enum	lt_startup_id_t { TR01_REBOOT = 0x01 , TR01_MAINTENANCE_REBOOT = 0x03 }
	Values for the Startup_Req command, which TROPIC01 uses to determine the mode to reboot into. More...
enum	lt_tr01_mode_t { LT_TR01_MAINTENANCE , LT_TR01_APPLICATION , LT_TR01_ALARM }
	Interprets TROPIC01's Chip Modes and CHIP_STATUS values (described in the TROPIC01 datasheet) and defines new modes (not described in the TROPIC01 datasheet) based on them. These modes are practical when working with the chip. More...
enum	lt_secure_session_status_t { LT_SECURE_SESSION_ON = 0x5A5A5A5A , LT_SECURE_SESSION_OFF = 0 }
	Used to indicate whether the Secure Session is on or off.
enum	lt_ret_t {   LT_OK = 0 , LT_FAIL = 1 , LT_HOST_NO_SESSION = 2 , LT_PARAM_ERR = 3 ,   LT_CRYPTO_ERR = 4 , LT_APP_FW_TOO_NEW = 5 , LT_REBOOT_UNSUCCESSFUL = 6 , LT_L1_SPI_ERROR = 7 ,   LT_L1_DATA_LEN_ERROR = 8 , LT_L1_CHIP_STARTUP_MODE = 9 , LT_L1_CHIP_ALARM_MODE = 10 , LT_L1_CHIP_BUSY = 11 ,   LT_L1_INT_TIMEOUT = 12 , LT_L3_SLOT_NOT_EMPTY = 13 , LT_L3_SLOT_EXPIRED = 14 , LT_L3_INVALID_KEY = 15 ,   LT_L3_UPDATE_ERR = 16 , LT_L3_COUNTER_INVALID = 17 , LT_L3_SLOT_EMPTY = 18 , LT_L3_SLOT_INVALID = 19 ,   LT_L3_OK = 20 , LT_L3_FAIL = 21 , LT_L3_UNAUTHORIZED = 22 , LT_L3_INVALID_CMD = 23 ,   LT_L3_HARDWARE_FAIL = 24 , LT_L3_DATA_LEN_ERROR = 25 , LT_L3_RES_SIZE_ERROR = 26 , LT_L3_BUFFER_TOO_SMALL = 27 ,   LT_L3_R_MEM_DATA_READ_SLOT_EMPTY = 28 , LT_L3_RESULT_UNKNOWN = 29 , LT_L2_REQ_CONT = 30 , LT_L2_RES_CONT = 31 ,   LT_L2_RESP_DISABLED = 32 , LT_L2_HSK_ERR = 33 , LT_L2_NO_SESSION = 34 , LT_L2_TAG_ERR = 35 ,   LT_L2_CRC_ERR = 36 , LT_L2_GEN_ERR = 37 , LT_L2_NO_RESP = 38 , LT_L2_UNKNOWN_REQ = 39 ,   LT_L2_IN_CRC_ERR = 40 , LT_L2_RSP_LEN_ERROR = 41 , LT_L2_STATUS_UNKNOWN = 42 , LT_CERT_STORE_INVALID = 43 ,   LT_CERT_UNSUPPORTED = 44 , LT_CERT_ITEM_NOT_FOUND = 45 , LT_NONCE_OVERFLOW = 46 , LT_RET_T_LAST_VALUE = 47 }
	Enum return type. More...
enum	lt_cert_kind_t { LT_CERT_KIND_DEVICE = 0 , LT_CERT_KIND_XXXX = 1 , LT_CERT_KIND_TROPIC01 = 2 , LT_CERT_KIND_TROPIC_ROOT = 3 }
enum	lt_bank_id_t { TR01_FW_BANK_FW1 = 1 , TR01_FW_BANK_FW2 = 2 , TR01_FW_BANK_SPECT1 = 17 , TR01_FW_BANK_SPECT2 = 18 }
	BANK ID.
enum	lt_pkey_index_t { TR01_PAIRING_KEY_SLOT_INDEX_0 , TR01_PAIRING_KEY_SLOT_INDEX_1 , TR01_PAIRING_KEY_SLOT_INDEX_2 , TR01_PAIRING_KEY_SLOT_INDEX_3 }
	Pairing key indexes corresponds to S_HiPub.
enum	lt_config_obj_addr_t {   TR01_CFG_START_UP_ADDR = BOOTLOADER_CO_CFG_START_UP_ADDR , TR01_CFG_SENSORS_ADDR = BOOTLOADER_CO_CFG_SENSORS_ADDR , TR01_CFG_DEBUG_ADDR = BOOTLOADER_CO_CFG_DEBUG_ADDR , TR01_CFG_GPO_ADDR = APPLICATION_CO_CFG_GPO_ADDR ,   TR01_CFG_SLEEP_MODE_ADDR = APPLICATION_CO_CFG_SLEEP_MODE_ADDR , TR01_CFG_UAP_PAIRING_KEY_WRITE_ADDR = APPLICATION_CO_CFG_UAP_PAIRING_KEY_WRITE_ADDR , TR01_CFG_UAP_PAIRING_KEY_READ_ADDR = APPLICATION_CO_CFG_UAP_PAIRING_KEY_READ_ADDR , TR01_CFG_UAP_PAIRING_KEY_INVALIDATE_ADDR = APPLICATION_CO_CFG_UAP_PAIRING_KEY_INVALIDATE_ADDR ,   TR01_CFG_UAP_R_CONFIG_WRITE_ERASE_ADDR = APPLICATION_CO_CFG_UAP_R_CONFIG_WRITE_ERASE_ADDR , TR01_CFG_UAP_R_CONFIG_READ_ADDR = APPLICATION_CO_CFG_UAP_R_CONFIG_READ_ADDR , TR01_CFG_UAP_I_CONFIG_WRITE_ADDR = APPLICATION_CO_CFG_UAP_I_CONFIG_WRITE_ADDR , TR01_CFG_UAP_I_CONFIG_READ_ADDR = APPLICATION_CO_CFG_UAP_I_CONFIG_READ_ADDR ,   TR01_CFG_UAP_PING_ADDR = APPLICATION_CO_CFG_UAP_PING_ADDR , TR01_CFG_UAP_R_MEM_DATA_WRITE_ADDR = APPLICATION_CO_CFG_UAP_R_MEM_DATA_WRITE_ADDR , TR01_CFG_UAP_R_MEM_DATA_READ_ADDR = APPLICATION_CO_CFG_UAP_R_MEM_DATA_READ_ADDR , TR01_CFG_UAP_R_MEM_DATA_ERASE_ADDR = APPLICATION_CO_CFG_UAP_R_MEM_DATA_ERASE_ADDR ,   TR01_CFG_UAP_RANDOM_VALUE_GET_ADDR = APPLICATION_CO_CFG_UAP_RANDOM_VALUE_GET_ADDR , TR01_CFG_UAP_ECC_KEY_GENERATE_ADDR = APPLICATION_CO_CFG_UAP_ECC_KEY_GENERATE_ADDR , TR01_CFG_UAP_ECC_KEY_STORE_ADDR = APPLICATION_CO_CFG_UAP_ECC_KEY_STORE_ADDR , TR01_CFG_UAP_ECC_KEY_READ_ADDR = APPLICATION_CO_CFG_UAP_ECC_KEY_READ_ADDR ,   TR01_CFG_UAP_ECC_KEY_ERASE_ADDR = APPLICATION_CO_CFG_UAP_ECC_KEY_ERASE_ADDR , TR01_CFG_UAP_ECDSA_SIGN_ADDR = APPLICATION_CO_CFG_UAP_ECDSA_SIGN_ADDR , TR01_CFG_UAP_EDDSA_SIGN_ADDR = APPLICATION_CO_CFG_UAP_EDDSA_SIGN_ADDR , TR01_CFG_UAP_MCOUNTER_INIT_ADDR = APPLICATION_CO_CFG_UAP_MCOUNTER_INIT_ADDR ,   TR01_CFG_UAP_MCOUNTER_GET_ADDR = APPLICATION_CO_CFG_UAP_MCOUNTER_GET_ADDR , TR01_CFG_UAP_MCOUNTER_UPDATE_ADDR = APPLICATION_CO_CFG_UAP_MCOUNTER_UPDATE_ADDR , TR01_CFG_UAP_MAC_AND_DESTROY_ADDR = APPLICATION_CO_CFG_UAP_MAC_AND_DESTROY_ADDR }
	CONFIGURATION_OBJECTS_REGISTERS memory map.
enum	lt_config_obj_idx_t {   TR01_CFG_START_UP_IDX = 0 , TR01_CFG_SENSORS_IDX , TR01_CFG_DEBUG_IDX , TR01_CFG_GPO_IDX ,   TR01_CFG_SLEEP_MODE_IDX , TR01_CFG_UAP_PAIRING_KEY_WRITE_IDX , TR01_CFG_UAP_PAIRING_KEY_READ_IDX , TR01_CFG_UAP_PAIRING_KEY_INVALIDATE_IDX ,   TR01_CFG_UAP_R_CONFIG_WRITE_ERASE_IDX , TR01_CFG_UAP_R_CONFIG_READ_IDX , TR01_CFG_UAP_I_CONFIG_WRITE_IDX , TR01_CFG_UAP_I_CONFIG_READ_IDX ,   TR01_CFG_UAP_PING_IDX , TR01_CFG_UAP_R_MEM_DATA_WRITE_IDX , TR01_CFG_UAP_R_MEM_DATA_READ_IDX , TR01_CFG_UAP_R_MEM_DATA_ERASE_IDX ,   TR01_CFG_UAP_RANDOM_VALUE_GET_IDX , TR01_CFG_UAP_ECC_KEY_GENERATE_IDX , TR01_CFG_UAP_ECC_KEY_STORE_IDX , TR01_CFG_UAP_ECC_KEY_READ_IDX ,   TR01_CFG_UAP_ECC_KEY_ERASE_IDX , TR01_CFG_UAP_ECDSA_SIGN_IDX , TR01_CFG_UAP_EDDSA_SIGN_IDX , TR01_CFG_UAP_MCOUNTER_INIT_IDX ,   TR01_CFG_UAP_MCOUNTER_GET_IDX , TR01_CFG_UAP_MCOUNTER_UPDATE_IDX , TR01_CFG_UAP_MAC_AND_DESTROY_IDX }
	CONFIGURATION_OBJECTS_REGISTERS index map to lt_config_t. More...
enum	lt_ecc_slot_t {   TR01_ECC_SLOT_0 = 0 , TR01_ECC_SLOT_1 , TR01_ECC_SLOT_2 , TR01_ECC_SLOT_3 ,   TR01_ECC_SLOT_4 , TR01_ECC_SLOT_5 , TR01_ECC_SLOT_6 , TR01_ECC_SLOT_7 ,   TR01_ECC_SLOT_8 , TR01_ECC_SLOT_9 , TR01_ECC_SLOT_10 , TR01_ECC_SLOT_11 ,   TR01_ECC_SLOT_12 , TR01_ECC_SLOT_13 , TR01_ECC_SLOT_14 , TR01_ECC_SLOT_15 ,   TR01_ECC_SLOT_16 , TR01_ECC_SLOT_17 , TR01_ECC_SLOT_18 , TR01_ECC_SLOT_19 ,   TR01_ECC_SLOT_20 , TR01_ECC_SLOT_21 , TR01_ECC_SLOT_22 , TR01_ECC_SLOT_23 ,   TR01_ECC_SLOT_24 , TR01_ECC_SLOT_25 , TR01_ECC_SLOT_26 , TR01_ECC_SLOT_27 ,   TR01_ECC_SLOT_28 , TR01_ECC_SLOT_29 , TR01_ECC_SLOT_30 , TR01_ECC_SLOT_31 }
	ECC key slot indexes.
enum	lt_ecc_curve_type_t { TR01_CURVE_P256 = 1 , TR01_CURVE_ED25519 }
	ECC key type.
enum	lt_ecc_key_origin_t { TR01_CURVE_GENERATED = 1 , TR01_CURVE_STORED }
	ECC key origin.
enum	lt_mcounter_index_t {   TR01_MCOUNTER_INDEX_0 = 0 , TR01_MCOUNTER_INDEX_1 = 1 , TR01_MCOUNTER_INDEX_2 = 2 , TR01_MCOUNTER_INDEX_3 = 3 ,   TR01_MCOUNTER_INDEX_4 = 4 , TR01_MCOUNTER_INDEX_5 = 5 , TR01_MCOUNTER_INDEX_6 = 6 , TR01_MCOUNTER_INDEX_7 = 7 ,   TR01_MCOUNTER_INDEX_8 = 8 , TR01_MCOUNTER_INDEX_9 = 9 , TR01_MCOUNTER_INDEX_10 = 10 , TR01_MCOUNTER_INDEX_11 = 11 ,   TR01_MCOUNTER_INDEX_12 = 12 , TR01_MCOUNTER_INDEX_13 = 13 , TR01_MCOUNTER_INDEX_14 = 14 , TR01_MCOUNTER_INDEX_15 = 15 }
	Use to choose one from 16 counters.
enum	lt_mac_and_destroy_slot_t {   TR01_MAC_AND_DESTROY_SLOT_0 = 0 , TR01_MAC_AND_DESTROY_SLOT_1 , TR01_MAC_AND_DESTROY_SLOT_2 , TR01_MAC_AND_DESTROY_SLOT_3 ,   TR01_MAC_AND_DESTROY_SLOT_4 , TR01_MAC_AND_DESTROY_SLOT_5 , TR01_MAC_AND_DESTROY_SLOT_6 , TR01_MAC_AND_DESTROY_SLOT_7 ,   TR01_MAC_AND_DESTROY_SLOT_8 , TR01_MAC_AND_DESTROY_SLOT_9 , TR01_MAC_AND_DESTROY_SLOT_10 , TR01_MAC_AND_DESTROY_SLOT_11 ,   TR01_MAC_AND_DESTROY_SLOT_12 , TR01_MAC_AND_DESTROY_SLOT_13 , TR01_MAC_AND_DESTROY_SLOT_14 , TR01_MAC_AND_DESTROY_SLOT_15 ,   TR01_MAC_AND_DESTROY_SLOT_16 , TR01_MAC_AND_DESTROY_SLOT_17 , TR01_MAC_AND_DESTROY_SLOT_18 , TR01_MAC_AND_DESTROY_SLOT_19 ,   TR01_MAC_AND_DESTROY_SLOT_20 , TR01_MAC_AND_DESTROY_SLOT_21 , TR01_MAC_AND_DESTROY_SLOT_22 , TR01_MAC_AND_DESTROY_SLOT_23 ,   TR01_MAC_AND_DESTROY_SLOT_24 , TR01_MAC_AND_DESTROY_SLOT_25 , TR01_MAC_AND_DESTROY_SLOT_26 , TR01_MAC_AND_DESTROY_SLOT_27 ,   TR01_MAC_AND_DESTROY_SLOT_28 , TR01_MAC_AND_DESTROY_SLOT_29 , TR01_MAC_AND_DESTROY_SLOT_30 , TR01_MAC_AND_DESTROY_SLOT_31 ,   TR01_MAC_AND_DESTROY_SLOT_32 , TR01_MAC_AND_DESTROY_SLOT_33 , TR01_MAC_AND_DESTROY_SLOT_34 , TR01_MAC_AND_DESTROY_SLOT_35 ,   TR01_MAC_AND_DESTROY_SLOT_36 , TR01_MAC_AND_DESTROY_SLOT_37 , TR01_MAC_AND_DESTROY_SLOT_38 , TR01_MAC_AND_DESTROY_SLOT_39 ,   TR01_MAC_AND_DESTROY_SLOT_40 , TR01_MAC_AND_DESTROY_SLOT_41 , TR01_MAC_AND_DESTROY_SLOT_42 , TR01_MAC_AND_DESTROY_SLOT_43 ,   TR01_MAC_AND_DESTROY_SLOT_44 , TR01_MAC_AND_DESTROY_SLOT_45 , TR01_MAC_AND_DESTROY_SLOT_46 , TR01_MAC_AND_DESTROY_SLOT_47 ,   TR01_MAC_AND_DESTROY_SLOT_48 , TR01_MAC_AND_DESTROY_SLOT_49 , TR01_MAC_AND_DESTROY_SLOT_50 , TR01_MAC_AND_DESTROY_SLOT_51 ,   TR01_MAC_AND_DESTROY_SLOT_52 , TR01_MAC_AND_DESTROY_SLOT_53 , TR01_MAC_AND_DESTROY_SLOT_54 , TR01_MAC_AND_DESTROY_SLOT_55 ,   TR01_MAC_AND_DESTROY_SLOT_56 , TR01_MAC_AND_DESTROY_SLOT_57 , TR01_MAC_AND_DESTROY_SLOT_58 , TR01_MAC_AND_DESTROY_SLOT_59 ,   TR01_MAC_AND_DESTROY_SLOT_60 , TR01_MAC_AND_DESTROY_SLOT_61 , TR01_MAC_AND_DESTROY_SLOT_62 , TR01_MAC_AND_DESTROY_SLOT_63 ,   TR01_MAC_AND_DESTROY_SLOT_64 , TR01_MAC_AND_DESTROY_SLOT_65 , TR01_MAC_AND_DESTROY_SLOT_66 , TR01_MAC_AND_DESTROY_SLOT_67 ,   TR01_MAC_AND_DESTROY_SLOT_68 , TR01_MAC_AND_DESTROY_SLOT_69 , TR01_MAC_AND_DESTROY_SLOT_70 , TR01_MAC_AND_DESTROY_SLOT_71 ,   TR01_MAC_AND_DESTROY_SLOT_72 , TR01_MAC_AND_DESTROY_SLOT_73 , TR01_MAC_AND_DESTROY_SLOT_74 , TR01_MAC_AND_DESTROY_SLOT_75 ,   TR01_MAC_AND_DESTROY_SLOT_76 , TR01_MAC_AND_DESTROY_SLOT_77 , TR01_MAC_AND_DESTROY_SLOT_78 , TR01_MAC_AND_DESTROY_SLOT_79 ,   TR01_MAC_AND_DESTROY_SLOT_80 , TR01_MAC_AND_DESTROY_SLOT_81 , TR01_MAC_AND_DESTROY_SLOT_82 , TR01_MAC_AND_DESTROY_SLOT_83 ,   TR01_MAC_AND_DESTROY_SLOT_84 , TR01_MAC_AND_DESTROY_SLOT_85 , TR01_MAC_AND_DESTROY_SLOT_86 , TR01_MAC_AND_DESTROY_SLOT_87 ,   TR01_MAC_AND_DESTROY_SLOT_88 , TR01_MAC_AND_DESTROY_SLOT_89 , TR01_MAC_AND_DESTROY_SLOT_90 , TR01_MAC_AND_DESTROY_SLOT_91 ,   TR01_MAC_AND_DESTROY_SLOT_92 , TR01_MAC_AND_DESTROY_SLOT_93 , TR01_MAC_AND_DESTROY_SLOT_94 , TR01_MAC_AND_DESTROY_SLOT_95 ,   TR01_MAC_AND_DESTROY_SLOT_96 , TR01_MAC_AND_DESTROY_SLOT_97 , TR01_MAC_AND_DESTROY_SLOT_98 , TR01_MAC_AND_DESTROY_SLOT_99 ,   TR01_MAC_AND_DESTROY_SLOT_100 , TR01_MAC_AND_DESTROY_SLOT_101 , TR01_MAC_AND_DESTROY_SLOT_102 , TR01_MAC_AND_DESTROY_SLOT_103 ,   TR01_MAC_AND_DESTROY_SLOT_104 , TR01_MAC_AND_DESTROY_SLOT_105 , TR01_MAC_AND_DESTROY_SLOT_106 , TR01_MAC_AND_DESTROY_SLOT_107 ,   TR01_MAC_AND_DESTROY_SLOT_108 , TR01_MAC_AND_DESTROY_SLOT_109 , TR01_MAC_AND_DESTROY_SLOT_110 , TR01_MAC_AND_DESTROY_SLOT_111 ,   TR01_MAC_AND_DESTROY_SLOT_112 , TR01_MAC_AND_DESTROY_SLOT_113 , TR01_MAC_AND_DESTROY_SLOT_114 , TR01_MAC_AND_DESTROY_SLOT_115 ,   TR01_MAC_AND_DESTROY_SLOT_116 , TR01_MAC_AND_DESTROY_SLOT_117 , TR01_MAC_AND_DESTROY_SLOT_118 , TR01_MAC_AND_DESTROY_SLOT_119 ,   TR01_MAC_AND_DESTROY_SLOT_120 , TR01_MAC_AND_DESTROY_SLOT_121 , TR01_MAC_AND_DESTROY_SLOT_122 , TR01_MAC_AND_DESTROY_SLOT_123 ,   TR01_MAC_AND_DESTROY_SLOT_124 , TR01_MAC_AND_DESTROY_SLOT_125 , TR01_MAC_AND_DESTROY_SLOT_126 , TR01_MAC_AND_DESTROY_SLOT_127 }
	Mac-and-Destroy slot indexes.

Variables
const uint8_t	sh0priv_eng_sample []
	Host MCU's X25519 private key to execute a Secure Channel Handshake on Pairing Key slot 0 of the engineering (pre-production) TROPIC01 samples.
const uint8_t	sh0pub_eng_sample []
	Host MCU's X25519 public key (stored in TROPIC01) to execute a Secure Channel Handshake on Pairing Key slot 0 of the engineering (pre-production) TROPIC01 samples.
const uint8_t	sh0priv_prod0 []
	Host MCU's X25519 private key to execute a Secure Channel Handshake on Pairing Key slot 0 of the production TROPIC01 chips.
const uint8_t	sh0pub_prod0 []
	Host MCU's X25519 public key (stored in TROPIC01) to execute a Secure Channel Handshake on Pairing Key slot 0 of the production TROPIC01 chips.

Detailed Description

Copyright

Copyright (c) 2020-2025 Tropic Square s.r.o.

License

For the license see file LICENSE.txt file in the root directory of this source tree.

---

Data Structure Documentation

lt_l3_gen_frame_t

struct lt_l3_gen_frame_t

Data Fields
uint16_t	cmd_size	RES_SIZE or CMD_SIZE value.
uint8_t	data[TR01_L3_CIPHERTEXT_MAX_SIZE+TR01_L3_TAG_SIZE]	Command or result ciphertext + tag.

lt_l2_state_t

struct lt_l2_state_t

Data Fields
void *	device
uint8_t	buff[TR01_L1_CHIP_STATUS_SIZE+TR01_L2_MAX_FRAME_SIZE]
bool	startup_req_sent

lt_l3_state_t

struct lt_l3_state_t

Data Fields
enum lt_secure_session_status_t	session_status
uint8_t	encryption_IV[TR01_L3_IV_SIZE]
uint8_t	decryption_IV[TR01_L3_IV_SIZE]
void *	crypto_ctx
uint8_t	buff[LT_SIZE_OF_L3_BUFF]	Buffer for L3 commands and results
uint16_t	buff_len	Length of the buffer

lt_handle_t

struct lt_handle_t

This structure holds data related to one physical chip. Contains AESGCM contexts for encrypting and decrypting L3 commands, nonce and device void pointer, which can be used for passing arbitrary data.

Data Fields
lt_l2_state_t	l2
lt_l3_state_t	l3
lt_tr01_attrs_t	tr01_attrs

lt_cert_store_t

struct lt_cert_store_t

Data Fields
uint8_t *	certs[LT_NUM_CERTIFICATES]
uint16_t	buf_len[LT_NUM_CERTIFICATES]	Certificates
uint16_t	cert_len[LT_NUM_CERTIFICATES]	Length of buffers for certificates

lt_ser_num_t

struct lt_ser_num_t

This structure contains fields for parsing the chip's serial number data.

Data Fields
uint8_t	sn	8 bits for serial number
uint8_t	fab_data[3]	12 bits fab ID, 12 bits part number ID
uint16_t	fab_date	16 bits for fabrication date
uint8_t	lot_id[5]	40 bits for lot ID
uint8_t	wafer_id	8 bits for wafer ID
uint16_t	x_coord	16 bits for x-coordinate
uint16_t	y_coord	16 bits for y-coordinate

lt_chip_id_t

struct lt_chip_id_t

Data Fields
uint8_t	chip_id_ver[4]	CHIP_ID structure versioning (32 bits), defined by Tropic Square in BP. Example encoding: v1.2.3.4 = 0x01,0x02,0x03,0x04
uint8_t	fl_chip_info[16]	Factory level test info (128 bits), structure retrieved from silicon provider. The exact copy of FL_PROD_DATA structure. If missing, it is filled with 0x00.
uint8_t	func_test_info[8]	Manufacturing level test info (128 bits), structure retrieved from test line and BP. The exact copy of first two words of MAN_FUNC_TEST structure. In case of missing, it is filled with 0x00
uint8_t	silicon_rev[4]	Silicon revision (32 bits). ASCII encoded string value defined by Tropic Square. Example: ’ACAB’ = 0x41434142
uint8_t	packg_type_id[2]	Package Type ID defined by Tropic Square.
uint8_t	rfu_1[2]	Reserved field 1 (16 bits).
uint8_t	prov_ver_fab_id_pn[4]	Provisioning info (128 bits), filled by the provisioning station. 8 bits: Provisioning info version. 12 bits: Fabrication ID. 12 bits: Part Number ID.
uint8_t	provisioning_date[2]	Provisioning date (16 bits).
uint8_t	hsm_ver[4]	HSM version (32 bits). Byte 0: RFU, Byte 1: Major version, Byte 2: Minor version, Byte 3: Patch version
uint8_t	prog_ver[4]	Program version (32 bits).
uint8_t	rfu_2[2]	Reserved field 2 (16 bits).
struct lt_ser_num_t	ser_num	Serial Number (128 bits).
uint8_t	part_num_data[16]	Part Number (128 bits), defined by Tropic Square in BP. Part number data.
uint8_t	prov_templ_ver[2]	Provisioning Data version (160 bits), defined by Tropic Square for each batch in BP. Provisioning template version.
uint8_t	prov_templ_tag[4]	Provisioning template tag.
uint8_t	prov_spec_ver[2]	Provisioning specification version.
uint8_t	prov_spec_tag[4]	Provisioning specification tag.
uint8_t	batch_id[5]	Batch ID (40 bits).
uint8_t	rfu_3[3]	Reserved field 3 (24 bits).
uint8_t	rfu_4[24]	Padding (192 bits).

lt_header_boot_v1_t

struct lt_header_boot_v1_t

Data Fields
uint8_t	type[4]
uint8_t	version[4]
uint8_t	size[4]
uint8_t	git_hash[4]
uint8_t	hash[4]

lt_header_boot_v2_t

struct lt_header_boot_v2_t

Data Fields
uint16_t	type	Currently only two types supported: 1 == FW for RISCV coprocessor. 2 == FW for SPECT coprocessor.
uint8_t	padding
uint8_t	header_version	This header version.
uint32_t	ver	FW version, the same number as TS_L2_GET_INFO_REQ_OBJECT_ID_RISCV_FW_VERSION or TS_L2_GET_INFO_REQ_OBJECT_ID_SPECT_ROM_ID.
uint32_t	size	FW size in bytes (always aligned to uint32_t).
uint32_t	git_hash	GIT hash of the underlying FW repository.
uint8_t	hash[32]	Hash for data integrity (SHA256, 32B).
uint32_t	pair_version	Other FW version compatibility. In case RISCV FW there may be SPECT version to match. Zero means any version.

lt_host_eph_keys_t

struct lt_host_eph_keys_t

Data Fields
uint8_t	ehpriv[32]	Host MCU ephemeral private key.
uint8_t	ehpub[32]	Host MCU ephemeral public key.

lt_config_obj_desc_t

struct lt_config_obj_desc_t

Data Fields
char	desc[60]
enum lt_config_obj_addr_t	addr

lt_config_t

struct lt_config_t

Data Fields
uint32_t	obj[LT_CONFIG_OBJ_CNT]