Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zerokeyusb.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Welcome to ZeroKeyUSB

Congratulations on your new ZeroKeyUSB — a fully offline, hardware-encrypted password manager.
No apps to install, no accounts to create, no cloud to trust. Just plug it in. ZeroKeyUSB device overview

​
What’s in the box

ItemDescription
ZeroKeyUSB deviceEpoxy-sealed hardware key with OLED screen and 5 capacitive touch pads
USB-C cableFor connecting to your computer, tablet, or phone
That’s it. No software disc, no activation card — because ZeroKeyUSB needs none of that.

​
Know your device

ZeroKeyUSB has five golden touch pads arranged in a cross pattern. These are your only controls:
PadShort tapLong press
⬆ UpChange digit / Scroll up—
⬇ DownChange digit / Scroll down—
⬅ LeftGo back / Delete digitJump 10 slots back
➡ RightGo forward / Add digitJump 10 slots forward
● CenterConfirm / SelectEdit field / Type to host

​
Step 1 — Plug in & power up

1

Connect the USB-C cable

Plug ZeroKeyUSB into any USB-C port on your computer, tablet, or phone.
The device draws about 20 mA — less than a wireless mouse — and needs no battery.
2

Wait for the splash screen

The OLED screen lights up showing:
ZeroKeyUSB
This confirms all hardware is working: the display, the touch controller (TS06), the EEPROM memory, and the ATECC608A secure element.
3

First-time setup wizard

On a brand-new device, the setup wizard starts automatically.
It walks you through screen orientation, keyboard layout, and PIN creation — one step at a time.
Use Right to advance and Left to go back.

​
Step 2 — Choose your screen orientation

The wizard asks if the screen and controls feel right-side-up.
  • Press Center to flip the display 180°.
  • Press Right when it looks correct.
This setting is saved in EEPROM and persists across power cycles.

​
Step 3 — Select your keyboard layout

ZeroKeyUSB emulates a USB keyboard. To type special characters correctly (@, !, #, etc.), it needs to match your computer’s keyboard layout. Available layouts:
CodeLanguage
EN-USEnglish (United States) — default
ES-ESSpanish
FR-FRFrench
DE-DEGerman
IT-ITItalian
PT-PTPortuguese
DA-DKDanish
SV-SESwedish
HU-HUHungarian
Press Center to cycle through layouts, then Right to confirm.
You can change the layout later from Menu → Settings → Keyboard.

​
Step 4 — Create your Master PIN

This is the most important step. Your PIN protects everything on the device.
1

Choose 4–16 digits

Use Up/Down to change the current digit (0–9).
Press Right to add a digit.
Press Left to delete the last digit.
2

Confirm your PIN

Type the same PIN again for confirmation.
If they don’t match, you’ll be asked to start over.
3

Wait for security setup

The device shows a progress bar while it:
  1. Derives your PIN hash: SHA-256(PIN ∥ chip_serial)
  2. Stores the hash in the ATECC608A secure element (slot 9)
  3. Generates a 128-bit AES master key from the hardware TRNG
  4. Generates a 128-bit IV (Initialization Vector) from the TRNG
  5. Sets the hardware PIN attempt counter (Counter0)
  6. Initializes all 62 credential slots with encrypted blanks
This takes about 30–60 seconds.
There is no PIN recovery. If you forget your PIN, the only option is a factory reset that permanently erases all stored credentials. Choose a PIN you will remember.

​
Step 5 — Understanding the security

Here’s what happens behind the scenes when you enter your PIN: Key security features:
  • Hardware counter (Counter0): Every PIN attempt — right or wrong — increments an irreversible hardware counter in the ATECC608A. After 50 consecutive wrong attempts, the device permanently wipes all data.
  • Exponential delay: Wrong PIN? Wait 5 seconds. Wrong again? 10 seconds. Then 20, 40, 80… up to 43 minutes between attempts.
  • Constant-time compare: The PIN hash comparison uses a timing-safe algorithm that reveals nothing about which digits were correct.

​
Step 6 — Store your first credential

After unlocking, you see the main screen showing slot 0: 
🌐 ________________
👤 ________________
🔒 ________________
1

Navigate to a field

Use Up/Down to switch between the Site, Username, and Password views.
2

Enter edit mode

Long-press Center on any field to start editing.
3

Type characters

The editor shows three keyboard pages:
  • Page 1: A-Z and brackets
  • Page 2: a-z and symbols
  • Page 3: 0-9, space, and special characters
Use Left/Right to move the cursor, Up/Down to switch keyboard pages, and Center to insert a character.
4

Save and return

Long-press Center again to save and return to the main screen.
Your credential is immediately encrypted with AES-128 CBC and written to EEPROM.
Use Left/Right on the main screen to move between credential slots (0–61). Long-press Left/Right to jump 10 slots at a time.

​
Step 7 — Type credentials to your computer

This is where the magic happens:
  1. Navigate to the credential slot you want.
  2. Press Center on the Site field → ZeroKeyUSB types the username + Tab + password as a USB keyboard.
The host computer sees ZeroKeyUSB as an ordinary keyboard — no drivers or software needed.
Works on Windows, macOS, Linux, Android, and iPadOS.

​
Step 8 — (Optional) Add 2FA / TOTP

ZeroKeyUSB can generate time-based one-time passwords (TOTP) — the same codes you’d get from Google Authenticator, but fully offline.
1

Import your TOTP secret

Use the web manager or serial CLI to send the Base32-encoded secret (from the otpauth:// QR code your service provides). The secret is encrypted and stored in page 3 of the credential slot.
2

Sync the clock

Since ZeroKeyUSB has no real-time clock, it needs the current time once.
When you see REQTIME on screen, the web manager or a terminal sends the Unix epoch over USB serial.
The time is saved in EEPROM and tracked using the SAMD21’s millis() counter.
3

View your 2FA code

Navigate to a credential that has a TOTP secret and scroll to the 2FA view.
A 6-digit code appears with a 30-second countdown. It refreshes automatically.

​
Step 9 — Back up your data

Backups are transmitted in plain text over USB serial. Only perform this on a trusted computer.
  1. Navigate to Menu → Backup → Export.
  2. Hold Center to authorize the export.
  3. ZeroKeyUSB sends all 62 credential slots as CSV lines over the USB serial port.
  4. Save the output file securely — encrypt it with GPG, age, or a password-protected ZIP.
To restore later: Menu → Backup → Import → send the CSV file back via the web manager or serial CLI.

​
Quick reference card

ActionHow
UnlockEnter PIN on touch pads
Browse credentialsLeft / Right (short press)
Jump 10 slotsLeft / Right (long press)
Switch fieldUp / Down on main screen
Type to computerCenter on Site field
Edit a fieldLong-press Center
Open menuScroll past last slot
View 2FA codeDown past Password to 2FA
Export backupMenu → Backup → Export
Factory resetMenu → Danger Zone → Factory Reset

​
Next steps

Hardware Overview

Understand the main components: SAMD21 MCU, ATECC608A secure element, EEPROM, and touch controller.

Security Architecture

Learn how AES-128 CBC, the ATECC608A TRNG, and Counter0 work together to protect your data.

Menu System

Explore every menu option: Backup, Settings, Danger Zone, and device Info.

TOTP Module

Set up offline 2FA codes with time synchronization and automatic code refresh.
ZeroKeyUSB works on any operating system that supports USB keyboards.
No drivers, browser extensions, or software installations are required — ever.