tinyTouch: fingerprint sudo and login over HID or PIV on macOS
authenticate, sudo, login with your fingerprint wire(less)ly without having to spend $149 at the cost of some security
At a glance
- What is it?
- tinyTouch is an ESP-based fingerprint device that types your password or acts as a PIV smart card, so you can authenticate on a Mac without a $149 keyboard. The README is candid about the trade-off: it depends on an unauthenticated UART between sensor and ESP.
- Who is it for?
- tinyTouch suits people who keep a Mac at a desk, are comfortable flashing firmware and running a Python helper, and accept that the sensor-to-ESP link is unauthenticated. It is the wrong choice for a company device, a shared or travelling machine, or anything holding classified material; the README itself points those users at a $149 Magic Keyboard instead.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 19, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What tinyTouch replaces, and who it is built for
The problem tinyTouch addresses is narrow and concrete: on a Mac, logging in, unlocking the screen and answering `sudo` all want a password, and a fingerprint reader that covers those prompts otherwise means paying for Apple's keyboard. tinyTouch is a small ESP board wired to a fingerprint sensor that either pretends to be a USB keyboard or pretends to be a USB smart card, so the same physical touch covers login, `sudo` and lockscreen.
The README is explicit about the audience. It asks the reader to answer a list of questions before choosing a mode: whether the device ever leaves your desk, whether roommates or family could perform a flash dump, whether you are protecting sensitive or classified information, whether you are on a company device. If any answer is yes, the README says "the magic keyboard presents an excellent value at $149 and is worth the added security." That is an unusually direct statement of who should not use a project, and it should be read as part of the product, not as marketing hedging.
The repository also points at a preassembled option through tinytouch.dev, and at a build guide on YouTube, so the DIY path is not the only route in.
HID mode: the ESP types your password after a fingerprint match
In HID mode the ESP enumerates as a USB keyboard. The design deliberately keeps the password off the ESP: the macOS helper stores your real password encrypted on the Mac, and the ESP holds only a shared pairing key. After a fingerprint match, the ESP sends a signed request to the helper; the helper verifies it, encrypts the password for that single request, and returns it. The ESP decrypts it in RAM, types it, and wipes it.
Two mechanisms limit replay. Requests carry a nonce and a MAC, so an old request cannot simply be resent, and the helper replies with an encrypted one-time response. The README notes the password exists on the ESP only briefly in RAM.
The trade-off is stated plainly: the final step is still your real password being typed into whatever window has focus. That is why HID mode works almost everywhere, including remote SSH sessions, and also why it inherits the failure modes of typing: the wrong field focused, or a malicious password field, both apply. HID mode also covers Apple TCC privacy prompts, general settings and keychain passwords, which PIV mode does not.
PIV mode: a smart card whose key use is gated by the fingerprint
In PIV mode the ESP enumerates as a USB smart card. macOS sends ordinary PIV commands over CCID, and when it needs authentication it asks the card to use the PIV private key. The firmware only permits that key operation immediately after a fingerprint match.
macOS still expects a PIV PIN, so the firmware has a small HID side path that types the dummy PIN `000000`. The README is careful about this: that PIN is not your Mac password, and the project does not treat it as sensitive, because authorization is gated by the fingerprint around the key. PIV mode therefore avoids typing your real password, but only works where macOS accepts smart cards, such as login and `sudo` through PAM.
The security table gives PIV mode the stronger authentication story: challenge and response rather than a typed secret. It also gives it the weaker transport story, described as plain USB CCID/APDU, with no shared-key encryption between ESP and computer. A USB keylogger cannot reveal the key, and a traffic sniffer can observe APDUs but not the PIV private key. Whether that is acceptable depends on what you are defending against.
Installing the macOS helper and flashing the firmware
The README's install section covers the red pill, meaning HID mode. It starts by creating a virtual environment and installing the helper's requirements, then generates a random pairing key and stores it, then stores your password.
python3 -m venv .venv
. .venv/bin/activate
pip install -r software/macos-helper/requirements.txt
pairing_key="$(openssl rand -hex 32)"
.venv/bin/python software/macos-helper/tinytouch_helper.py --set-pairing-key "$pairing_key"
.venv/bin/python software/macos-helper/tinytouch_helper.py --set-password 'your-password-here'After that, copy the example secrets header and edit it so the firmware carries the same pairing key bytes.
cp firmware/tiny_touch_keyboard/secrets.example.h firmware/tiny_touch_keyboard/secrets.hFlash `firmware/tiny_touch_keyboard/tiny_touch_keyboard.ino` with the Arduino IDE. The README lists the board settings used: USB CDC on boot enabled, and USB mode USB-OTG.
usb cdc on boot: enabled
usb mode: usb-otgFinally, run the helper. The README also mentions a launchd configuration for running it persistently, but the snippet is truncated, so treat launchd setup as something to work out from the repository files rather than from the README alone.
.venv/bin/python software/macos-helper/tinytouch_helper.pyThe unauthenticated UART is the limitation to take seriously
The README names the central weakness itself: all authentication happens inside the fingerprint sensor, and the sensor talks to the ESP over an unauthenticated UART. That link can be spoofed. The suggested countermeasures are physical, filling the inside of the device with black epoxy, or replacing the sensor with a more secure one. Neither is a firmware fix, and the README describes the epoxy approach as basic.
The attack table shows how far that reaches. Sensor UART spoofing applies in both modes. Flash dumping matters differently depending on configuration: with secure boot and flash encryption off, the HID shared key or the PIV key can be exposed; with them on, neither is exportable; with a secure element, the same holds. The README frames all of these as requiring physical access to both the device and your Mac, which is the honest scope of the risk.
There is a second class of limitation that is not about attackers. PIV mode does not cover general settings or keychain passwords, and the README says it probably will not work for remote SSH sessions. If your daily flow depends on those, HID mode is the only option, and HID mode types your real password. Choosing a mode is choosing which limitation you can live with.
How this differs from a commercial fingerprint keyboard
The obvious alternative is Apple's Magic Keyboard with Touch ID, which the README names at $149 and recommends for anyone whose threat model includes roommates, employers or classified material. The difference is not just price. A commercial keyboard integrates the sensor into a device Apple designs and secures end to end; tinyTouch is an ESP, a sensor and a UART link you assemble, where the sensor-to-ESP hop is unauthenticated and the ESP-to-computer hop differs by mode.
A second comparison is a software-only approach: macOS already supports PIV smart cards, and tinyTouch's PIV mode is essentially presenting a fingerprint-gated card to that existing stack. If you already own a PIV-capable token, tinyTouch's contribution is the fingerprint gate and the form factor, not the PIV protocol itself. That is worth knowing before you buy parts, because it tells you where the project's actual engineering sits.
The README's own framing is the clearest summary: risks are low to begin with because every listed attack requires physical access, and the question is whether physical access to your machine is something you can rule out.
Editorial conclusion
tinyTouch suits people who keep a Mac at a desk, are comfortable flashing firmware and running a Python helper, and accept that the sensor-to-ESP link is unauthenticated. It is the wrong choice for a company device, a shared or travelling machine, or anything holding classified material; the README itself points those users at a $149 Magic Keyboard instead. Before adopting it, decide which mode you need (HID types your real password, PIV gates a smart-card key), then read the security table in the README and the pairing-key and secrets.h steps in full.
Frequently asked questions
Does tinyTouch work for sudo and login on macOS?
Yes. The README shows PIV authentication of sudo and of the lockscreen, and HID mode covers sudo prompts plus keyboardless login. PIV mode works where macOS accepts smart cards, such as login and sudo through PAM, while HID mode types your password into whatever has focus.
What is the difference between tinyTouch HID mode and PIV/PAM mode?
HID mode makes the ESP act as a USB keyboard that types your real password after a fingerprint match, so it works almost everywhere including remote SSH. PIV mode makes the ESP act as a USB smart card whose private key operation is allowed only right after a fingerprint match, so your real password is never typed, but general settings and keychain passwords are not covered.
What hardware and software do I need to build a tinyTouch?
The install section uses a Python virtual environment, the helper requirements in software/macos-helper/requirements.txt, and an ESP board flashed with firmware/tiny_touch_keyboard/tiny_touch_keyboard.ino via the Arduino IDE, with USB CDC on boot enabled and USB mode set to USB-OTG. The README also links a YouTube build guide and a preassembled option at tinytouch.dev.
Is tinyTouch secure enough to use on a work laptop?
The README asks directly whether you are using a company device or protecting sensitive or classified information, and if the answer is yes it recommends the $149 Magic Keyboard instead. The stated reason is that the fingerprint sensor talks to the ESP over an unauthenticated UART that can be spoofed.
Community notes