{"id":13760662,"url":"https://github.com/jorgelbg/pinentry-touchid","last_synced_at":"2025-10-07T03:29:55.827Z","repository":{"id":37696607,"uuid":"383950914","full_name":"jorgelbg/pinentry-touchid","owner":"jorgelbg","description":"Custom GPG pinentry program for macOS that allows using Touch ID for fetching the password from the macOS keychain.","archived":false,"fork":false,"pushed_at":"2023-10-18T03:39:53.000Z","size":81,"stargazers_count":632,"open_issues_count":24,"forks_count":29,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-07-31T22:47:17.782Z","etag":null,"topics":["gpg","hacktoberfest","keychain","macos","pinentry","pinentry-mac","touchid"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jorgelbg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":["jorgelbg"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2021-07-07T23:47:27.000Z","updated_at":"2025-07-26T13:27:11.000Z","dependencies_parsed_at":"2024-01-15T03:57:14.732Z","dependency_job_id":"5224e35c-ee0e-4610-935a-294c1a5defc0","html_url":"https://github.com/jorgelbg/pinentry-touchid","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/jorgelbg/pinentry-touchid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgelbg%2Fpinentry-touchid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgelbg%2Fpinentry-touchid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgelbg%2Fpinentry-touchid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgelbg%2Fpinentry-touchid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jorgelbg","download_url":"https://codeload.github.com/jorgelbg/pinentry-touchid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgelbg%2Fpinentry-touchid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278715508,"owners_count":26033296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gpg","hacktoberfest","keychain","macos","pinentry","pinentry-mac","touchid"],"created_at":"2024-08-03T13:01:15.781Z","updated_at":"2025-10-07T03:29:55.799Z","avatar_url":"https://github.com/jorgelbg.png","language":"Go","funding_links":["https://github.com/sponsors/jorgelbg"],"categories":["Go"],"sub_categories":[],"readme":"# pinentry-touchid\n\n\u003cp align=\"center\"\u003e\n    \u003cimg class=\"center\" src=\"https://user-images.githubusercontent.com/1291846/127916161-5803ca98-c0a2-4d1f-8479-860f4d7edc98.png\" width=\"300\" alt=\"pinentry-touchid logo\"/\u003e\n\u003c/p\u003e\n\nCustom GPG pinentry program for macOS that allows using Touch ID for fetching the password from the\nmacOS keychain.\n\n\u003e Macbook Pro devices without Touch ID are currently not supported. These devices \u003e lack a Touch ID\n\u003e sensor and while the alternative offered by Apple is to use (if available) an Apple Watch, this\n\u003e feature it is not yet implemented.\n\n## See it in action\n\n ![pinentry-touchid in action with gopass](https://user-images.githubusercontent.com/1291846/128176593-271ac649-5207-41f2-83da-3fb3d37ede9c.gif)\n\n\n## How does it work\n\nThis program interacts with the `gpg-agent` for providing a password, using the following rules:\n\n- If the password entry for the given key cannot be found in the Keychain we fallback to the\n  `pinentry-mac` program to get the password. We recommend preventing `pinentry-mac` from storing the\n  password: uncheck the \u003ckbd\u003eSave in keychain\u003c/kbd\u003e checkbox in the dialog.\n\n- If a password entry is found the user will be shown the Touch ID dialog and upon successful\n  authentication the password stored from the keychain will be returned to the gpg-agent.\n\n- If a password entry is found but is not \"owned\" by the `pinentry-touchid` program after the\n  successful authentication with Touch ID, a normal password will be shown. This is an extra step\n  enforced by the macOS keychain. In this dialog click \u003ckbd\u003eAlways allow\u003c/kbd\u003e after entering the\n  password. This will allow `pinentry-touchid` to access the password entry without the need to type\n  the additional password, but still, the access to the password will be guarded by Touch ID.\n\n## Installation\n\n### Prerequisites\n\n* [gnupg](https://formulae.brew.sh/formula/gnupg)\n* [pinentry-mac](https://github.com/GPGTools/pinentry-mac)\n\n\nIf you have already installed GPG, make sure that executing `pinentry` shows a GUI prompt by running\nthe following command:\n\n```sh\n$ echo GETPIN | pinentry\n```\n\nYou should get the dialog from [pinentry-mac](https://github.com/GPGTools/pinentry-mac). If that is not the case you can install it though Homebrew:\n\n```sh\n$ brew install pinentry-mac\n```\n\nYou can overwrite the `pinentry` alias to point to `pinentry-mac`:\n\n```sh\n$ alias pinentry='pinentry-mac'\n```\n\n_Then try again whether you see a GUI prompt._\n\nIn some cases aliasing `pinentry` to `pinentry-mac` is not enough because `gpgconf` returns the\nabsolute path that points to the `$HOMEBREW_PREFIX/opt` path. In that case you can execute the\nfollowing command to automatically fix the symlink.\n\n```sh\n$ pinentry-touchid -fix\n```\n\n### Homebrew\n\n\nAs part of our release process we keep an updated Homebrew Formula. To install `pinentry-touchid` using\nHomebrew execute the following commands:\n\n```sh\n$ brew tap jorgelbg/tap\n$ brew install pinentry-touchid\n```\n\nHomebrew will print the next steps, which will look similar to:\n\n```\n==\u003e Caveats\n➡️  Ensure that pinentry-mac is the default pinentry program:\n      /usr/local/bin/pinentry-touchid -fix\n\n✅ Add the following line to your ~/.gnupg/gpg-agent.conf file:\n      pinentry-program /usr/local/opt/pinentry-touchid/bin/pinentry-touchid\n\n🔄  Then reload your gpg-agent:\n      gpg-connect-agent reloadagent /bye\n\n🔑  Run the following command to disable \"Save in Keychain\" in pinentry-mac:\n    defaults write org.gpgtools.common DisableKeychain -bool yes\n\n⛔️  If you are upgrading from a previous version, you will be asked to give\n    access again to the keychain entry. Click \"Always Allow\" after the\n    Touch ID verification to prevent this dialog from showing.\n==\u003e Summary\n🍺  /usr/local/Cellar/pinentry-touchid/0.0.2: 4 files, 2.2MB, built in 10 seconds\n```\n\n### Manual installation\n\n- Download the `pinentry-touchid` binary from our Releases page\n\n- Configure the `gpg-agent` to use `pinentry-touchid` as its pinentry program. Add or replace the\n  following line to your gpg agent configuration in: `~/.gnupg/gpg-agent.conf`:\n\n```sh\n$ pinentry-program /usr/local/bin/pinentry-touchid\n```\n\nYou can replace `/usr/local/bin/pinentry-touchid` with the path where the binary was stored.\n\nMake sure that the `pinentry-mac` is configured to be the default `pinentry` program (will be used\nas fallback). You can check which PIN program will be used by default by executing:\n\n```sh\n$ pinentry-touchid -check\n```\n\nIf any error is reported `pinentry-touchid` can automatically fix the symlink for you:\n```sh\n$ pinentry-touchid -fix\n```\n\n## Manually add your GPG key password to the Keychain\n\nFirst, ensure pinentry-mac is already using the Keychain:\n\n```sh\n$ security find-generic-password -s 'GnuPG'\n```\n\nYou should get a big list of attributes.\nIf you get an error, such as the following, it means pinentry-mac is not configured to use the Keychain:\n\n```\nsecurity: SecKeychainSearchCopyNext: The specified item could not be found in the keychain.\n```\n\nIf you do not see this error, skip ahead to [Configuring pinentry-touchid](#configuring-pinentry-touchid).\n\n### Configuring pinentry-mac\n\nBefore configuring pinentry-touchid, you should configure pinentry-mac to use the Keychain at least once:\n\n```sh\n$ defaults write org.gpgtools.common UseKeychain -bool yes\n```\n\nNote that there are two defaults which are the reverse of each other.\nThis one, `UseKeychain`, should be set to `yes` or `true`.\n\nEnsure the `pinentry-program` entry in your `~/.gnupg/gpg-agent.conf` points to pinentry-mac, then restart the GPG Agent:\n\n```sh\n$ gpgconf --kill gpg-agent\n```\n\nUsing gpg should then use pinentry-mac to provide a GUI prompt for your GPG passphrase:\n\n```sh\n$ echo 1234 | gpg -as -\n```\n\nMake sure you check the \"Save in Keychain\" box on the prompt.\nYou may then get a second prompt, this time for your login password, to authorize pinentry-mac to create and use the Keychain entry to store your GPG passphrase.\nIf so, use \"Always Allow\" to avoid future prompts.\n\nYou should now be able to see the new Keychain entry via the same command as before:\n\n```sh\n$ security find-generic-password -s 'GnuPG'\n```\n\nContinue on to the next section to replace this password prompt with a TouchID prompt.\n\n### Configuring pinentry-touchid\n\nOnce your Keychain is configured correctly, you can update your `gpg-agent.conf` with the correct path for `pinentry-program` pointing to the full path to `pinentry-touchid`.\nRemember to restart the GPG Agent each time you make a change to this configuration file:\n\n```sh\n$ gpgconf --kill gpg-agent\n```\n\nWe recommend disabling the option to store the password in the macOS Keychain for the default\npinentry-mac program with the following option:\n\n```sh\n$ defaults write org.gpgtools.common DisableKeychain -bool yes\n```\n\nThis will allow `pinentry-touchid` to create and automatically take ownership of the entry in the\nKeychain. If an entry already exists in the Keychain you need to always allow `pinentry-touchid` to\naccess the existing entry.\n\n## Disclaimer\n\nThis project does not store the password/pin in the [Secure\nEnclave](https://support.apple.com/en-gb/guide/security/sec59b0b31ff/web) of your device, instead\nuses the normal Keychain entry from\n[pinentry-mac](https://github.com/GPGTools/pinentry/tree/master/macosx) if available, or creates a\nnew one.\n\n## Tested on\n\nI've tested `pinentry-touchid` in the following combinations of devices and macOS versions:\n\n* MacBook Pro (15-inch, 2018), macOS Catalina - 10.15.7\n* MacBook Pro (15-inch, 2018), macOS Big Sur - 11.4, 11.5.0, 11.5.1\n* MacBook Pro (16-inch, Late 2019), macOS Big Sur - 11.4, 11.5.1\n* MacBook Pro (16-inch, Late 2021), macOS Monterey - 12.2\n\n## Links\n\n* The project icon is taken from \u003ca href=\"https://icons8.com/icon/BebbEec6QUjh/touch-id\"\u003eTouch ID icon by Icons8\u003c/a\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjorgelbg%2Fpinentry-touchid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjorgelbg%2Fpinentry-touchid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjorgelbg%2Fpinentry-touchid/lists"}