A software simulator for the Tropic Square TROPIC01 secure element, written
in Rust. It speaks libtropic's "TROPIC01 model" protocol over TCP (the
hal/posix/tcp HAL), emulates the chip's SPI side byte for byte, runs the
Noise_KK1_25519_AESGCM_SHA256 secure channel and implements the full
application firmware L3 command set. Host code built on libtropic (wolfSSL's
TROPIC01 port, the wolfHSM TROPIC01 port, applications) can be tested
without hardware.
The es-0.1.2 and es-2.2.0 personalities were validated against the same
real chip, before and after a firmware update: a conformance probe that runs
unchanged on the chip and on the simulator produces 267 (FW 0.1.2) and 357
(FW 2.2.0) identical behavioural observations. See
HARDWARE_VALIDATION.md for the bench, the probe,
the chip behaviours it recorded and what is not verified.
TROPIC01 behaviour depends on the part (silicon, bootloader, factory
provisioning) and on the firmware it runs. Select a combination with
TROPIC01_SIM_PERSONALITY:
| Personality | Part | Firmware | Validated |
|---|---|---|---|
es-0.1.2 (default) |
Engineering sample: bootloader 1.0.1, 20-byte bank headers, debug log enabled, libtropic's eng_sample key in pairing slot 0 |
Application FW 0.1.2, SPECT FW 0.3.1: 444-byte R-Memory slots, lenient L3 size checks | Against a real chip |
es-2.2.0 |
The same engineering sample after a firmware update and the RNGTEST_DIS erratum fix | Application FW 2.2.0, SPECT FW 1.3.0: 475-byte R-Memory slots, strict L3 sizes (L2 GEN_ERR and session close) |
Against the same chip after the update |
2.2.0 |
Production part: bootloader 2.0.1, 52-byte bank headers, empty log, libtropic's prod0 key in pairing slot 0 |
As es-2.2.0 |
Firmware through es-2.2.0; the part against Tropic Square's functional model (ts-tvl) and libtropic's model configuration |
- CHIP_STATUS on every transaction (READY, ALARM and START_UP bits), the
0xAAGET_RESPONSE poll and a configurable number of busy polls before a response is ready (READY cleared on FW 0.1.2 and in maintenance mode, READY with no response on FW 2.2.0). - Responses are served once and only RESEND repeats them; a replayed frame
goes in front of the frames not fetched yet. Encrypted L3 results longer
than one 252-byte L2 chunk are returned as
RESULT_CONTchunks, and L3 commands are reassembled fromREQUEST_CONTchunks. - All TCP connections talk to the same chip. A new connection is a new host on a chip that stays powered: its mode, ALARM state and secure session carry over.
- TCP
POWER_ON,POWER_OFFandRESET_TARGETpower cycle the chip: the session, queued responses and ALARM mode are lost, persistent state is kept.
GET_INFO: certificate store (30 blocks of 128 bytes), CHIP_ID, RISC-V and SPECT firmware versions, firmware bank headers (maintenance mode only).HANDSHAKE,ENCRYPTED_CMD,ENCRYPTED_SESSION_ABT,RESEND,SLEEP,GET_LOG,STARTUP(reboot into application or maintenance mode).- The chip's status codes for malformed, unknown and out of mode requests, bad CRCs and failed AES-GCM tags (which drop the session).
| ID | Command |
|---|---|
0x01 |
PING (up to 4096 bytes) |
0x10 - 0x12 |
PAIRING_KEY_WRITE / READ / INVALIDATE (4 slots) |
0x20 - 0x22 |
R_CONFIG_WRITE / READ / ERASE |
0x30, 0x31 |
I_CONFIG_WRITE (clears one bit) / READ |
0x40 - 0x42 |
R_MEM_DATA_WRITE / READ / ERASE (512 slots) |
0x50 |
RANDOM_VALUE_GET (0 to 255 bytes) |
0x60 - 0x63 |
ECC_KEY_GENERATE / STORE / READ / ERASE (32 slots, P-256 and Ed25519) |
0x70 |
ECDSA_SIGN (P-256 over a 32-byte hash, randomized) |
0x71 |
EDDSA_SIGN (Ed25519, 1 to 4096 byte messages) |
0x80 - 0x82 |
MCOUNTER_INIT / UPDATE / GET (16 counters, counting down) |
0x90 |
MAC_AND_DESTROY (128 slots, KMAC256 construction) |
Every command is gated by its User Access Privilege configuration (the
R-Config AND I-Config value, one bit per pairing slot). As in Tropic
Square's model, the firmware reads that configuration after a power cycle
or a Startup_Req reboot, so configuration writes take effect only then;
reads return the stored values at once. Result codes
follow the chip: UNAUTHORIZED for out of range targets, INVALID_KEY for
empty ECC slots, SLOT_NOT_EMPTY, SLOT_EMPTY, UPDATE_ERR and so on.
Unknown command IDs are INVALID_CMD. On FW 2.2.0 a SPECT command (ECC,
MAC-and-Destroy) rejected for its size leaves the firmware in a state that
spoils the next command that is not a SPECT command, as the chip does (see
HARDWARE_VALIDATION.md).
Each simulated device is provisioned on first start (or with
TROPIC01_SIM_FRESH=1) and saved as JSON after every command that can
change it:
- a CHIP_ID with the personality's layout and a random serial number;
- a static X25519 key pair (STPRIV/STPUB) and a four-certificate store with the same structure as the chip's: the X25519 device certificate, a P-384 intermediate, a P-384 cross certificate and a P-521 root, all issued under the simulator's own root CA (they do not chain to Tropic Square's roots);
- pairing slot 0 with the personality's libtropic key, slots 1 to 3 empty;
- for the
es-*personalities the configuration read from the bench chip (R-ConfigCFG_START_UP0xffffffef as shipped; 0xffffffeb in R-Config and 0xfffffffb in I-Config after the erratum fix; the rest erased), for2.2.0an erased R-Config and I-Config; - empty ECC slots, R-Memory, counters and MAC-and-Destroy slots.
With TROPIC01_SIM_WOLFSSL_FIXTURES=1, R-Memory slots 0 to 3 are filled
with the AES key, IV and Ed25519 key pair that wolfSSL's TROPIC01 port
(wolfcrypt/src/port/tropicsquare/tropic01.c) reads from its fixed slot
map. A real chip ships with empty R-Memory.
All tiers run from inside TROPIC01Sim/:
# 1. Rust unit and TCP integration tests
docker build -t tropic01-sim .
docker run --rm tropic01-sim
# 2. libtropic 4.2.0 (mbedTLS v4 CAL, posix/tcp HAL) driving the simulator
docker build -f Dockerfile.sdk-test -t tropic01-sdk-test .
docker run --rm tropic01-sdk-test
# 3. wolfSSL --with-tropic01 and Tropic Square's wolfssl-test app
docker build -f Dockerfile.wolfcrypt -t tropic01-wolfcrypt .
docker run --rm tropic01-wolfcrypt
# 4. Conformance probe against the simulator, compared with each hardware baseline
docker build -f Dockerfile.conformance -t tropic01-conformance .
docker run --rm tropic01-conformance# Build
cargo build --manifest-path tropic01-sim/Cargo.toml --release
# Unit and integration tests
cargo test --manifest-path tropic01-sim/Cargo.toml -- --test-threads=1
# Run the TCP server (127.0.0.1:28992, libtropic's posix/tcp default)
cargo run --manifest-path tropic01-sim/Cargo.toml --release --bin tcp_server
# Conformance check (needs libtropic and wolfSSL checkouts)
make -C conformance LIBTROPIC_DIR=/path/to/libtropic WOLFSSL_DIR=/path/to/wolfssl
conformance/run.shEnvironment variables of the TCP server:
| Variable | Default | Purpose |
|---|---|---|
TROPIC01_SIM_BIND |
127.0.0.1 |
Listen address |
TROPIC01_SIM_PORT |
28992 |
Listen port |
TROPIC01_SIM_STORE |
tropic01_store.json |
Persistent device state |
TROPIC01_SIM_FRESH |
unset | Provision a new device, ignoring the stored one |
TROPIC01_SIM_PERSONALITY |
es-0.1.2 |
Personality (es-0.1.2, es-2.2.0, 2.2.0); a stored device keeps its personality unless TROPIC01_SIM_FRESH is set |
TROPIC01_SIM_WOLFSSL_FIXTURES |
unset | Pre-load wolfSSL's R-Memory fixtures at provisioning |
TROPIC01_SIM_BUSY_POLLS |
1 |
GET_RESPONSE polls answered "busy" before each response |
| Tier | Dependency | Pin | Why |
|---|---|---|---|
| 2 (sdk-test) | libtropic | v4.2.0 (9085ea5) |
Current API, and the release the hardware was validated with |
| 2 | mbedTLS | 4.0.0 | What libtropic's examples fetch for the PSA CAL; OpenSSL verifies Ed25519 because that mbedTLS profile lacks PureEdDSA |
| 3 (wolfcrypt) | libtropic | v0.1.0 | wolfSSL's TROPIC01 port uses the v0.x API (lt_random_get, verify_chip_and_start_secure_session, ...) |
| 3 | wolfSSL | master |
Tracks the port; the build fixes a ForceZero / wc_ForceZero typo in tropic01.c |
| 3 | tropic01-wolfssl-test | main |
Tropic Square's test app, with its USB dongle HAL swapped for TCP |
| 4 (conformance) | libtropic | v4.2.0 (9085ea5) |
The baselines were recorded with it |
| 4 | wolfSSL | v5.9.4-stable | wolfCrypt CAL and signature checks |
- Firmware update: the firmware update L2 requests are
UNKNOWN_ERRin both modes (on the chip that is only true in application mode). - Chip timing: responses are ready after
TROPIC01_SIM_BUSY_POLLSpolls. - Sensors, the GPO pin and physical attack detection.
GPL-3.0-or-later. See ../LICENSE at the repo root.