Skip to main content

​
Dual USB personality

ZeroKeyUSB operates as a composite USB device exposing two interfaces simultaneously:
  1. HID Keyboard – types usernames and passwords exactly like a physical keyboard.
  2. CDC Serial channel – a lightweight text-based protocol used for backups, diagnostics, and time synchronization.
Both remain active after unlocking, but any sensitive action requires explicit on-device confirmation.

​
Keyboard output engine

The firmware uses a compact US-QWERTY layout hardcoded in flash memory.
Each ASCII character is mapped to its corresponding USB HID keycode.
Future versions may add alternative layouts (ES, FR, DE…), but the current firmware always emulates US-QWERTY.

​
Typing sequence

When you select a credential, ZeroKeyUSB performs a scripted output:
  1. Types the username.
  2. Sends a Tab key.
  3. Types the password.
  4. Finishes with {ENTER} if the field includes that token.
TOTP codes are displayed on the OLED screen but are not auto-typed.

​
Serial command set

The serial channel communicates over 115200 bps using simple ASCII commands, one per line.
All commands are processed only after successful PIN unlock.
CommandDirectionDescription
PINGHost → DeviceReturns OK for connection testing.
REQTIMEDevice → HostRequests current Unix time; host replies SETTIME 1706227200.
SETTIME <epoch>Host → DeviceStores the given Unix epoch (binary, unencrypted).
EXPORTHost → DeviceSends all credentials in plain CSV format for local backup.
IMPORTHost → DeviceRestores a backup created on the same device and PIN (fails silently if PIN mismatch).
FACTORY_RESETHost → DeviceArms a secure wipe; requires 5-second long-press confirmation on the device.
Messages are short, human-readable text lines — not JSON — making the protocol easy to audit and debug.

​
Time synchronization

TOTP codes require accurate timing.
When the device shows REQTIME, send the current Unix time once: REQTIME # displayed on screen SETTIME 1706227200 The firmware stores the epoch as an 8-byte binary value (not encrypted).
Elapsed time is tracked in software using the SAMD21’s millis() counter — no hardware RTC is used.
If drift exceeds roughly ±90 s, the device will request time again.

​
Backup workflow

  1. Unlock the device and open Menu → Backup → Export.
  2. Start the local web manager or CLI; it listens to the serial stream.
  3. The device outputs all credentials in plain text CSV format (site, user, password, optional TOTP flag).
  4. To restore, choose Import and send the same file back.
    The firmware verifies basic integrity and overwrites existing entries.
⚠️ Backups are not encrypted. Handle them carefully and store them offline, as they contain readable credentials.

​
Safe factory reset

Executing FACTORY_RESET wipes:
  • All credential pages
  • PIN signature and failed-attempt counter
  • Initialization vector (a new IV is generated on next boot)
A visible countdown (Hold to confirm: 5…0) ensures this cannot be triggered accidentally by software alone.
There is no hidden debugging interface on the serial channel.
All available commands are documented here, and any action affecting stored data requires physical confirmation on the device.
⌘I