How it works

A remote card reader for one operation.

KeyTap moves only the part of decryption that needs your YubiKey® – the key agreement – to your iPhone. Everything else stays on your computer.

sops / age
   |  stdio
   v
KeyTap bridge  (age-plugin-yubikey-phone, on your computer)
   ^  HTTPS, only while a request waits - the phone connects out
   |
KeyTap app  (your iPhone)
   |  NFC: PIN + key agreement
   v
YubiKey

The four steps

1. You decrypt on the computer as usual. The KeyTap bridge – an age plugin on the computer – receives the encrypted file key, which only your YubiKey can unwrap.
2. KeyTap shows the request in plain words: which command, which file, which computer, and a short code that the computer’s terminal shows too.
3. You enter the YubiKey PIN and hold the key to the phone. The YubiKey performs the key agreement (PIV, P-256).
4. The phone unwraps the 16-byte file key and sends only that back. The computer finishes decrypting.

The bridge

The bridge is a small program, age-plugin-yubikey-phone, that works as an age plugin. It is installed ahead of the real age-plugin-yubikey under that name, so age and sops use it without any change. Encryption keeps working because the bridge hands everything except decryption to the real plugin. The source is on GitHub.

When a decrypt starts, the bridge listens on the address you chose – and only then. It shows the request on your phone, waits for the answer, checks it and gives the file key to age. Requests expire after 120 seconds.

Pairing

You pair your phone with your computer once. The bridge prints a keytap:// link containing the computer’s address, the fingerprint of its self-signed certificate and a one-time code. You copy it into the app. The app creates a key in the iPhone’s Secure Enclave and registers its public half with the bridge. During pairing you also tap the YubiKey (or several) so the bridge knows which keys this phone can use; files sealed to several of your keys still give a single prompt.

Several keys, one prompt

sops starts the plugin once per recipient. The bridge forwards only requests for YubiKeys registered at pairing and answers the rest at once with “not here”, just as age-plugin-yubikey does for an absent key. A file sealed to four YubiKeys therefore still means one prompt on your phone.

Dry run

age-plugin-yubikey-phone test checks the whole chain – computer, network, phone, PIN, NFC, YubiKey – without decrypting anything. Run it once after setup and any time something changes.

Notifications are optional

By default KeyTap uses no push notifications: a push travels through Apple’s servers, so you keep the app open while you decrypt. If you prefer a notification, switch it on in the app. Your computer then asks our relay to wake your iPhone; the relay and Apple see only your iPhone’s push token, the time and encrypted text – the details are decrypted on the phone. Tap the notification to open the request; the PIN and the tap happen in the app, because iOS lets only an app on screen read NFC. The notification disappears when you answer or after two minutes.

Read the security model → · Set it up →