{"id":13513029,"url":"https://github.com/maximbaz/yubikey-touch-detector","last_synced_at":"2025-05-15T10:03:27.050Z","repository":{"id":38417419,"uuid":"109547506","full_name":"maximbaz/yubikey-touch-detector","owner":"maximbaz","description":"A tool to detect when your YubiKey is waiting for a touch (to send notification or display a visual indicator on the screen)","archived":false,"fork":false,"pushed_at":"2025-01-10T00:23:13.000Z","size":248,"stargazers_count":448,"open_issues_count":11,"forks_count":35,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-14T16:53:54.130Z","etag":null,"topics":["go","golang","gpg","notifier","openpgp","ssh","systemd-service","touch","u2f","webauthn","yubikey"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximbaz.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,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"maximbaz"}},"created_at":"2017-11-05T03:05:00.000Z","updated_at":"2025-04-07T18:26:52.000Z","dependencies_parsed_at":"2024-06-18T15:25:55.707Z","dependency_job_id":"2182daf1-b68c-43cb-86c2-0e3d529d046f","html_url":"https://github.com/maximbaz/yubikey-touch-detector","commit_stats":{"total_commits":125,"total_committers":20,"mean_commits":6.25,"dds":"0.16800000000000004","last_synced_commit":"a7abc22ccf02e68e3c82a166d7cc075707b324c5"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbaz%2Fyubikey-touch-detector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbaz%2Fyubikey-touch-detector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbaz%2Fyubikey-touch-detector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximbaz%2Fyubikey-touch-detector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximbaz","download_url":"https://codeload.github.com/maximbaz/yubikey-touch-detector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319716,"owners_count":22051072,"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","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":["go","golang","gpg","notifier","openpgp","ssh","systemd-service","touch","u2f","webauthn","yubikey"],"created_at":"2024-08-01T04:00:36.617Z","updated_at":"2025-05-15T10:03:22.007Z","avatar_url":"https://github.com/maximbaz.png","language":"Go","funding_links":["https://github.com/sponsors/maximbaz"],"categories":["Tools","Go","Repositories"],"sub_categories":["Third-party Tools"],"readme":"# YubiKey touch detector\n\nThis is a tool that can detect when YubiKey is waiting for your touch. It is designed to be integrated with other UI components to display a visible indicator.\n\nFor example, an integration with [i3wm](https://i3wm.org/) and [py3status](https://github.com/ultrabug/py3status) looks like this:\n\n![demo](https://user-images.githubusercontent.com/1177900/46533233-2bcf5580-c8a4-11e8-99e7-1418e89615f5.gif)\n\n_See also: [Wiki: Which UI components are already integrated with this app?](https://github.com/maximbaz/yubikey-touch-detector/wiki)_\n\n## Installation\n\n**This tool only works on Linux**. If you want to help implementing (at least partial) support for other OS, pull requests are very welcome!\n\nOn Arch Linux, you can install it with `pacman -S yubikey-touch-detector`\n\nThe package also installs a systemd service and socket. If you want the app to launch on startup, just enable the service like so:\n\n```\n$ systemctl --user daemon-reload\n$ systemctl --user enable --now yubikey-touch-detector.service\n```\n\nIf you want the service to be started only when there is a listener on Unix socket, enable the socket instead like so:\n\n```\n$ systemctl --user daemon-reload\n$ systemctl --user enable --now yubikey-touch-detector.socket\n```\n\nAlternatively you can download the latest release from the [GitHub releases](https://github.com/maximbaz/yubikey-touch-detector/releases) page. All releases are signed with [my PGP key](https://keybase.io/maximbaz).\n\nFinally you can install the app with `go`:\n\n### Prequisites for building locally\n\n- gpgme\n\n```\nsudo apt install libgpgme-dev\n```\n\n- For Go \u003c1.17\n\n```\n$ go get -u github.com/maximbaz/yubikey-touch-detector\n```\n\n- For [Go \u003e1.17](https://go.dev/doc/go-get-install-deprecation):\n\n```\n$ go install github.com/maximbaz/yubikey-touch-detector@latest\n```\n\nThis places the binary in your `$GOPATH/bin` folder, as well as the sources in `$GOPATH/src` for you to use the detection functions in your own code.\n\n## Usage\n\n#### Command line\n\nTo test how the app works, run it in verbose mode to print every event on STDERR:\n\n```\n$ yubikey-touch-detector -v\n```\n\nNow try different commands that require a physical touch and see if the app can successfully detect them.\n\n#### Desktop notifications\n\nYou can make the app show desktop notifications using `libnotify` if you run it with corresponding flag:\n\n```\n$ yubikey-touch-detector --libnotify\n```\n\n#### Configuring the app\n\nThe app supports the following environment variables and CLI arguments (CLI args take precedence):\n\n| Environment var                    | CLI arg       |\n| ---------------------------------- | ------------- |\n| `YUBIKEY_TOUCH_DETECTOR_VERBOSE`   | `-v`          |\n| `YUBIKEY_TOUCH_DETECTOR_LIBNOTIFY` | `--libnotify` |\n| `YUBIKEY_TOUCH_DETECTOR_STDOUT`    | `--stdout`    |\n| `YUBIKEY_TOUCH_DETECTOR_NOSOCKET`  | `--no-socket` |\n\nYou can configure the systemd service by defining any of these environment variables in `$XDG_CONFIG_HOME/yubikey-touch-detector/service.conf` - see `service.conf.example` for a configuration example.\n\n#### Integrating with other UI components\n\nFirst of all, make sure the app is always running (e.g. start a provided systemd user service or socket).\n\nNext, in order to integrate the app with other UI components to display a visible indicator, use any of the available notifiers in the `notifier` subpackage.\n\n##### notifier/unix_socket\n\n`unix_socket` notifier allows anyone to connect to the socket `$XDG_RUNTIME_DIR/yubikey-touch-detector.socket` and receive the following events:\n\n| event   | description                                         |\n| ------- | --------------------------------------------------- |\n| `GPG_1` | when a `gpg` operation started waiting for a touch  |\n| `GPG_0` | when a `gpg` operation stopped waiting for a touch  |\n| `U2F_1` | when a `u2f` operation started waiting for a touch  |\n| `U2F_0` | when a `u2f` operation stopped waiting for a touch  |\n| `MAC_1` | when a `hmac` operation started waiting for a touch |\n| `MAC_0` | when a `hmac` operation stopped waiting for a touch |\n\nAll messages have a fixed length of 5 bytes to simplify the code on the receiving side.\n\n## How it works\n\nYour YubiKey may require a physical touch to confirm these operations:\n\n- `sudo` request (via `pam-u2f`)\n- [WebAuthn](https://webauthn.io/)\n- `gpg --sign`\n- `gpg --decrypt`\n- `ssh` to a remote host (and related operations, such as `scp`, `rsync`, etc.)\n- `ssh` on a remote host to a different remote host (via forwarded `ssh-agent`)\n- `HMAC` operations\n\n_See also: [FAQ: How do I configure my YubiKey to require a physical touch?](#faq-configure-yubikey-require-touch)_\n\n### Detecting u2f operations\n\nIn order to detect whether a U2F/FIDO2 operation requests a touch on YubiKey, the app is listening on the appropriate `/dev/hidraw*` device for corresponding messages as per FIDO spec.\n\nSee `detector/u2f.go` for more info on implementation details, the source code is documented and contains relevant links to the spec.\n\n### Detecting gpg operations\n\nThis detection is based on a \"busy check\" - when the card is busy (i.e. `gpg --card-status` hangs), it is assumed that it is waiting on a touch. This of course leads to false positives, when the card is busy for other reasons, but it is a good guess anyway.\n\nIn order to not run the `gpg --card-status` indefinitely (which leads to YubiKey be constantly blinking), the check is being performed only after any shadowed private key files inside `$GNUPGHOME/private-keys-v1.d/*` are opened (the app is thus watching for `OPEN` events on those files).\n\n\u003e If the path to your `private-keys-v1.d` folder differs, define `$GNUPGHOME` environment variable, globally or in `$XDG_CONFIG_HOME/yubikey-touch-detector/service.conf`.\n\nSince v1.11.0 we started using `gpgme` to perform some operations above:\n\n- we are now using Assuan protocol to query card status, instead of spawning `gpg --card-status` processes.\n- we are now querying path to `$GNUPGHOME` from `gpgme`.\n\n### Detecting ssh operations\n\nThe requests performed on a local host will be captured by the `gpg` detector. However, in order to detect the use of forwarded `ssh-agent` on a remote host, an additional detector was introduced.\n\nThis detector runs as a proxy on the `$SSH_AUTH_SOCK`, it listens to all communications with that socket and starts a `gpg --card-status` check in case an event was captured.\n\n### Detecting HMAC operations\n\nThis detection is based on the observation that a certain `/dev/hidraw*` device will disappear when YubiKey will start waiting for a HMAC, and reappear when it stops waiting for a touch.\n\n## FAQ\n\n\u003ca name=\"faq-configure-yubikey-require-touch\"\u003e\u003c/a\u003e\n\n#### How do I configure my YubiKey to require a physical touch?\n\nFor `sudo` requests with `pam-u2f`, please refer to the documentation on [Yubico/pam-u2f](https://github.com/Yubico/pam-u2f) and online guides (e.g. [official one](https://support.yubico.com/support/solutions/articles/15000011356-ubuntu-linux-login-guide-u2f)).\n\nFor `gpg` and `ssh` operations, install [ykman](https://github.com/Yubico/yubikey-manager) and use the following commands:\n\n```\n$ ykman openpgp set-touch sig on   # For sign operations\n$ ykman openpgp set-touch enc on   # For decrypt operations\n$ ykman openpgp set-touch aut on   # For ssh operations\n```\n\nIf you are going to frequently use OpenPGP operations, `cached` or `cached-fixed` may be better for you. See more details [here](https://github.com/drduh/YubiKey-Guide#require-touch).\n\nMake sure to unplug and plug back in your YubiKey after changing any of the options above.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximbaz%2Fyubikey-touch-detector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximbaz%2Fyubikey-touch-detector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximbaz%2Fyubikey-touch-detector/lists"}