Skip to main content

​
Modular by design

ZeroKeyUSB firmware is written in C++ for the Microchip SAMD21E18A microcontroller (ARM Cortex-M0+, 48 MHz, 256 KB flash, 32 KB SRAM).
It follows a layered architecture that keeps hardware drivers, security primitives, and the user interface cleanly separated. Each module can evolve independently while keeping critical security routines auditable and easy to review.

​
Source file map

​
Boot sequence

The configuration flag at 0x0000 determines whether the device shows the setup wizard (flag ≠ 0x42) or the PIN unlock screen (flag = 0x42). The wizard writes 0x42 after successful PIN creation.

​
Main loop

The firmware runs a cooperative main loop — no RTOS, no interrupts for application logic, no dynamic memory allocation: Each iteration is deterministic. Timing-sensitive operations (TOTP countdown, lockout delays) use millis() instead of blocking delays.

​
Screen state machine

Every interactive view is a state identified by a programPosition constant. Touch events are dispatched based on this value:

​
I²C bus topology

All peripherals share a single I²C bus: Bus speed: 100 kHz (set at boot, matches bootloader).
The TS06 address is 0xD2 >> 1 = 0x69.

​
USB composite device

ZeroKeyUSB enumerates as a composite USB Full-Speed device with two interfaces: Both interfaces are active simultaneously after boot. The CDC channel requires PIN unlock before accepting any data-modifying commands.

​
Memory footprint

No dynamic memory allocation (malloc/new) is used anywhere. All buffers are stack-allocated or static.

​
Build & verification

  • Compiled with ARM GCC using the Arduino SAMD core.
  • Build process managed by Makefile — supports selective compilation and J-Link flashing via Dashboard.bat.
  • Firmware binary is signed with a BLAKE2s MAC and appended with a 28-byte security footer.
  • The bootloader verifies this signature at every boot using CRC32 + BLAKE2s before jumping to application code.
  • Unsigned or tampered firmware triggers a 15-second penalty delay and falls into USB-CDC DFU mode.
ZeroKeyUSB runs on a minimal firmware stack: no RTOS, no dynamic memory allocation, and no hidden debug backdoors.
All tasks are cooperative and time-deterministic — simplicity is treated as a security feature.