TropicSquare Core Class

The TropicSquare class is the main interface for communicating with the TROPIC01 secure element chip. It implements the L2 and L3 protocol layers and provides high-level methods for all chip operations. It serves as the common base class for the platform-specific implementations.

class tropicsquare.TropicSquare(*args, **kwargs)

Bases: object

static __new__(cls, *args, **kwargs)

Factory method that returns platform-specific implementation.

When instantiating TropicSquare directly, automatically returns either TropicSquareCPython or TropicSquareMicroPython based on the detected platform.

This allows users to write platform-agnostic code:

from tropicsquare import TropicSquare ts = TropicSquare(transport)

__init__(transport)

Initialize TropicSquare base class.

Parameters:

transport (L1Transport) – L1Transport instance

Return type:

None

property certificate: bytes

Get X509 certificate from the chip

Returns:

X509 certificate

Return type:

bytes

property public_key: bytes

Get public key from the X509 certificate

In case certificate is not loaded before, it will load also certificate

returns:

Public key

rtype:

bytes

property chip_id: ChipId

Get parsed chip ID structure

Returns:

Parsed chip ID object with all fields

Return type:

ChipId

property riscv_fw_version: tuple

Get RISCV firmware version

Returns:

Firmware version (major, minor, patch, release)

Return type:

tuple

property spect_fw_version: tuple

Get SPECT firmware version

Returns:

Firmware version (major, minor, patch, release)

Return type:

tuple

property fw_bank: bytes

Get firmware bank information.

Returns:

Firmware bank data

Return type:

bytes

start_secure_session(pkey_index, shpriv, shpub)

Initialize secure session for L3 commands

Parameters:

• phkey_index – Pairing key index

• shpriv (bytes) – Pairing private key

• shpub (bytes) – Pairing public key

• pkey_index (int)

Returns:

True if secure session was established

Return type:

bool

Raises:

TropicSquareError – If secure session handshake failed

abort_secure_session()

Abort secure session

Returns:

True if secure session was aborted

Return type:

bool

reboot(mode)

Startup/reboot chip

Parameters:

mode (int) – Startup mode (STARTUP_REBOOT or STARTUP_MAINTENANCE_REBOOT)

Returns:

True if startup request was sent

Return type:

bool

Raises:

• ValueError – If invalid startup mode

• TropicSquareError – If startup request failed

sleep(mode)

Put chip to sleep

Parameters:

mode (int) – Sleep mode (SLEEP_MODE_SLEEP or SLEEP_MODE_DEEP_SLEEP)

Returns:

True if sleep request was sent

Return type:

bool

Raises:

• ValueError – If invalid sleep mode

• TropicSquareError – If sleep request failed

get_log()

Get log from the RISC Firmware

Returns:

Log message

Return type:

str

ping(data)

Returns data back

Parameters:

data (bytes) – Data to send

Returns:

Data from input

Return type:

bytes

random(nbytes)

Get random bytes

Parameters:

nbytes (int) – Number of bytes to generate

Returns:

Random bytes

Return type:

bytes

r_config_read(address)

Read and parse R-CONFIG register.

Parameters:

address (int) – Register address (use CFG_* constants from tropicsquare.constants.config)

Returns:

Parsed config object (StartUpConfig, SensorsConfig, etc.)

Return type:

BaseConfig

Example:

from tropicsquare.constants.config import CFG_START_UP

config = ts.r_config_read(CFG_START_UP)
print(config.mbist_dis)

i_config_read(address)

Read and parse I-CONFIG register.

Parameters:

address (int) – Register address (use CFG_* constants from tropicsquare.constants.config)

Returns:

Parsed config object (StartUpConfig, SensorsConfig, etc.)

Return type:

BaseConfig

Example:

from tropicsquare.constants.config import CFG_START_UP

config = ts.i_config_read(CFG_START_UP)
print(config.mbist_dis)

r_config_write(address, value)

Write single R-CONFIG register.

Parameters:

• address (int) – Register address (use CFG_* constants from tropicsquare.constants.config)

• value – 32-bit register value or BaseConfig object

Returns:

True if write succeeded

Return type:

bool

i_config_write(address, bit_index)

Clear a single I-CONFIG bit (1->0 transition only).

Parameters:

• address (int) – Register address (use CFG_* constants from tropicsquare.constants.config)

• bit_index (int) – Bit index to clear (0-31)

Returns:

True if write succeeded

Return type:

bool

r_config_erase()

Erase whole R-CONFIG (sets all bits of all COs to 1).

Returns:

True if erase succeeded

Return type:

bool

mem_data_read(slot)

Read data from memory slot

Parameters:

slot (int) – Memory slot

Returns:

Data from memory slot

Return type:

bytes

mem_data_write(data, slot)

Write data to memory slot

Parameters:

• data (bytes) – Data to write (Maximum 444 bytes)

• slot (int) – Memory slot

Returns:

True if data was written

Return type:

bool

Raises:

ValueError – If data size is larger than 444

mem_data_erase(slot)

Erase memory slot

Parameters:

slot (int) – Memory slot

Returns:

True if data was erased

Return type:

bool

ecc_key_generate(slot, curve)

Generate ECC key

Parameters:

• slot (int) – Slot for key

• curve (int) – Curve (ECC_CURVE_P256 or ECC_CURVE_ED25519)

Returns:

True if key was generated

Return type:

bool

Raises:

ValueError – If slot is larger than ECC_MAX_KEYS or curve is invalid

ecc_key_store(slot, curve, key)

Store own ECC key

Parameters:

• slot (int) – Slot for key

• curve (int) – Curve (ECC_CURVE_P256 or ECC_CURVE_ED25519)

• key (bytes) – Private key

Returns:

True if key was stored

Return type:

bool

Raises:

ValueError – If slot is larger than ECC_MAX_KEYS or curve is invalid

ecc_key_read(slot)

Read ECC key information from slot

Parameters:

slot (int) – Slot for key

Returns:

Key information with curve, origin, and public_key

Return type:

EccKeyInfo

Raises:

ValueError – If slot is larger than ECC_MAX_KEYS

Example:

key_info = ts.ecc_key_read(0)
if key_info.curve == ECC_CURVE_ED25519:
    print("Ed25519 key")
print(key_info.public_key.hex())

ecc_key_erase(slot)

Erase ECC key

Parameters:

slot (int) – Slot for key

Returns:

True if key was erased

Return type:

bool

Raises:

ValueError – If slot is larger than ECC_MAX_KEYS

ecdsa_sign(slot, hash)

Sign hash with ECDSA using P256 key

Parameters:

• slot (int) – Slot with P256 ECC key

• hash (bytes) – Hash to sign (32 bytes)

Returns:

ECDSA signature

Return type:

EcdsaSignature

Raises:

ValueError – If slot is larger than ECC_MAX_KEYS

Example:

import hashlib
message_hash = hashlib.sha256(b"Hello").digest()
signature = ts.ecdsa_sign(1, message_hash)
print(signature.r.hex())
print(signature.s.hex())

eddsa_sign(slot, message)

Sign message with EdDSA using Ed25519 key

Parameters:

• slot (int) – Slot with Ed25519 ECC key

• message (bytes) – Message to sign

Returns:

EdDSA signature

Return type:

EddsaSignature

Example:

signature = ts.eddsa_sign(0, message)
print(signature.r.hex())
print(signature.s.hex())

mcounter_init(index, value)

Initialize monotonic counter

Parameters:

• index (int) – Counter index

• value (int) – Initial value

Returns:

True if counter was initialized

Return type:

bool

mcounter_update(index)

Decrement monotonic counter

Parameters:

index (int) – Counter index

Returns:

True if counter was updated

Return type:

bool

mcounter_get(index)

Get monotonic counter value

Parameters:

index (int) – Counter index

Returns:

Counter value

Return type:

int

mac_and_destroy(slot, data)

MAC and destroy operation for atomic PIN verification.

This command executes atomic PIN verification using Keccak-based MAC. The operation reads a slot from the MAC-and-Destroy partition (128 slots, 0-127), performs MAC calculation, and destroys/erases the slot data.

The MAC-and-Destroy partition is separate from User Data partition and uses Keccak engines with PUF-based per-chip unique keys (K_FXA, K_FXB).

Parameters:

• slot (int) – Slot index in MAC-and-Destroy partition (0-127)

• data (bytes) – Data to MAC (must be exactly 32 bytes)

Returns:

MAC result (32 bytes)

Raises:

• ValueError – If slot exceeds maximum (127) or data length is not 32 bytes

• TropicSquareNoSession – If secure session is not established

Return type:

bytes

Note

Requires active secure session via start_secure_session().

See also

TROPIC01 User API v1.1.2, Table 37: MAC_And_Destroy command specification

Example:

# Start secure session first
ts.start_secure_session(
    FACTORY_PAIRING_KEY_INDEX,
    FACTORY_PAIRING_PRIVATE_KEY_PROD0,
    FACTORY_PAIRING_PUBLIC_KEY_PROD0
)

# Perform MAC and destroy on slot 0
pin_data = b'my_32_byte_pin_data_here_000'  # Exactly 32 bytes
mac_result = ts.mac_and_destroy(0, pin_data)
print(f"MAC: {mac_result.hex()}")  # Returns 32-byte MAC

pairing_key_read(slot)

Read pairing key information from slot.

Parameters:

slot (int) – Pairing key slot index (0-3)

Returns:

Pairing key information (32 bytes)

Return type:

bytes

Raises:

ValueError – If slot exceeds maximum (3)

pairing_key_write(slot, key)

Write pairing key information to slot.

Parameters:

• slot (int) – Pairing key slot index (0-3)

• key (bytes) – Pairing key data (32 bytes)

Returns:

True if write succeeded

Return type:

bool

Raises:

ValueError – If slot exceeds maximum (3) or key length is not 32 bytes

pairing_key_invalidate(slot)

Invalidate pairing key in slot.

Parameters:

slot (int) – Pairing key slot index (0-3)

Returns:

True if successful

Return type:

bool

Raises:

ValueError – If slot exceeds maximum (3)

Platform-Specific Implementations

For actual usage, you should use one of the platform-specific implementations:

• TropicSquareCPython - For CPython (development, desktop)

• TropicSquareMicroPython - For MicroPython (ESP32, embedded)

See Also

• L2 Protocol Layer - L2 protocol implementation details

• Platform Ports - Platform-specific implementations

• Transport Layer - Available transport layers