Hackintosh Touch-ID, Fingerprint authentication for macOS

A libusb-based capture pipeline and NBIS matcher bringing Fingerprint sensors fingerprint authentication to macOS on unsupported (Hackintosh) hardware — lock screen unlock and System Settings authentication prompts, driven by a real fingerprint sensor instead of a password.

• Current version: v2.0.2
• Current Menubar app version: v1.4.1
• If you want to see the changes that happen to the code, please head into the Change log with This link
• Please refrence the Table that has the Supported sensors to make sure you can use this tool. This link should take you there
• link to the GitHub page

---

Overview

This project ports the USB capture protocol for supported fingerprint sensors to a standalone macOS C code, and pairs it with NIST's NBIS fingerprint matching suite (mindtct for minutiae extraction, bozorth3 for matching) to provide working fingerprint authentication on Hackintosh hardware that shipped with this sensor but has no native macOS driver support.

It is not a kernel extension or a libfprint port. It runs as a small background daemon that watches for authentication prompts using the Accessibility APIs, captures a fingerprint swipe on demand, matches it against enrolled templates, and — on a match — types the stored password into the prompt automatically.

Supported Sensors

This Table will have the currently Supported Sensors or sensors in Development or Planned Support. Please keep your expectations in check, this is a hobby project.

Sensor Name / Model	VID	PID	Support status	Supported Features
Validity VFS5011	138A	0018	Supported & Confirmed working on a DV6-7070ex (Thanks Hackintosh-user!)	Fully Supported.
Synaptics Metallica MIS	06cb	009a	Supported & Confirmed working on a X1C6 (Thanks u/p0cketl1nt!)	Fully Supported.
Prometheus 97	138A	0097	Supported & Confirmed working on a X1C5 (Thanks u/p0cketl1nt!)	Fully Supported.
Prometheus 9d	138A	009d	Supported & but needs testing	Needs testing.
UPEK TouchStrip	147e	2016	Developing & actively Testing (thanks u/Cold_Salamander7764!)	Features in development.
Synaptics VFS7552	138A	0092	Developing & actively Testing (thanks priyashgawande-commits!)	Features in development.
ELAN	04f3	0c6e	Developing, capture-only test on the elan-0c6e branch (thanks @s17765152890-gif!)	Features in development.
EGIS ETU905A80-E	1c7a	05a1	Planned support (requested in issue #15)	Planned.
ELAN WBF	04f3	0c4c	Planned support (requested in issue #16)	Planned.

• Please Keep in Mind that some sensor names are too long to fit in the table the VID:PID for each currently or planned sensor will be in the table and regardless the client itself checks if your sensor is supported.
• Please also keep in mind that when you want to open a Github Issue that the sensor VID:PID is Required. I won't be able to help if you open an issue and say my sensor doesn't work.

Features

Please Keep in mind some features for other sensors may be broken or buggy this project isnt maintained by a full Dev-Ops team. So i would love if you encounter any issues to Open a Github Issue with as much information provided in the issue so i can work on the fix. Thanks! :)

Features with Hackintosh Touch-ID:

• Fingerprint capture and matching entirely native to macOS, no Linux kernel driver or libfprint dependency at runtime
• Multi-finger enrollment (multiple fingers, best-match-wins verification)
• Lock screen unlock via fingerprint swipe
• System Settings / System Preferences authentication sheet ("padlock") unlock via fingerprint swipe
• Authentication for Finder password prompts.
• Works with browsers (Currently confirmed working with Orion but I'm not sure for others)
• Passwords.app Padlock unlock via fingerprint swipe
• Keychain Access "confidential information" consent prompt unlock via fingerprint swipe
• Enrolled templates and the stored password are kept on a dedicated, encrypted APFS volume, not in plaintext on the boot volume
• Self-elevating daemon with a narrowly scoped, single-purpose sudoers rule rather than a blanket NOPASSWD grant
• Interactive terminal client (hack-touchid_client) for enrollment, verification, and one-command deployment of the background daemon
• Optional Menu bar Application for disabling, enabling, Restarting the Daemon + sends notifications when authentication is ready if Sensor light is too dim / too slow
• Growing supported sensor list with testers.
• Auto Updating Client that auto extracts, runs chmod, re-launches new update, and deletes the old files
• [D] Diagnose option for debugging issues, and opening issues on github
• Multi operating system (macOS) support on one APFS encrypted volume
• Multiple Launch-arguments for easier access like --q or --diag-pid, there's more Read about them here
• macOS Tahoe only: Swipe to lock with the menubar app!

Menu Bar Companion App

Hackintosh-TouchID-Menubar/ contains the menu bar app that surfaces the daemon's auth events as real notifications, useful since the sensor's LED can be too dim to notice on its own. It is installed by Deploy.

• Notifies you the moment the daemon wants a swipe ("Swipe to authenticate! 🫆"), then whether it succeeded or failed
• One-click toggle to pause/resume fingerprint auth without touching Terminal
• Registers itself as a login item automatically on first launch (macOS 14+, via SMAppService, no manual LaunchAgent setup needed)
• "About hackintosh Touch-ID" menu item with a short project summary and a link back here

Installing

A pre-compiled, ad-hoc signed x86_64 app is committed in shared/menubar/build/. The client installs it for you:

• [3] Deploy copies it to /Applications, starts it, and checks that notifications and the login item are set up. If macOS shows a notification prompt, click Allow. If notifications were denied or the login item needs approval, the client opens the right System Settings pane.
• [M] Install / Repair Menu Bar App runs the same step on its own.
• The app is only replaced when its binary differs from the installed one.
• [X] Uninstall removes the app and its login item.

If you prefer to compile it yourself:

cd Hackintosh-TouchID-Menubar
chmod +x build_menubar_app.sh
./build_menubar_app.sh

This writes the app to shared/menubar/build/Hackintosh Touch-ID.app. Requires Xcode Command Line Tools (xcode-select --install) for swiftc and iconutil. No other dependencies. And it needs macOS 14 Sonoma and later, like the Daemon, Older versions may work but I don't know if they do you are on your own if you are on monterey and older.

IMPORTANT NOTE: the Swipe to Lock feature is ment and will always be for macOS 26 Tahoe only.

The client clears the quarantine flag when it installs the app. If you copy the app by hand, the first launch is blocked by Gatekeeper since it is ad-hoc signed, not notarized: right-click the app, Open, Open again, or run xattr -cr "Hackintosh Touch-ID.app" once.

Wiring it to the daemon

The menu bar app talks to the daemon over macOS distributed notifications — the same mechanism the daemon already uses for its own screenIsLocked/screenIsUnlocked handling. The daemon needs a small patch to actually send those events; see it's own README

for the exact 6-line diff against vfs5011_daemon.c. Without the patch, the app runs standalone and just never receives anything — harmless, but silent.

Known limitations:

• Pause/resume is global — disabling fingerprint auth pauses it for every recognized prompt at once (lock screen, padlock, Finder, pkg installer, Time Machine, Apple ID's local password step), not just one surface.
• Not notarized (see Gatekeeper note above).
• Pre-Login is not a simple workaround. Could takes months or years to fix.
• Requires you to go into System settings -> notfifications -> show Previews: set to Always otherwise it will show up but wont tell you if its ready to swipe or a failed the swipe test.

Requirements

• macOS 14 Sonoma and later (older versions may work, but I offer 0 support for them)
• macOS 15 Sequoia and later is the recommended version for Hackintosh Touch-ID
• macOS 26 Tahoe for "swipe/touch to lock"
• Xcode Command Line Tools (xcode-select --install)
• Homebrew or MacPorts (the build scripts and the client look in both; with MacPorts the packages below are libusb, openssl3, innoextract and 7zip, installed with sudo port install)
• Dependencies depend on your sensor. prep_and_build.sh installs only what yours needs (run ./prep_and_build.sh --list to see it):
  • libusb (brew install libusb), every sensor
  • openssl@3 (brew install openssl@3), Metallica MIS and Prometheus 97 only [will be Deprecated on Novemeber 1st 2026 but should work fine still]
  • innoextract (brew install innoextract), Metallica MIS and Prometheus 97 only
  • sevenzip (brew install sevenzip), Synaptics VFS7552 only
• Accessibility permission granted to the daemon (handled automatically by the deploy script, see below)
• OpenCore v1.0.6 or later (For maximum Security | Release or Debug are fine) but on older versions of OpenCore will work but I don't support it. You are on your own if you use v1.0.5 or older.

Building

git clone https://github.com/hackintosh-user/hack-touchid.git
cd hack-touchid
chmod +x prep_and_build.sh
./prep_and_build.sh                    # detects your sensor over USB
./prep_and_build.sh --sensor vfs5011   # or name it: vfs5011, upek, metallica, or a VID:PID

Only the dependencies for that sensor are installed and built. Add --yes to skip the install prompt or --no-install to only report what is missing.

This produces the needed binaries for running the client and each sensor's Daemon + other needed files.

prep_and_build.sh also compiles the System Settings preference pane into shared/pane/build/ (add --no-pane to skip it). It is never installed automatically: use [I] Install Preference Pane in the client, or answer Y to the question at the end of [3] Deploy. The client installs the pre-compiled bundle from shared/pane/build/.

Repository layout

prep_and_build.sh        start here: installs deps, builds everything
hack_touchid_client.c    the client (menu + headless commands), binary: ./hack-touchid
fpbootd-install.sh       opt-in pre-login daemon install
scripts/                 build scripts (build.sh, build_client.sh, build_daemon.sh,
                         build_metallica_mis.sh) and ht_env.sh, the shared build helpers
shared/sen/              supported_sensors.h, fp_types.h, ht_sensor_tool.c, the matcher
shared/access/           accessibility grant script, ax_probe.c
shared/pane/source/      preference pane source (Swift, Info.plist, build_prefpane.sh)
shared/pane/build/       pre-compiled HackTouchID.prefPane that ships with the repo
vfs5011/                 VFS5011 daemon, protocol, menu bar IPC, agent installer
vol/                     encrypted template volume scripts (setup, mount, unmount, store password)
metallica/               Metallica MIS code, sensor stubs, and tests/ (mmis_*_test.c)
upek/                    UPEK code
NBIS/                    fingerprint matching library
tests/                   matcher unit tests
Hackintosh-TouchID-Menubar/   menu bar app

The binaries (hack-touchid, vfs5011_daemon, metallica_mis_daemon) are still written to the repo root.

Usage

WARINING 1: On macOS 13 Ventura And older you will be shown a message that clearly states there is 0 Support for any OS older than macOS 14 Sonoma and later you are on your own for any issues that may arise on this version of macOS.

WARNING 2: Same goes for the OpenCore Boot loader: the minimum version is OpenCore v1.0.6 or later. v1.0.5 and older are officially not supported. You are on your own if you encounter any issues on v1.0.5 or older.

Run the client with this command:

sudo ./hack-touchid

• Upon running this the client runs its startup checks, then clears the screen and draws the menu (if a check prints a warning or an error, the screen is left alone so you can read it). For the plain startup, with the banner first and no clearing, use:

  sudo ./hack-touchid --q

  Or:

  sudo ./hack-touchid --quiet

• After the first launch, the Client will add itself to $PATH That way you can simply launch a fresh terminal without Cd'ing into the folder where the repo is located and simply run:

sudo hack-touchid

or with its launch-arguments!

Then, you should be greeted with this interactive CLI menu for Hackintosh Touch-ID client

Actions
[1] Enroll a Finger
[2] Verify Fingerprint Match [Score / x ]
[3] Deploy Authentication Services
[C] View Fingerprint (capture preview, nothing saved)
[P] (ONLY FOR METALLICA MIS & PROMETHEUS 97 SENSORS) Pair
[U] (ONLY FOR UPEK 147e:2016) capture .pgm
[B] Capture (experimental, Only for Metallica MIS & Prometheus 97 Sensors)
[FP] Fpbootd, Pre-Login Auth (coming soon)

Utilities
[D] Diagnose (generate a report for troubleshooting)
[S] Settings
[A] About
[X] Uninstall
[Q] Quit

• Enroll a Finger — captures several swipes of a finger and stores them as a named template on the encrypted volume. Repeat for as many fingers as needed; enrollment is capped and uses best-match-wins verification across all enrolled fingers.
• Verify Fingerprint Match — a standalone test of the capture and matching pipeline, independent of the daemon, useful for confirming the sensor and templates are working before deploying.
• Deploy Authentication Services — rebuilds the daemon from source, installs it as a per-user LaunchAgent, re-signs it and regenerates its Accessibility permission grant, and installs a narrowly scoped sudoers rule so the daemon can self-elevate when it needs root access to the USB device. This step is re-run every time you deploy, so the daemon is never left running a stale build.

Once deployed, the daemon runs continuously in the background. At the lock screen, or when a System Settings authentication sheet appears, it prompts for a fingerprint swipe and, on a match, types the stored password automatically.

Launch Arguments

NOTICE This list is set to change accordingly, there will be new launch-arguments which I will Mention in the Changelog!! Always keep up to date about these launch-args as they could heavily benefit your use-case.

• -h, --help: Shows the list of launch arguments and exits. Needs no password. The same list is shown by [H] in the menu.
• -v, --version: Shows the client version, build, branch and the installed daemon, FPOV and Fpbootd versions, then exits. Needs no password.
• --q: plain startup: banner first, the startup checks stay on screen and the screen is not cleared afterwards
• --quiet: same as --q.
• --deploy-agent: Runs the [3] Deploy authentication services without entering the client. This is also used when the Menubar detects the Daemon isn't installed / after a macOS update
• --diag-pid: Runs the [D] Diagnostic steps but without launching the client.
• --check-updates: checks for updates without launching the client. If there is one, shows the [A] Show changelog / [Y] Download and install / [N] Cancel prompt.
• --menu-updater: checks for updates and installs one right away, with no prompts. The menu bar app's "Update Client" notification button runs this in a terminal.
• --debug: Makes the client print every log for better debugging.
• --debug-full: Same as --debug, but never truncates large payloads.
• --list-records: Read-only. Lists the storage, users and enrolled fingers stored on the sensor, plus database size and free space.
• --wipe-records: Deletes all enrolled prints stored on the sensor. Destructive, cannot be undone.
• --enroll-test: Metallica MIS and Prometheus 97 only. Calibrates, enrolls one finger on the sensor and exits. Tester tool, run it together with --debug.
• --verify-test: Metallica MIS and Prometheus 97 only. Calibrates, asks for one touch, matches it against the print saved by --enroll-test and exits. Run it together with --debug.
• --force-pair: Experimental. Tries to pair the sensor by writing its identity partitions. A sensor that is already paired refuses this (error 0x0404), so use the two host flags below instead.
• --host-product "<name>": Overrides the product name HTID uses to derive the pairing key. Use the laptop's real value, not the spoofed Mac one. Use together with --host-serial. Applies to this run only, nothing is saved.
• --host-serial "<serial>": Overrides the serial HTID uses to derive the pairing key. Use the laptop's real value. Use together with --host-product. Applies to this run only, nothing is saved.
• --cli: Skips the preference pane question and starts the CLI client.
• --pane: Opens the installed preference pane instead of the CLI client.
• --list-fingers: Prints the enrolled prints as JSON and exits. Used by the Settings pane.
• --rename-finger: Used with --finger-id <ID> --finger-name "<name>". Renames a print and exits.
• --delete-finger: Used with --finger-id <ID>. Removes a print and exits. Not available on Metallica MIS or Prometheus 97.
• --mmis-connect: Metallica MIS and Prometheus 97 only. Opens a session with the sensor and reports the result. Used by the Settings pane.
• --mmis-calibrate: Metallica MIS and Prometheus 97 only. Runs the calibration and reports the result. Used by the Settings pane.
• --fpbootd-daemon: Runs the client as the Fpbootd pre-login socket server. Started by the Fpbootd install, you should not need to run it yourself.

How it works

• Capture: the raw USB protocol (initialization sequence, swipe capture, image reassembly) is implemented directly against libusb, without going through any Linux-specific driver stack.
• Matching: captured swipes are run through NIST's mindtct for minutiae extraction and bozorth3 for match scoring, both compiled directly into the client and daemon.
• Storage: enrolled templates and the authentication password live on a dedicated, encrypted APFS volume rather than in a plaintext file on the boot volume. The passphrase for that volume is stored in the System keychain.(Not seen by finder or the user)
• Detection: the daemon polls the system's focused UI element via the Accessibility APIs to recognize when a lock screen or System Settings password field is active, rather than hooking or patching any system process.
• Privilege model: the daemon runs as the console user and only escalates to root, via a narrowly scoped sudoers rule, for the specific operations that require it (accessing the USB device). It is not installed as a system-wide LaunchDaemon.

Limitations

These are limitations that are either not possible to fix or currently Planned / Fixes for later. As before, please keep your expectations in check, this is a hobby project maintained by one person, not a Dev-Ops Development team.

List as goes:

• macOS only. This is not a libfprint driver and is not intended to run on Linux — if you're on Linux with this sensor, use the existing open-source libfprint driver directly instead (see Acknowledgments).
• Targets macOS 14 Sonoma and later only; the client prints a warning if run on an older Darwin version.
• No PAM module exists for sudo in a terminal. An Accessibility-based approach for sudo prompts was prototyped during development and intentionally removed to keep scope limited to lock screen and System Settings authentication. (there are still plans to attempt implementing this. But unknown if Modern macOS allows this type of access within the user space-range)
• Ad hoc code signing is used for the daemon binary and its Accessibility grant, both regenerated on every deploy. There is no notarization or Developer ID signing.
• a Cold boot sign in is not supported:

Explanation:

• Modern macOS Does not allow this level of access required to implement such thing into the Login window before the user has logged in. As such this is only a For now impossible, could happen one day but could take months or even years of active development towards this feat of macOS engineering.

Acknowledgments

This project would not exist without the following prior work:

• NBIS (mindtct, bozorth3) — the fingerprint minutiae extraction and matching engine used in this project is NIST's public NBIS distribution. Developed by employees of the U.S. federal government in the course of their official duties and, per 17 U.S.C. section 105, not subject to copyright protection in the United States. https://www.nist.gov/services-resources/software/nist-biometric-image-software-nbis

• VFS5011 capture protocol — the USB initialization and capture sequence for the VFS5011 sensor was originally implemented as a libfprint driver by Arseniy Lartsev and AceLan Kao (Canonical), licensed under the GNU Lesser General Public License v2.1. This project's macOS capture pipeline was independently written in C, informed by that original driver's protocol logic. https://github.com/ars3niy/fprint_vfs5011

If you are on Linux and have a Fingerprint sensor, the libfprint driver linked above is the right tool to use directly — this project exists specifically to bring the same capability to macOS, where no equivalent driver exists.

Credits

• @Hackintosh-user: Main Lead developer
• @ilikehackintosh: Documentation handler
• u/p0cketl1nt: Main tester for Metallica MIS 06cb:009a & Prometheus 97 138a:0097 (Massive thank you!)
• u/Cold_Salamander7764: Main tester for UPEK touch-Strip 147e:2016 (Massive thank you!)
• @priyashgawande-commits: Main tester for Synaptics VFS7552 (Massive thank you!)
• @s17765152890-gif: Contributor, ELAN 04f3:0c6e capture-only test and client dispatch (PR #12, Massive thank you!)

License

Released under the BSD 3-Clause License. See LICENSE for the full text, including third-party attribution for NBIS and the VFS5011 capture protocol.