Project Logs

Collapse

• Eight PCB revisions for a tiny wireless fingerprint key

  superdog • 2 hours ago • 0 comments

  Notes from building immurok: a wrong MCU choice, a sensor swap, a tamper switch that only worked while powered, and a long fight to get standby current down to 40 uA.

  immurok is a small wireless fingerprint key: touch the sensor, approve the action, get back to work. It took eight PCB revisions to get there. These are the notes — the boards we scrapped, the parts that looked right until they met a battery, and the mechanical choices that worked in CAD and failed in plastic.

  Four things drove most of the rework: keep the radio connected without draining the battery, make the sensor usable without it glowing like a toy, build an enclosure that survives assembly, and make the tamper switch actually do something.

  Picking the MCU: ESP32 was too power-hungry

  The first prototypes used ESP32-S3 and ESP32-C3. Familiar, well documented, easy to bring up.

  Then we looked at the power budget. immurok sits on a desk for weeks, wakes on touch, and does nothing the rest of the time. The number that matters is idle current, not peak current during BLE traffic. The ESP32 direction projected over 200 uA static before the design was even finished. For a battery-powered key, that drains the battery while the user is doing nothing.

  So we moved to CH592F. Tighter RAM, less convenient, but it gave us the sleep budget a desk key needs. The shipping design idles around 40 uA, after a lot of measurement and firmware tuning — BLE intervals, sensor rails, pull resistors, LEDs, wake paths, and every GPIO default.

  Takeaway: for a device that’s supposed to disappear into the desk, the MCU choice is the product, not an implementation detail.

  Choosing a fingerprint sensor

  Our first working path used ZW3021-class modules. They worked: enroll a finger, match locally, report over UART. The problem was the built-in lighting — blue rings, green glows, decorative LEDs that make sense on an access-control panel and look wrong on a desk. The light also costs power and complicates the enclosure.

  For a while we had a promising module shaped like a ping-pong paddle. Mechanically it fit a small handheld object well, and it skipped the built-in-light problem. Then the vendor told us they couldn’t support the volume we’d need for a real run. “Can I buy five?” and “Can I buy five thousand, repeatedly, without redesigning the product?” are different questions.

  We settled on R559S: no light, on-module matching, fits the enclosure. It has one catch — after every power cycle, firmware must explicitly enable the touch interrupt switch. Most modules we tested do this automatically. On R559S, if firmware doesn’t send the setup command after power is restored, touch no longer wakes the system.

  This matters in the failure path. If firmware crashes before re-enabling the touch interrupt, the user can touch the sensor forever and nothing happens. So we treat the command as part of the power system, not a feature toggle: bring up the sensor early, and re-send the touch-interrupt command after every power transition.

  Why the board shape kept changing

  The PCB revisions were half the story. The other half was a pile of failed enclosures: sensor holes a millimeter off, screw posts colliding with components, shapes that looked fine in CAD and felt wrong in the hand.

  Each failed case pushed back on the board. The sensor opening set how far the module could sit from the edge. The screw posts set where copper couldn’t go. The USB connector needed room for a cable and fingers. The antenna needed air, not a wall of plastic and metal. Button and LED positions changed once the enclosure became something you could actually press.

  • VER0 — proving the parts could talk: MCU, sensor, buttons, debug UART, BLE. A lab board, not a product.
  • VER1–2 — real mechanical constraints: USB connector placement, sensor flex routing, room for a switch, antenna clearance, how the device sits in the hand.
  • VER3–4 — consolidation. Components moved off the edges, power routing got...

  Read more »

• Why desktop fingerprint authentication is still awkward on Mac and Linux

  superdog • 2 hours ago • 0 comments

  Touch ID is excellent when it is built into the machine or keyboard. The awkward part starts everywhere else: Mac mini, Mac Studio, closed-lid MacBooks, external keyboards, Linux desktops, and terminal-heavy workflows.

  immurok is my attempt to build a small wireless fingerprint key for those setups.

  It is not meant to be “Apple Touch ID, but external.” Touch ID is Apple’s own secure platform, deeply fused into the Secure Enclave and the OS. immurok is something more modest and more honest about its scope: a local-first desktop authentication device with clear limits.

  Where built-in fingerprint auth runs out

  If you use a laptop with the sensor under your thumb, none of this is your problem. But a lot of desktop computing doesn’t look like that:

  • Mac mini and Mac Studio ship with no fingerprint reader at all. Apple’s only first-party answer is a $199 Magic Keyboard with Touch ID.
  • A MacBook in clamshell mode, driving an external display, can’t reach its own sensor — the lid is closed.
  • External keyboards — and especially mechanical keyboards, which a lot of developers prefer — have no biometric story on macOS unless you buy Apple’s specific keyboard.
  • Linux desktops can do fingerprint auth through fprintd, but good, well-supported hardware is genuinely scarce, and setup is fiddly.
  • Terminal-heavy workflows are the worst case: you sudo a dozen times an hour, sign Git commits, SSH into boxes — and every one of those is a password prompt.

  The common thread is that biometric auth is welded to specific hardware. The moment your setup steps outside that hardware, you’re back to typing passwords.

  What immurok actually is

  A small wireless key with a capacitive fingerprint sensor that pairs to your computer over Bluetooth LE. Concretely, its scope is:

  • Linux sudo and system authentication through PAM. This is the cleanest integration — see below for why it matters.
  • A Linux CLI/TUI app for pairing, status, and local control — no GUI required, built for people who live in the terminal.
  • macOS sudo / system-prompt support through PAM integration, for the auth prompts that do consult PAM.
  • Mac desk-setup workflows — Mac mini, Studio, clamshell, external keyboards — where Touch ID is missing or impractical.
  • Fingerprint matching on the device. Your fingerprint template is enrolled and matched on the key itself; it never travels over Bluetooth, never lands on your disk, and there is no cloud to send it to.
  • Open-source firmware and software. The macOS app, the PAM module, the Linux app, and the hardware design are open; the firmware will be opened up before the end of the year.

  It is deliberately a single-purpose device. No screen, no account, no app store — a key that proves a fingerprint touch happened, and lets your OS act on it.

  The distinction that matters: PAM, not a typed password

  Here is the part I most want to be clear about, because it’s the easiest thing to get wrong when you build something like this.

  For sudo and system authentication, immurok is not just typing a stored password for you. A lot of “fingerprint unlock” gadgets are really just a biometric trigger wired to a password autotyper: they keep your password somewhere, and when you touch the sensor they replay it into the prompt. That works, but it means your password is sitting in storage, and anything that can see the keystrokes sees your password.

  On Linux, immurok integrates through PAM — the same authentication framework sudo, login, and polkit already use. When you run sudo, the PAM stack asks immurok’s module, the module checks with your paired device over an authenticated channel, you touch the sensor, and PAM gets back a real success/failure result. There’s no stored password being replayed — the authentication decision flows through the OS’s own auth pipeline, the way a fingerprint should.

  On macOS the picture is split, and it’s worth being precise:

  • For prompts that consult PAM — sudo in a terminal, some system dialogs...

  Read more »

• The immurok security model

  superdog • 3 hours ago • 0 comments

  A fingerprint key is only as good as the trust it can prove. Here's how immurok keeps your biometrics on the device, authenticates every touch, and refuses to phone home — ECDH pairing, HMAC-signed events, and signed firmware, end to end.

  immurok replaces your password with a fingerprint. That only works if the fingerprint touch is something your Mac can trust — not just a button press that any nearby radio could fake. This post is the full picture of how that trust is built: what the device proves, what the host verifies, where keys live, and the things we deliberately refuse to do.

  The threat model

  We designed against a concrete set of attackers:

  • A passive radio eavesdropper sniffing Bluetooth LE traffic in the room.
  • An active attacker who can connect to the device, spoof advertisements, or replay captured packets.
  • A malicious or compromised peripheral pretending to be your immurok key.
  • A thief who walks off with the device itself.
  • A supply-chain attacker trying to push tampered firmware onto the device over the air.

  And a set of principles we hold regardless of attacker:

  1. Your biometric never leaves the sensor. Not over BLE, not to disk, not to a cloud.
  2. Every authentication event is cryptographically authenticated — a touch the host accepts must have come from your paired device.
  3. No cloud, no account, no telemetry. The entire system works offline. There is no server to breach because there is no server.
  4. The host is the policy engine; the device is the proof. macOS decides what a touch unlocks; the device only proves that a real, authenticated touch happened.

  Biometrics stay on the device

  The fingerprint sensor (an R559S capacitive module) does matching on-chip. Enrollment templates are stored in the sensor’s own flash and are never read out over the wire. The CH592F microcontroller that runs immurok’s firmware never sees your fingerprint image or template — it only ever receives a match result: page N matched, or no match.

  That means the BLE link, the companion app, your Mac’s disk, and certainly our infrastructure (which doesn’t exist for this) never hold anything that could reconstruct a fingerprint. The worst case for a stolen device is a stolen device — not a stolen identity.

  Matching strictness matters here too. The sensor exposes a configurable score threshold, and the firmware sets it explicitly rather than trusting a vendor default. We learned this the hard way: an early build left the score level unset, fell back to the module’s lax default, and a second validation step was missing in firmware — which let unenrolled fingers occasionally pass. The fix (firmware 1.3.14) pins the score level and re-validates the match index in firmware before signing anything. Biometric thresholds are now part of the build, not an accident of defaults.

  Pairing: ECDH, once

  When you pair a device, the app and the device run an ECDH key agreement over NIST P-256:

  1. The app generates an ephemeral P-256 key pair and sends its compressed public key (33 bytes) to the device.
  2. The device does the same and sends its public key back.
  3. Both sides compute the shared secret, then run it through HKDF-SHA256 (with a fixed salt and info string) to derive a 32-byte symmetric shared key.

  let sharedSecret = try privateKey.sharedSecretFromKeyAgreement(with: devicePubKey)
  let symmetricKey = sharedSecret.hkdfDerivedSymmetricKey(
      using: SHA256.self,
      salt: "immurok-pairing-salt",
      sharedInfo: "immurok-shared-key",
      outputByteCount: 32
  )

  The shared key never crosses the wire — each side derives it independently from the key agreement. The ephemeral private key is discarded the moment pairing completes. From then on, the app and the device share one secret that proves they paired with each other.

  This is a single-device design on purpose: one key, one device, no roaming credentials to manage or leak.

  Every touch is signed

  A fingerprint match isn’t a bare “OK” byte that anyone could forge. When the device confirms a match, it emits...

  Read more »

• Why we're building immurok

  superdog • 3 hours ago • 0 comments

  Millions of developers use desktop Macs and Linux machines without any biometric auth. We're building a tiny wireless fingerprint key to fix that.

  If you use a Mac mini, Mac Studio, or a MacBook in clamshell mode with an external keyboard, you know the pain: no Touch ID. Apple’s only solution is a $199 Magic Keyboard — and if you prefer a mechanical keyboard, you’re completely out of luck.

  Linux users have it even worse. fprintd exists, but good hardware options are scarce.

  The problem

  Every time you:

  • Unlock your screen
  • Run sudo / ssh
  • Approve a system dialog
  • Sign a Git commit

  …you type a password. Dozens of times a day.

  Our solution

  immurok is a tiny wireless device with a capacitive fingerprint sensor. It connects via Bluetooth LE and replaces passwords with a single touch:

  • Screen unlock — touch the sensor, screen unlocks
  • sudo & PAM — custom PAM module intercepts auth prompts
  • SSH agent — sign commits and SSH into servers with your fingerprint
  • Open source — the macOS app and PAM module are fully auditable

  Security first

  Your fingerprint template never leaves the device. Authentication uses ECDH P-256 key exchange and HMAC-SHA256 signed messages. There’s no cloud, no account, no telemetry — everything works offline over Bluetooth.

  We’ll be sharing more technical deep-dives on the BLE protocol, PAM integration, and firmware architecture in upcoming posts. Stay tuned.

View all 4 project logs