How trustcrypto/onlykey-firmware works
Project Type and Purpose
• Type: Embedded firmware for a USB security token (OnlyKey).
• Purpose: Implements USB HID (keyboard + raw HID) interfaces, handles cryptographic operations, and maps user inputs to secure key outputs.
File Structure
Top-level items:
• OnlyKey/OnlyKey.ino → Main Arduino-style entry point
• usb_dev.c / usb_dev.h → USB device initialization & core HAL
• usb_desc.c / usb_desc.h → USB descriptors (HID, configuration, device IDs)
• usb_keyboard.c → USB Keyboard HID class implementation
• usb_rawhid.c / usb_rawhid.h → Raw HID class for custom commands
• keylayouts.c / keylayouts.h → Scancode maps for different keyboard layouts
• Libraries (external, not in tree): MBED TLS, micro-ECC, Yubico-C, ArduinoLibs crypto
Extract Architectural Insights from README
• Cryptographic libraries are linked statically into firmware.
• Firmware features are modular and added per release.
• Communication with host over standard USB HID and custom Raw HID protocols.
Main Components
a. Hardware & Host
• USB Host (PC, OS HID driver)
• OnlyKey hardware (MCU, Flash, Crypto co-processor if used)
b. Firmware Layers
1. Hardware Abstraction Layer (usb_dev)
2. USB Descriptor Layer (usb_desc)
3. USB Class Drivers
– HID Keyboard (usb_keyboard)
– HID Raw (usb_rawhid)
4. Application Layer
– Keylayout Manager (keylayouts)
– Crypto Engine (MBED TLS, micro-ECC, Yubico-C via ArduinoLibs)
– Command Dispatcher (parses Raw HID commands, invokes crypto or keystroke routines)
5. Main Loop (OnlyKey.ino) – initialization, event loop, power management
Relationships and Data Flows
• On Startup: OnlyKey.ino → initialize usb_dev → usb_desc registers descriptors → register USB class handlers
• Host sends HID requests → usb_dev ISR → usb_rawhid or usb_keyboard dispatch
• Raw HID commands → Command Dispatcher → Crypto Engine → Response via usb_rawhid
• Key press simulation → Keylayout Manager → usb_keyboard → host
Architectural Patterns & Principles
• Layered design (HAL → USB stack → class drivers → application)
• Modular separation (separate modules for descriptors, class drivers, layouts, crypto)
• Event-driven model (USB interrupts → dispatch handlers)
• Resource constraints (small footprint, static linking of crypto libraries)
Technologies, Frameworks, Libraries
• Language: C/C++ (Arduino)
• Build: Arduino IDE or makefile utilizing avr-gcc
• Crypto: MBED TLS, micro-ECC, Yubico-C, ArduinoLibs
• USB: Native USB support via usb_dev, descriptors, HID drivers