Project Logs

Collapse

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

  superdog • a few seconds ago • 0 comments

  Touch ID is excellent when it's built into the machine or keyboard. Everywhere else — Mac mini, Mac Studio, clamshell MacBooks, external keyboards, Linux desktops — desktop biometrics are still awkward. immurok is a small wireless fingerprint key for those setups, and on Linux it goes through PAM, not a stored password.

  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...

  Read more »

• The immurok security model

  superdog • an hour 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 • an hour 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 3 project logs