[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92508":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":13,"stars30d":15,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":16,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":10,"pushedAt":10,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":13,"starSnapshotCount":13,"syncStatus":24,"lastSyncTime":25,"discoverSource":26},92508,"tinyTouch","ZimengXiong\u002FtinyTouch","ZimengXiong","authenticate, sudo, login with your fingerprint wire(less)ly without having to spend $149 at the cost of some security","https:\u002F\u002Ftinytouch.zimengxiong.com",null,"C",123,0,8,27,39.7,false,"main",true,[],"2026-07-22 04:02:06","\u003Cimg width=\"2304\" height=\"1152\" alt=\"tinyTouch (4)\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fec66ec7d-3e14-4292-8085-15374e349057\" \u002F>\n\n# tinytouch\n\nauthenticate, sudo, and log in with your fingerprint wire(less)ly without having\nto spend $149.\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fefede271-6d84-441d-919c-f5532f687c4e\n\nPIV authentication of sudo:\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fc197dd9c-81e5-4150-9793-d2e445651dfd\n\nPIV authentication of lockscreen (you know its PIV because it says PIN and not password in the entry field) (the typing is just the PIV PIN, which we bypass (since we gate by the fingerprint), read below to learn more about it)\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F88014cb2-34d2-4d63-8998-54f0561364eb\n\n\n\n## table of contents\n\n- [red pill or blue pill?](#red-pill-or-blue-pill)\n- [install](#install)\n  - [red pill](#red-pill)\n  - [blue pill](#blue-pill)\n- [hardware](#hardware)\n- [wiring](#wiring)\n- [notes](#notes)\n\n## red pill or blue pill?\n\nthere are two ways to use tinytouch on your computer: `HID` and `PIV\u002FPAM` mode. read about how they work in the sections below.\n\neach has its advantages, and we want to scare you a tiny bit so you actually do\nyour diligence and understand the security implications of such a device before\nyou decide whether you are willing to take on the risks:\n\n| features | HID | PIV\u002FPAM* |\n| -- | -- | -- |\n| keyboardless login | ✅ | ✅ |\n| sudo prompts | ✅ | ✅ |\n| apple TCC (privacy & security) | ✅ | ✅|\n| general settings | ✅ | ❌ |\n| keychain\u002Fapple passwords | ✅ | ❌ |\n| everywhere your password is accepted (remote SSH sessions, etc) | ✅ | depends, but probably not |\n\n| security | HID | PIV\u002FPAM* |\n| -- | -- | -- |\n| fingerprint sensor \u003C-> esp | 🔴 (unauth'ed UART) | 🔴 (unauth'ed UART) |\n| esp \u003C-> computer negotiation | 🟢 (shared-key mac\u002Fencryption) | 🔴 (plain usb ccid\u002Fapdu) |\n| authentication | 🔴 (password typed over hid) | 🟢 (piv challenge\u002Fresponse) |\n\n| attack | HID | PIV\u002FPAM* |\n| -- | -- | -- |\n| sensor uart spoofing^ | yes | yes |\n| wrong focused field | yes | no |\n| malicious password field | yes | no |\n| usb traffic sniffing | low impact (channel is encrypted\u002Fmac'ed) | can observe apdus, not piv private key |\n| usb keylogger | can reveal password | cannot reveal key |\n| usb command injection | reject bad macs\u002Freplays | device may receive apdus, but auth still needs fingerprint-gated key use |\n| flash dumping (secure boot\u002Fflash encryption off) | shared-key exposable | piv key exposable |\n| flash dumping (secure boot\u002Fflash encryption on) | shared-key non-exportable | piv key non-exportable |\n| flash dumping (with secure element) | shared key non-exportable | piv key non-exportable |\n\n*PIV\u002FPAM always uses HID to deliver the mandatory PIV PIN, which we do not use.\nauthorization is still gated by your fingerprint. the PIV PIN is not your\npassword, and is not considered sensitive in our scenario.\n\n^this is the major security issue with this device. since all authentication\nhappens inside the fingerprint sensor, and the sensor communicates with the esp\nover unauthenticated uart, it can be easily spoofed. basic countermeasures\ninvolve filling the insides of the device with black epoxy. a more proper fix\nwould be upgrading to a more secure fingerprint sensor.\n\n### so... which pill, if any?\nthis depends on:\n\n1. your security tolerance\n2. your environment\n3. current\u002Ffuture criminal background\n4. family\u002Froommate relations\n5. technical skill set of family members\u002Froommates\n\nrisks are low to begin with since every attack here requires *physical access* to\nboth the device and your mac.\n\nso ask yourself: will your device ever leave your desk? can your roommates\nperform a flash dump in half an hour? how about your family members? do they have\nanything against you that would create a motive? are you wanted by any government\nagency? are you protecting sensitive or classified information? are you using a\ncompany device? would you be personally implicated if you leaked company secrets?\n\nif the answer is yes to any of the above questions, i think the magic keyboard presents an excellent value at $149 and is worth the added security.\n\nif the answer is no, chances are you will be fine with a slightly insecure method\nof authentication. personally, i am happy with the red pill and love the\nconvenience of having it work everywhere.\n\n### hid mode\n\nin hid mode, the esp acts like a usb keyboard.\n\nthe mac helper keeps your real password encrypted and stored on your mac. this\nway, an attacker cannot extract your password from the esp alone. the esp keeps a\nshared pairing key. after a fingerprint match, the esp sends a signed request to\nthe helper, the helper checks it, encrypts the password for that one request, and\nsends it back. the esp decrypts it in ram, types it, then wipes it.\n\nthis is why it works almost everywhere. it is also why it is scary: the final\nstep is still your real password being typed into whatever has focus.\n\nto make it less bad, the esp never stores the password. requests use a nonce and\nmac so old requests cannot just be replayed, and the helper only sends back an\nencrypted one-time response. the password only exists on the esp briefly in ram.\n\n### piv mode\n\nin piv mode, the esp acts like a usb smart card.\n\nmacos sends normal piv commands over ccid. when macos needs authentication, it\nasks the card to use the piv private key. the esp only allows that key operation\nright after a fingerprint match.\n\nmacos also expects a piv pin, so the firmware has a tiny hid side path that types\nthe dummy pin `000000`. that pin is not your mac password. it is just there to\nget through the macos piv prompt while the real authorization is the fingerprint\ngate around the piv key.\n\nthis avoids typing your real password, but only works where macos accepts smart\ncards, like login and `sudo` with pam.\n\n## install\n\n### red pill\nuse this if you just want the thing to type your password.\n\n```sh\npython3 -m venv .venv\n. .venv\u002Fbin\u002Factivate\npip install -r software\u002Fmacos-helper\u002Frequirements.txt\n\npairing_key=\"$(openssl rand -hex 32)\"\n.venv\u002Fbin\u002Fpython software\u002Fmacos-helper\u002Ftinytouch_helper.py --set-pairing-key \"$pairing_key\"\n.venv\u002Fbin\u002Fpython software\u002Fmacos-helper\u002Ftinytouch_helper.py --set-password 'your-password-here'\n\ncp firmware\u002Ftiny_touch_keyboard\u002Fsecrets.example.h firmware\u002Ftiny_touch_keyboard\u002Fsecrets.h\n```\n\nedit `firmware\u002Ftiny_touch_keyboard\u002Fsecrets.h` so it contains the same pairing\nkey bytes, then flash `firmware\u002Ftiny_touch_keyboard\u002Ftiny_touch_keyboard.ino`\nwith arduino ide.\n\nboard settings used here:\n\n```text\nusb cdc on boot: enabled\nusb mode: usb-otg\n```\n\nrun the helper:\n\n```sh\n.venv\u002Fbin\u002Fpython software\u002Fmacos-helper\u002Ftinytouch_helper.py\n```\n\nfor launchd, edit paths in\n`software\u002Fmacos-helper\u002Flaunchd\u002Fcom.tinytouch.helper.plist`, then copy it to\n`~\u002FLibrary\u002FLaunchAgents\u002F`.\n\n### blue pill\n\nuse this if you want the current better path. it exposes piv over ccid, plus hid\nonly for the dummy pin `000000`.\n\n`main\u002Fsecrets.h` needs the piv certs and private keys for slots `9a` and `9d`.\n\ngenerate test keys:\n\n```sh\ncd firmware\u002Ftiny_touch_smartcard\nopenssl req -newkey rsa:2048 -nodes -keyout piv_key_9a.pem -x509 -days 3650 -out piv_cert_9a.pem -subj \"\u002FCN=tinytouch piv auth\u002F\"\nopenssl req -newkey rsa:2048 -nodes -keyout piv_key_9d.pem -x509 -days 3650 -out piv_cert_9d.pem -subj \"\u002FCN=tinytouch piv key management\u002F\"\ncp main\u002Fsecrets.example.h main\u002Fsecrets.h\n```\n\nthen paste:\n\n- `piv_cert_9a.pem` into `PIV_CERT_9A_PEM`\n- `piv_key_9a.pem` into `PIV_PRIVATE_KEY_9A_PEM`\n- `piv_cert_9d.pem` into `PIV_CERT_9D_PEM`\n- `piv_key_9d.pem` into `PIV_PRIVATE_KEY_9D_PEM`\n\nbuild and flash:\n\n```sh\nidf.py set-target esp32s3\nidf.py build\nidf.py -p \u002Fdev\u002Fcu.usbmodem101 flash\n```\n\nafter flashing:\n\n```sh\nsystem_profiler SPSmartCardsDataType\nsc_auth identities\nsudo sc_auth pair -u \"$USER\" -h \u003Cauth-cert-hash>\n```\n\nto test sudo:\n\n```sh\nsudo -k\nsudo -v\n```\n\nwhen macos asks for the pin, touch the sensor.\n\n## hardware\n\n| part | used here | notes |\n| -- | -- | -- |\n| microcontroller | seeed studio esp32-s3 | needs native usb and hardware uart. secure boot + flash encryption strongly recommended |\n| fingerprint sensor | zw101-style uart sensor | uses the common `0xef01` packet protocol |\n| computer | macos | hid mode needs the helper. piv\u002Fpam mode needs macos smart card support |\n| case | printed top\u002Fbottom stl | `hardware\u002Fcase\u002Fcase_top.stl` and `hardware\u002Fcase\u002Fcase_bottom.stl` |\n| wiring\u002Fsolder\u002Fetc | misc | whatever your build needs |\n\nother esp32-s3 boards should work if the usb and uart pins are available. other\nfingerprint sensors may work if they speak the same uart protocol. other\nmicrocontroller families can work, but are not currently supported.\n\n## wiring\n\nthe fingerprint sensor connects over uart to pins 6 and 7 for tx and rx.\n\nthe interrupt pin can be connected anywhere. in firmware, it is connected to pin\n1.\n\n## notes\n\ndo not commit:\n\n- `firmware\u002Ftiny_touch_keyboard\u002Fsecrets.h`\n- `firmware\u002Ftiny_touch_smartcard\u002Fmain\u002Fsecrets.h`\n\n[cad](https:\u002F\u002Fcad.onshape.com\u002Fdocuments\u002Fd0e6bb7977e6171d4e4a5086\u002Fw\u002F1ded27ad6c634fd1fdaf26d0\u002Fe\u002Faca67210e400490a08d0b29a?renderMode=0&uiState=6a4c1df32e292f12144a65fe). if you make changes, please make them open source as well.\n\n## bonus images\n\n\u003Cimg width=\"2261\" height=\"1347\" alt=\"render2\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F5f107d74-d651-4e3b-90ed-f37dcaa026ac\" \u002F>\n\u003Cimg width=\"1238\" height=\"901\" alt=\"cross\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F6a7062d9-ec56-4aac-adad-00d888e7d486\" \u002F>\n\u003Cimg width=\"1280\" height=\"957\" alt=\"tinyTouch\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fad66c9b3-5823-44d3-bd73-bba64f2e60ab\" \u002F>\n","tinyTouch 是一个基于 ESP 微控制器的低成本指纹认证硬件方案，用于替代高价生物识别设备（如 $149 的 Touch ID 外设），实现无线\u002F有线方式的系统登录、sudo 权限提升和 PIV 认证。核心功能包括 HID 模式（模拟键盘输入密码）与 PIV\u002FPAM 模式（基于智能卡标准的挑战-响应认证），支持 Linux 和 macOS 系统集成。项目采用 C 语言开发固件，强调在有限安全预算下平衡可用性与风险控制，适合个人开发者、隐私敏感用户及嵌入式安全实验场景使用。",2,"2026-07-09 02:30:12","CREATED_QUERY"]