Skip to main content

Phantom Key — Hardware Authenticator

Phantom Key is a hardware TOTP authenticator that uses split-key cryptography for enhanced security. The complete secret never exists in one place — it is split between your Mac and a physical hardware device. Both halves are required to generate authentication codes, making it immune to phishing and remote attacks.

Features​

  • Split-key architecture — TOTP secret split between app and hardware device using XOR
  • Hardware requirement — Physical device must be present to generate codes
  • Multi-account support — Manage multiple TOTP accounts on one device
  • Auto-expiry — Codes expire after configurable time limit for security
  • No cloud sync — Secrets never leave your devices
  • USB connection — Direct communication via USB serial, no network required

Overview​

Traditional authenticator apps store the complete TOTP secret on your phone or computer. If your device is compromised, attackers can generate codes indefinitely. Phantom Key solves this by splitting the secret into two halves:

  • App Half — Stored in Camouflage Hub on your Mac
  • Device Half — Stored on the RP2350 hardware device

Neither half alone can generate valid codes. The complete secret only exists briefly in the device's RAM when both halves are combined via XOR operation, then immediately disappears.

How It Works​

When you add an account to Phantom Key, the TOTP secret is automatically split:

  1. A random device half is generated
  2. The app half is calculated using XOR: App Half = Full Secret ⊕ Device Half
  3. The device half is sent to the hardware device and stored in firmware
  4. The app half is stored locally in Camouflage Hub
  5. The full secret is never stored anywhere permanently

To generate a TOTP code:

  1. You select an account and click Send
  2. The app sends the app half and current timestamp to the device via USB
  3. The device combines both halves: Full Secret = App Half ⊕ Device Half
  4. The device generates the TOTP code using the full secret and timestamp
  5. The code is displayed on the hardware device's LCD screen
  6. The device auto-regenerates codes every 30 seconds
  7. After the configured expiry time, the device stops generating codes until you send a new request

Getting Started​

  1. Open Camouflage Hub
  2. Click the Phantom Key card
  3. Sign in if prompted (Phantom Key requires authentication)
  4. Connect your Phantom Key hardware device via USB
  5. Click Refresh Ports to detect the device
  6. Select the device port from the dropdown (usually /dev/cu.usbmodem####)
  7. Click Connect

Hardware Requirements​

Phantom Key requires a physical hardware device:

  • Waveshare RP2350-LCD-1.47-B — RP2350 microcontroller with 1.47" LCD display
  • USB-C connection — Direct connection to your Mac or PC
  • Pre-flashed firmware — Retail units come pre-configured and ready to use

The hardware device is a standalone authenticator with its own display and processor. It does not require internet connectivity and communicates with your Mac only via USB.

Managing Accounts​

Adding an Account​

To add a new TOTP account to Phantom Key:

  1. Click Add Account in the Phantom Key window
  2. Enter a name for the account (e.g. "GitHub", "Gmail", "AWS")
  3. Paste the TOTP secret from your service:
    • When setting up 2FA on a website, choose "manual entry" or "can't scan QR code"
    • Copy the Base32 secret string (e.g. JBSWY3DPEHPK3PXP)
    • Paste into the Phantom Key secret field
  4. Set Auto-Expire After (default: 5 code generations = 2.5 minutes)
  5. Click Add Account

The app automatically splits the secret and sends the device half to the hardware. Your account is now ready to use.

Generating Codes​

To generate a TOTP code for an account:

  1. Select the account from the list
  2. Click the Send button
  3. The hardware device displays:
    • Account name in the blue title bar
    • 6-digit TOTP code (large, centered)
    • Progress bar showing time remaining in the 30-second window
    • Countdown timer
  4. The device auto-regenerates codes every 30 seconds
  5. Enter the displayed code into your login prompt

The device will continue generating codes for the configured number of cycles (default: 5 cycles = 2.5 minutes), then show an "Expired" screen. Click Send again to start a fresh session.

Deleting Accounts​

To remove an account:

  1. Select the account from the list
  2. Click Delete Account
  3. Confirm the deletion

This removes the account from both the Mac app and the hardware device.

Account Tracking​

Each account in the list shows:

  • Account name — The label you assigned
  • Last used — When you last generated a code
  • Generation count — Total number of codes generated for this account

Security Model​

Phantom Key's split-key architecture provides protection against multiple attack vectors.

Split-Key Protection​

The TOTP secret is split using XOR (exclusive OR):

Full Secret ⊕ Device Half = App Half
App Half ⊕ Device Half = Full Secret

This means:

  • Stealing the Mac or laptop gives the attacker only the app half (useless)
  • Stealing the hardware device gives the attacker only the device half (useless)
  • Both halves are required to generate valid codes
  • Neither half reveals any information about the full secret

Threat Model​

Attack VectorProtection
Phishing attackHardware device required — attacker can't generate codes remotely
Malware on MacApp half alone cannot generate codes
Stolen hardware deviceDevice half alone cannot generate codes
Physical theft of bothSame as stealing phone with authenticator app
Firmware extractionRequires advanced tools and physical access to device

Generation Limits​

Each TOTP session has a configurable generation limit (default: 5 codes = 2.5 minutes). After this limit:

  • The device stops generating codes and shows "Expired"
  • A 30-second countdown is displayed
  • The device returns to "Ready" state
  • You must click Send again to start a new session

This prevents unlimited code generation if you walk away from your device while it is connected.

Clock Synchronization​

The hardware device synchronizes its clock from your Mac on every TOTP request. This ensures:

  • No clock drift issues between device and server
  • Codes always match the expected 30-second window
  • The device crystal accuracy is irrelevant (constant re-sync)

No Network Transmission​

Phantom Key never transmits secrets over the network:

  • TOTP secrets are split and stored locally
  • Device halves are sent to hardware via USB serial only
  • No cloud storage or backup
  • No internet connectivity required

Hardware Device Display​

The Phantom Key hardware device has three display states:

Ready State​

When idle and waiting for a command, the device shows:

Phantom Key
Ready
N accounts stored

This confirms the device is powered, connected, and ready to generate codes.

Active State​

When generating codes, the device shows:

  • Account name (in blue title bar)
  • 6-digit TOTP code (large, centered)
  • Progress bar (showing time remaining in 30-second window)
  • Countdown timer (seconds until next code)
  • Generation counter (e.g. "1/5" means first of five allowed codes)

The code and progress bar update every 30 seconds automatically.

Expired State​

After the generation limit is reached, the device shows:

Phantom Key
Expired
Request New Code

With a 30-second countdown bar. After 30 seconds, the device returns to the Ready state. Click Send in the app to start a new session.

Hub Status​

On the Hub, Phantom Key shows:

  • Ready (green) — Hardware device is connected and operational
  • Disconnected (grey) — No device detected
  • Requires Sign-In — Authentication needed to access Phantom Key

Coming Soon​

Future releases of Phantom Key will include:

FIDO2 / WebAuthn Support​

Phantom Key will support passwordless authentication using FIDO2 and WebAuthn standards:

  • Register hardware keys with GitHub, Google, AWS, and other services
  • Passwordless login without typing passwords
  • Phishing-resistant authentication
  • Visual key indicator on device display when authenticating

Hardware-Authenticated VPN​

Integration with Camouflage VPN for hardware-authenticated network access:

  • VPN handshakes require physical Phantom Key device
  • Visual VPN authentication approval on device display
  • Device must remain connected for entire VPN session
  • Unplugging device immediately disconnects VPN

Windows and Linux Support​

The Camouflage Hub app and Phantom Key will support Windows and Linux desktop platforms.

Authentication​

Phantom Key requires authentication. If you are not signed in, clicking Phantom Key will redirect you to the login page. Sign in with Google or Microsoft SSO to access your accounts.

Account data is stored locally on your Mac and is never transmitted to Camouflage servers. Authentication is required only to access the Phantom Key interface within Camouflage Hub.