Skip to main content
ZeroKeyUSB keeps credentials offline inside the encrypted EEPROM, so imports must happen after unlocking the device and require physical confirmation on the touch controls.

​
What you can import

Data typeSource formatNotes
Site / service namePlain text (32 bytes max)Long names automatically scroll on the OLED screen.
UsernamePlain text (32 bytes max)Trailing @ expands to the host domain when auto-typing.
PasswordPlain text (32 bytes max)All characters are accepted; stored encrypted in EEPROM.
TOTP secretBase32 (RFC 4648)Optional; stored in a dedicated encrypted page.
Each credential occupies three or four 32-byte EEPROM pages. The import process validates that the incoming data respects these limits before committing it.

​
Import methods

  1. Connect ZeroKeyUSB and unlock it with your Master PIN.
  2. Launch the ZeroKeyUSB Web Manager (served locally through the companion utility).
  3. Open Credentials → Import and choose a .csv or .json file exported previously.
  4. The manager converts every row into serial commands and sends them over the secure CDC channel.
  5. Confirm the overwrite on the device when prompted (Hold center to confirm).
The web manager never stores your credentials in the browser cache. Close the window when you finish importing.

​
2. Command-line utility

  1. Unlock the device.
  2. Run zerokeyusb-cli import backup.csv (available in the firmware repository).
  3. The CLI parses the CSV, streams it line-by-line, and verifies acknowledgements.
  4. Follow the on-screen confirmation prompts on ZeroKeyUSB.
This approach is ideal for automated or scripted deployments. The CLI exits with a non-zero status if any slot fails to write.

​
3. Manual serial session

For complete transparency you can interact with the serial port directly: 
screen /dev/ttyACM0 115200
IMPORT
<CSV row 1>
<CSV row 2>
...
<Ctrl+A> <\>
  • Send IMPORT to place the firmware in import mode.
  • Paste each CSV row: slot,site,username,password,totpSecret.
  • End the session or send an empty line to finalize.
  • Approve the operation on the device.
Use this method only on trusted machines because the credentials stay visible in terminal history.

​
CSV layout

slot,site,username,password,totp
0,example.com,[email protected],mY$up3rS3cret,
1,mail.example.com,alice,correct horse battery staple,JBSWY3DPEHPK3PXP
  • slot ranges from 0 to 63.
  • totp is optional; leave blank if no 2FA secret.
  • Fields containing commas should be quoted.
During import the firmware wipes the destination slot first, then writes each page sequentially to avoid partial corruption.

​
Conflict handling

  • Empty slots are filled immediately.
  • Occupied slots require you to hold the center touch pad for three seconds to confirm overwrite.
  • If the CSV references a slot outside the 0–63 range, the row is skipped and reported back to the host.
  • Invalid Base32 secrets are rejected and leave the slot unchanged.

​
After importing

  1. Browse the credential list to verify each entry.
  2. Optionally trigger Menu → Backup → Export to capture the new state.
  3. Safely disconnect the device using your operating system’s eject feature.
Following these steps ensures your imported passwords remain encrypted and recoverable solely from your ZeroKeyUSB.