PyTropicSquare Documentation

PyTropicSquare

Python library for communicating with the Tropic Square TROPIC01 secure element chip.

Overview

PyTropicSquare provides a comprehensive Python interface for the TROPIC01 secure element, supporting both CPython and MicroPython environments. The library implements the complete communication protocol stack for secure operations including cryptographic functions, key management, and secure data storage.

Features

• Dual Platform Support: Works with both CPython (using the cryptography library) and MicroPython (with embedded crypto implementations)

• Secure Communication: X25519 key exchange with HKDF key derivation and AES-GCM encryption

• Cryptographic Operations:

  • ECDSA signing (P256 curve)

  • EdDSA signing (Ed25519 curve)

  • ECC key generation and management

• Secure Storage: Memory slots for data storage (up to 444 bytes per slot)

• Chip Identification: Parsed chip ID with manufacturing details (package type, fab location, serial number, wafer coordinates)

• Configuration Management:

  • R-CONFIG (Reversible) and I-CONFIG (Irreversible) register support

  • User Access Policy (UAP) permissions for cryptographic operations

  • Startup, sensors, debug, GPO, and sleep mode configuration

• Additional Features:

  • True random number generation

  • Monotonic counters

  • MAC and destroy operations

  • Certificate and public key extraction

Installation

From PyPI (when available)

pip install pytropicsquare

From Source

git clone https://github.com/petrkr/pytropicsquare.git
cd pytropicsquare
pip install -r requirements.txt
pip install -e .

Quick Start

Example

from tropicsquare import TropicSquare
from tropicsquare.constants.ecc import ECC_CURVE_ED25519
from tropicsquare.constants.pairing_keys import (
    FACTORY_PAIRING_KEY_INDEX,
    FACTORY_PAIRING_PRIVATE_KEY_PROD0,
    FACTORY_PAIRING_PUBLIC_KEY_PROD0,
)

# Initialize with your SPI interface and CS pin

# Micropython machine.SPI
from machine import SPI, Pin
from tropicsquare.transports.spi import SpiTransport

spi = SPI(...)
cs = Pin(...)
transport = SpiTransport(spi, cs)

# Linux UART SPI devkit
# from tropicsquare.transports.uart import UartTransport
# transport = UartTransport("/dev/ttyACM0")

# Remote SPI over Network
# from tropicsquare.transports.network import NetworkSpiTransport
# transport = NetworkSpiTransport("127.0.0.1", 12345)

ts = TropicSquare(transport)

# Get chip information
chip_id = ts.chip_id
print(chip_id)  # Human-readable output
print(f"Package: {chip_id.package_type_name}")
print(f"Fabrication: {chip_id.fab_name}")
print(f"SPECT FW: {ts.spect_fw_version}")
print(f"RISC-V FW: {ts.riscv_fw_version}")

# Start secure session (requires pairing keys)
ts.start_secure_session(
    FACTORY_PAIRING_KEY_INDEX,
    FACTORY_PAIRING_PRIVATE_KEY_PROD0,
    FACTORY_PAIRING_PUBLIC_KEY_PROD0,
)

# Perform operations
random_data = ts.random(32)
ping_response = ts.ping(b"Hello TROPIC01!")

# Generate and use ECC keys
ts.ecc_key_generate(slot=0, curve=ECC_CURVE_ED25519)
signature = ts.eddsa_sign(slot=0, message=b"Sign this message")

Chip Information

The library provides detailed chip identification and manufacturing data through parsed structures:

# Get parsed chip ID
chip_id = ts.chip_id

# Access chip information
print(chip_id)  # Multi-line human-readable output

# Individual fields
print(f"Package Type: {chip_id.package_type_name}")      # "QFN32", "Bare Silicon"
print(f"Silicon Revision: {chip_id.silicon_rev}")        # e.g., "ACAB"
print(f"Fabrication Facility: {chip_id.fab_name}")       # "EPS Brno", "Tropic Square Lab"
print(f"Part Number ID: 0x{chip_id.part_number_id:03X}")
print(f"HSM Version: {'.'.join(map(str, chip_id.hsm_version))}")
print(f"Batch ID: {chip_id.batch_id.hex()}")

# Serial number details
sn = chip_id.serial_number
print(f"Serial Number: 0x{sn.sn:02X}")
print(f"Fab ID: 0x{sn.fab_id:03X}")
print(f"Wafer ID: 0x{sn.wafer_id:02X}")
print(f"Wafer Coordinates: ({sn.x_coord}, {sn.y_coord})")
print(f"Lot ID: {sn.lot_id.hex()}")

# Export to dictionary (useful for JSON serialization)
chip_dict = chip_id.to_dict()

# Access raw bytes if needed
raw_chip_id = chip_id.raw  # 128 bytes

Configuration Management

TROPIC01 uses two configuration memory spaces:

• R-CONFIG (Reversible): Can be written and erased freely

• I-CONFIG (Irreversible): Bits can only change from 1→0 permanently

The effective configuration is the AND of R-CONFIG and I-CONFIG values.

Configuration Types

Basic Configuration:

• StartUpConfig: Chip startup settings (MBIST, TRNG, clock, reset behavior)

• SensorsConfig: Security sensor disable flags (18 sensors)

• DebugConfig: Firmware logging control

• GpoConfig: General Purpose Output function (0-7)

• SleepModeConfig: Sleep mode behavior

User Access Policy (UAP) Permissions: Control which pairing keys can access cryptographic operations:

• ECC operations: key generation, storage, signing (ECDSA/EdDSA)

• Memory operations: read, write, erase

• Pairing key management

• R-CONFIG/I-CONFIG access

• Monotonic counters

• Utility operations (ping, random, MAC)

Example

from tropicsquare.constants.config import CFG_START_UP
from tropicsquare.config.startup import StartUpConfig

# Read R-CONFIG startup register (returns parsed config object)
config = ts.r_config_read(CFG_START_UP)

print(f"MBIST disabled: {config.mbist_dis}")
print(f"TRNG disabled: {config.trng_dis}")

# Modify and write back
config.mbist_dis = True
ts.r_config_write(CFG_START_UP, config)

# Read I-CONFIG and compute effective value
r_config = ts.r_config_read(CFG_START_UP)
i_config = ts.i_config_read(CFG_START_UP)
effective = StartUpConfig(r_config._value & i_config._value)

Architecture

The library is structured in three protocol layers:

• L1 (Transport): SPI communication layer

• L2 (Protocol): Chip communication with CRC validation and session management

• L3 (Commands): High-level cryptographic and utility functions

API Reference

Core Classes

• TropicSquare: Base class with protocol implementation

• TropicSquareCPython: CPython implementation

• TropicSquareMicroPython: MicroPython implementation

Chip Information Classes

• ChipId: Parsed chip identification structure (128 bytes)

  • Properties: package_type_name, fab_name, silicon_rev, serial_number, hsm_version, prog_version, batch_id, and more

  • Methods: to_dict() for JSON export, __str__() for human-readable output

• SerialNumber: Chip serial number with manufacturing details (16 bytes)

  • Properties: sn, fab_id, part_number_id, wafer_id, x_coord, y_coord, lot_id

  • Methods: to_dict() for JSON export

Key Methods

Session Management

• start_secure_session(key_index, private_key, public_key): Establish encrypted session

• abort_secure_session(): Terminate current session

Cryptographic Operations

• random(nbytes): Generate true random bytes

• ecc_key_generate(slot, curve): Generate ECC keypair

• ecdsa_sign(slot, hash): Sign hash with P256 key

• eddsa_sign(slot, message): Sign message with Ed25519 key

Data Storage

• mem_data_write(data, slot): Write data to memory slot

• mem_data_read(slot): Read data from memory slot

• mem_data_erase(slot): Erase memory slot

Utility Functions

• ping(data): Echo test

• get_log(): Retrieve chip logs

• mcounter_init/update/get(): Monotonic counter operations

Configuration Access

• r_config_read(register): Read and parse R-CONFIG register (returns Config object)

• r_config_write(register, data): Write R-CONFIG register

• i_config_read(register): Read and parse I-CONFIG register (returns Config object)

• i_config_write(register, bit_index): Clear one I-CONFIG bit (only 1 -> 0 transitions)

• parse_config(register, data): Parse raw bytes into config object (used internally)

Examples

See the examples/ directory for complete usage examples:

• esp32_quickstart.py: MicroPython example for ESP32

• rpi_spidev_quickstart.py: Linux/Raspberry Pi example using SpiDevTransport

• tcp_model_quickstart.py: Quickstart for TCP model/simulator transport

Requirements

• Python 3.11+

• cryptography library (CPython only)

Documentation

Full API documentation is available at: GitHub Pages

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Petr Kracik (petrkr@petrkr.net)

Contents

Documentation:

• Installation
  • CPython
  • MicroPython / ESP32
• API Reference
  • Overview
  • Quick Reference
  • Detailed Documentation
• Testing
  • Test Reports
  • Running Tests Locally
  • Continuous Integration
  • Test Organization
  • Writing Tests
  • Coverage Guidelines
  • Troubleshooting
  • Contributing
• Test Results
• Code Coverage

Examples

• Examples
  • PyTropicSquare Examples

Indices and tables

• Index

• Module Index

• Search Page