# 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)
```bash
pip install pytropicsquare
```

### From Source
```bash
git clone https://github.com/petrkr/pytropicsquare.git
cd pytropicsquare
pip install -r requirements.txt
pip install -e .
```

## Quick Start

### Example
```python
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:

```python
# 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

```python
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](https://petrkr.github.io/pytropicsquare/)

## 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)
