Skip to main content
TOTP stands for Time-based One-Time Password — the same standard used by Google Authenticator or Authy. ZeroKeyUSB calculates each 6-digit code offline, using the encrypted secret stored in EEPROM and a locally maintained Unix time value.

​
How it works

  • Secrets are imported as Base32 strings and encrypted with AES-128 before being written to EEPROM.
  • The firmware keeps an 8-byte Unix epoch counter in plaintext (for simplicity) and increments it using the SAMD21 millisecond timer.
  • Every 30 seconds the device computes Truncate(HMAC-SHA1(secret, epoch / 30)) and shows the result on the OLED.
Because the algorithm follows RFC 6238, the codes match any mainstream authenticator application while staying isolated from the Internet.

​
Adding a TOTP secret

  1. Unlock the device and open the credential you want to protect.
  2. Use the local web manager or CLI to paste the otpauth:// URI provided by the service.
  3. The tool extracts the secret= parameter and sends it once over the secure serial channel.
  4. ZeroKeyUSB encrypts the secret, stores it in the TOTP page, and flags the slot as 2FA-enabled.
Secrets are never shown in plain text after they are stored.

​
Viewing codes

  • Credentials with a TOTP secret show a 2FA → Touch to view prompt beneath the password.
  • Tapping the center pad reveals the current 6-digit code and a countdown ring that refreshes each second.
  • The screen auto-hides after 15 seconds of inactivity to keep codes private.
If the device needs the current epoch, it displays REQTIME and waits for the host to send the time once.

​
Keep it accurate

Epoch Synchronization

Understand how ZeroKeyUSB tracks Unix time and how to resync when drift occurs.

Web Time Sync Tool

Step-by-step guide for using the browser-based utility to keep the TOTP clock aligned.

​
Supported algorithms

Future firmware releases can extend the hash options without changing hardware.

​
Text notes instead of a code

The same per-credential field can hold a plaintext note — a recovery code, a hint, anything worth jotting down — instead of a TOTP secret. You choose per credential in the webtool: a selector marks the field as 2FA code or Note.
  • A note is hidden when empty, exactly like the 2FA field.
  • When present it is shown on the device (scrolling if long) with a document icon, so you can read it.
  • It is never typed over USB and never editable on-device — notes are set only from the webtool.
  • Limit: 32 characters (the field’s storage capacity).
The field’s type lives in its metadata byte (a NOTE marker), so the data needs no special marker on-device; backups round-trip the type via a note: prefix, so importing needs no manual re-marking.

​
Best practices

  • Resync time after long storage or travel across time zones.
  • Keep an offline backup of your credentials before performing a factory reset.
  • Treat printed or exported TOTP secrets as highly sensitive material.
With TOTP handled directly by the hardware key, your password and second factor stay together yet remain offline.