KeyTap

Install

Set up the KeyTap bridge.

The bridge runs on the computer where you decrypt. The iPhone app is coming soon to the App Store; the bridge can be installed now.

Before you start

  • A YubiKey® 5 series with NFC (the tested path) or one that plugs into the iPhone, holding an age identity made by age-plugin-yubikey.
  • An iPhone with NFC and the KeyTap app.
  • A computer running macOS, Linux or Windows, with age and age-plugin-yubikey installed (see your system below).
  • The phone and the computer on the same network, or the phone on a VPN into it.

macOS

1. Prerequisites

brew install age age-plugin-yubikey

2. Install the bridge and the shim

Quick install with the script (read it first – it is a plain shell script). It downloads the latest release from GitHub, verifies it against SHA256SUMS, installs it to ~/.local/bin and, with --shim, adds the shim:

curl -fsSL https://keytap.me/get | sh -s -- --shim

Or install it manually or with Go, see below.

3. Check the shim

The shim is the bridge under the name age-plugin-yubikey, found before the real plugin on your PATH, so age and sops ask the phone. Encryption keeps working: the bridge hands everything except decryption to the real plugin. The script never overwrites an existing ~/.local/bin/age-plugin-yubikey.

export PATH="$HOME/.local/bin:$PATH"   # put this in your shell profile; ~/.local/bin must come first
command -v age-plugin-yubikey            # should print ~/.local/bin/age-plugin-yubikey
# without the script: ln -s ~/.local/bin/age-plugin-yubikey-phone ~/.local/bin/age-plugin-yubikey

Then pair your phone.

Linux

1. Prerequisites

Install age and age-plugin-yubikey from your distribution’s packages, or download the release binaries from FiloSottile/age and str4d/age-plugin-yubikey (the latter needs pcscd).

2. Install the bridge and the shim

curl -fsSL https://keytap.me/get | sh -s -- --shim

3. Check the shim

export PATH="$HOME/.local/bin:$PATH"   # in your shell profile, first in the list
command -v age-plugin-yubikey            # should print ~/.local/bin/age-plugin-yubikey

Then pair your phone.

Windows

1. Prerequisites

winget install FiloSottile.age

Download the Windows release of age-plugin-yubikey from github.com/str4d/age-plugin-yubikey and put it on your PATH.

2. Install the bridge and the shim

In PowerShell (read the script first):

& ([scriptblock]::Create((irm https://keytap.me/install.ps1))) -Shim

The script downloads the latest release from GitHub, verifies it against SHA256SUMS, installs it to %LOCALAPPDATA%\KeyTap\bin and, with -Shim, places a copy named age-plugin-yubikey.exe there. It puts that folder first on your user PATH. Open a new terminal afterwards. Then pair your phone.

Manual install with checksum verification

  1. Open the releases page and download the archive for your system together with SHA256SUMS: age-plugin-yubikey-phone-darwin-arm64.tar.gz (Apple silicon), -darwin-amd64.tar.gz (Intel Mac), -linux-amd64.tar.gz, -linux-arm64.tar.gz, -windows-amd64.zip or -windows-arm64.zip.
  2. Verify it (use the file name you downloaded):
# macOS / Linux
shasum -a 256 -c SHA256SUMS --ignore-missing

# Windows (PowerShell): compare with the matching line in SHA256SUMS
Get-FileHash .\age-plugin-yubikey-phone-windows-amd64.zip -Algorithm SHA256

# optional: prove it was built by the project's release workflow (GitHub CLI)
gh attestation verify age-plugin-yubikey-phone-darwin-arm64.tar.gz --repo keytap-me/keytap
  1. Extract it and move age-plugin-yubikey-phone (.exe on Windows) to ~/.local/bin (Windows: a folder on your PATH), then set up the shim as above.

With Go

go install github.com/keytap-me/keytap/cmd/age-plugin-yubikey-phone@latest

This puts the binary in $(go env GOPATH)/bin (usually ~/go/bin); copy or link it to ~/.local/bin and set up the shim as above.

Pair, test, decrypt

  1. Pair. On the computer, using the address your phone can reach it at (a LAN or VPN address): 
    age-plugin-yubikey-phone pair --host <IP of this computer>
    This prints a keytap:// link. The bridge listens on that address only, on port 8743, and only while a decrypt waits – allow it in your firewall if you use one.
  2. Copy the link into the app on your iPhone and follow the steps. Tap your YubiKey(s) against the phone when asked, to register them.
  3. Dry run. Checks the whole chain without decrypting anything: 
    age-plugin-yubikey-phone test
  4. Decrypt normally, with the KeyTap app open: 
    sops -d file
age -d -i identity.txt file.age
    Compare the code on the phone with the one in your terminal, enter the PIN, tap the YubiKey.

Other commands

age-plugin-yubikey-phone devices      # list paired phones and registered YubiKeys
age-plugin-yubikey-phone unpair NAME    # remove a paired phone

Uninstall

macOS / Linux:

rm ~/.local/bin/age-plugin-yubikey ~/.local/bin/age-plugin-yubikey-phone
rm -r ~/.secure/keytap     # optional: the bridge's certificate, paired devices and log

Remove the PATH line you added if nothing else needs it. Windows: delete %LOCALAPPDATA%\KeyTap and remove that folder from your user PATH (Settings → System → About → Advanced system settings → Environment Variables). In the app, Settings → Unpair removes the pairing from the phone.

Problems? See Support.