maximbaz/ yubikey-touch-detector

(1.9.0) 6 months ago

openpgp

webauthn

yubikey

ssh

notifier

golang

gpg

u2f

View on GitHub

Need help with yubikey-touch-detector?

Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

maximbaz

162 Stars

9 Forks

ISC License

86 Commits

0 Opened issues

Description

A tool to detect when your YubiKey is waiting for a touch (to send notification or display a visual indicator on the screen)

Services available

Need anything else?

Contributors list

Maxim Baz maximbaz

# 15,307

ip-addr...

Arch Li...

Electro...

Zsh

81 commits

Nils Steinger n-st

# 83,773

Shell

JavaScr...

Linux

Laravel

1 commit

Cyrinux cyrinux

# 114,214

dunst

i3bar

JavaScr...

Lua

1 commit

Moritz e1mo

# 247,751

mastodo...

Sass

Shell

Laravel

1 commit

Mikhail Klementev jollheef

# 206,491

Shell

exploit...

isolati...

nix

1 commit

Readme

YubiKey touch detector

Name: yubikey-touch-detector
Brand: yubikey-touch-detector
SKU: //maximbaz/yubikey-touch-detector
Rating: 2.155 (162 reviews)

This 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.

For example, an integration with i3wm and py3status looks like this:

Installation

This tool only works on Linux. If you want to help implementing (at least partial) support for other OS, pull requests are very welcome!

On Arch Linux, you can install it with

pacman -S yubikey-touch-detector

The package also installs a systemd service and socket. If you want the app to launch on startup, just enable the service like so:

$ systemctl --user daemon-reload
$ systemctl --user enable --now yubikey-touch-detector.service

If you want the service to be started only when there is a listener on Unix socket, enable the socket instead like so:

$ systemctl --user daemon-reload
$ systemctl --user enable --now yubikey-touch-detector.socket

Alternatively you can download the latest release from the GitHub releases page. All releases are signed with my PGP key.

Finally you can install the app with

go

$ go get -u github.com/maximbaz/yubikey-touch-detector

This 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.

Usage

Command line

To test how the app works, run it in verbose mode to print every event on STDERR:

$ yubikey-touch-detector -v

Now try different commands that require a physical touch and see if the app can successfully detect them.

Desktop notifications

You can make the app show desktop notifications using

libnotify

if you run it with corresponding flag:

$ yubikey-touch-detector --libnotify

Configuring the app

The app supports the following environment variables and CLI arguments (CLI args take precedence):

| Environment var | CLI arg | | ---------------------------------- | ------------- | |

YUBIKEY_TOUCH_DETECTOR_VERBOSE

-v

| |

YUBIKEY_TOUCH_DETECTOR_LIBNOTIFY

--libnotify

You can configure the systemd service by defining any of these environment variables in

$XDG_CONFIG_HOME/yubikey-touch-detector/service.conf

, e.g. like so:

YUBIKEY_TOUCH_DETECTOR_VERBOSE=true
YUBIKEY_TOUCH_DETECTOR_LIBNOTIFY=true

Integrating with other UI components

First of all, make sure the app is always running (e.g. start a provided systemd user service or socket).

Next, 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.

notifier/unix_socket

unix_socket

notifier allows anyone to connect to the socket

$XDG_RUNTIME_DIR/yubikey-touch-detector.socket

and receive the following events:

| event | description | | ------- | -------------------------------------------------- | |

GPG_1

| when a

gpg

operation started waiting for a touch | |

GPG_0

| when a

gpg

operation stopped waiting for a touch | |

U2F_1

| when a

u2f

operation started waiting for a touch | |

U2F_0

| when a

u2f

operation stopped waiting for a touch |

All messages have a fixed length of 5 bytes to simplify the code on the receiving side.

How it works

Your YubiKey may require a physical touch to confirm these operations:

```
sudo
```
request (via
```
pam-u2f
```
)
WebAuthn
```
gpg --sign
```
```
gpg --decrypt
```
```
ssh
```
to a remote host (and related operations, such as
```
scp
```
,
```
rsync
```
, etc.)
```
ssh
```
on a remote host to a different remote host (via forwarded
```
ssh-agent
```
)

Detecting u2f operations

In 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.

See

detector/u2f.go

for more info on implementation details, the source code is documented and contains relevant links to the spec.

Detecting gpg operations

This 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.

In order to not run the

gpg --card-status

indefinitely (which leads to YubiKey be constantly blinking), the check is being performed only after

$GNUPGHOME/pubring.kbx

(or

$HOME/.gnupg/pubring.kbx

) file is opened (the app is thus watching for

OPEN

events on that file).

If the path to your
pubring.kbx
file differs, define
$GNUPGHOME
environment variable, globally or in
$XDG_CONFIG_HOME/yubikey-touch-detector/service.conf
.

Detecting ssh operations

The 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.

This 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.

FAQ

How do I configure my YubiKey to require a physical touch?

For

sudo

requests with

pam-u2f

, please refer to the documentation on Yubico/pam-u2f and online guides (e.g. official one).

For

gpg

and

ssh

operations, install ykman and use the following commands:

$ ykman openpgp set-touch sig on   # For sign operations
$ ykman openpgp set-touch enc on   # For decrypt operations
$ ykman openpgp set-touch aut on   # For ssh operations

If you are going to frequently use OpenPGP operations,

cached

cached-fixed

may be better for you. See more details here.

Make sure to unplug and plug back in your YubiKey after changing any of the options above.

What are those

.#lk*

files in

~/.gnupg

and how to clean them up?

These are temporary files being created by

gpg

while

yubikey-touch-detector

is checking if YubiKey is waiting for a touch. The hope is that we can implement a different implementation to detect touch request using some sort of smartcard protocol (like it is done for WebAuthn / U2F), which would stop producing these files.

Until then, you have to manually clean them up. One way is to use

systemd-tmpfiles

, which requires you to create

~/.config/user-tmpfiles.d/gnupg.conf

with the contents below and if necessary enabling

systemd-tmpfiles-setup

service:

r %h/.gnupg/.#lk*

Which UI components are already integrated with this app?

waybar can display an indicator via custom yubikey module.
py3status can display an indicator via yubikey module.
barista can display an indicator via yubikey module.
polybar can be made to display an indicator via
```
polybar-msg
```
, like so