Skip to content
gmkbenjaminPublic

About

Keythra: iPhone as your security key — SSH, Git signing, FIDO2/WebAuthn, smart card, OpenPGP card, cosign, Nostr — with a macOS bridge

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

105 Commits

Folders and files

Repository files navigation

Keythra

Keep Apple Passwords. Add a security key.

Keythra holds keys for the protocols Apple Passwords does not cover — SSH, Git signing, FIDO2/U2F security keys, PKCS#11, X.509/CMS, OpenPGP, HOTP/OCRA, YubiKey-style challenge-response, Yubico OTP, minisign and JWS — and asks you before every use.

Keys live on your iPhone (the authenticator); your Mac runs a bridge that exposes them to standard tools over an end-to-end encrypted, paired link. The same authenticator can also run directly on a Mac for development or single-device use.

Status: v0.1, built and tested on macOS 27 / iOS 27 (Simulator). Not audited. See docs/build-plan.md for the design and Limitations. Moving from a YubiKey: docs/yubikey-replacement.md.

Where keys live

Chosen per key at creation (software keys can move between the device and iCloud Keychain later):

Storage Algorithms Syncs Notes
Secure Enclave P-256 (sign + ECDH) Never Non-exportable, this device only. Requires Face ID / Touch ID at the key by default.
This device (software) Ed25519, X25519, P-256, P-384, RSA 2048–4096, secp256k1, HMAC, AES-128 No Not synced, excluded from backups.
iCloud Keychain (software) same as above Yes Synced end-to-end encrypted to your devices on the same Apple Account (including Macs running the signed app). Survives losing a device. Face ID is enforced by Keythra, not by the keychain item (Apple disallows biometric locks on synced items). FIDO credentials in this mode report backup-eligible/backed-up and signCount 0.

Syncing keys between iPhone and Mac

Keys in iCloud Keychain are shared by the iOS app and the Mac app (same keychain service and access group), so each device can use them on its own: the Mac with keys On this Mac lists and uses its own keys plus the synced ones, and Touch ID approves each use there (Face ID on the iPhone). Choose the storage when creating a key, set where new keys and new security-key credentials start (iPhone: About → Where new keys live), or move a key later:

  • Sync to your other devices (key details on the iPhone, the key's menu in the Mac's Keys window) moves a This device software key to iCloud Keychain after Face ID / Touch ID, keeping its id and public key (an OpenPGP key moves with its subkeys). It leaves the device's protection for your Apple Account's end-to-end-encrypted iCloud Keychain plus Keythra's approval; an item-level Face ID lock is dropped (synced items cannot have one). Keep on this device only reverses it, which removes the key from every other device; copies that synced before cannot be recalled, and the key is marked as previously synced.
  • Secure Enclave keys never move. "Create a synced replacement…" opens key creation with the same purpose and name in iCloud Keychain (P-256); register the new public key where you used the old one.
  • Security-key (FIDO) credentials stay where they were made: a site records whether a credential is backup-eligible, so a moved copy would be refused. New ones can be made in iCloud Keychain; they report BE/BS and signCount 0 (over U2F, which has no flags, the counter is the clock).

Sync semantics: deleting a synced key deletes it on every device; a key's metadata and state (label, approval policy, SSH namespaces, HOTP/OCRA/Yubico OTP counters) are last-writer-wins between devices, so two devices that each show a code before syncing may repeat a counter (the server accepts the code once) — keep HOTP keys device-only if several devices use them in quick succession. Module state (FIDO PIN and settings) and the Mac link's pairings stay on each device and never sync. The keythra CLI cannot open iCloud Keychain: keythra key list shows only ~/.keythra/vault, while the app's bridge serves synced keys to ssh, Git, FIDO and PKCS#11.

Every key has exactly one purpose (ssh-auth, ssh-sign, ssh-ca, fido, x509, openpgp, otp, minisign, jws), so an SSH login key can never sign a Git commit, a certificate or a JWT. Every private-key operation needs a single-use approval bound to the key, the purpose, a deadline and (where known) the exact bytes signed. Approval screens label each detail verified (checked or built by the authenticator), observed (seen by the Mac bridge) or claimed (reported by the requesting app).

Protocols

Protocol Consumer tested against How to use
SSH login agent /usr/bin/ssh → sshd; ssh -A forwarding IdentityAgent ~/.keythra/agent.sock (keythra ssh config)
SSH signatures / Git (gpg.format=ssh) ssh-keygen -Y verify, git verify-commit/verify-tag gpg.ssh.program=keythra-ssh-sign
SSH certificate authority ssh-keygen -s … -U, sshd TrustedUserCAKeys SSH_AUTH_SOCK=~/.keythra/sign.sock
FIDO2 / CTAP 2.1 + U2F python-fido2 client + server (registration, assertion, PIN v1/v2, hmac-secret/prf, credProtect, credMgmt) ctaphid.sock; CoreHID virtual device behind the Apple entitlement (untested)
Passkeys via iOS AutoFill (credential provider) Safari in the iOS 27 Simulator → python-fido2 Fido2Server (registration, sign-in, denial, excludeCredentials) Settings → General → AutoFill & Passwords → Keythra; nearby computers: "Use a phone or tablet"
OpenSSH security keys (ecdsa-sk, ed25519-sk) ssh-keygen, sshd via ssh-sk-helper SecurityKeyProvider=libkeythra-sk.dylib
PKCS#11 pkcs11-tool (outputs verified with openssl), ssh -o PKCS11Provider, ssh-keygen -D keythra pkcs11 path
macOS smart card (CryptoTokenKit token "Keythra") SecItemCopyMatching + SecKeyCreateSignature/SecKeyCreateDecryptedData, URLSession TLS client auth against openssl s_server, codesign Mac app: "Offer certificates as a smart card"; keys enabled for PKCS#11 that have a certificate
Mac lock screen unlock with the iPhone (opt-in Mac login key) sc_auth identities; SecKeyCreateSignature through the token with the PIN as an LAContext smart-card PIN credential; the keychain key's ECIES unwrap through the token (not yet at a real lock screen) Unlocking the Mac: key → "Unlock your Mac with this key", Mac → Unlock This Mac…, sudo sc_auth pair
X.509 CSR / certificates / chains openssl req/x509/verify keythra x509 …
CMS signatures / Git (gpg.format=x509) openssl cms, gpgsm, git verify-commit gpg.x509.program=keythra-gpgsm
OpenPGP (v4) sign + decrypt / Git GnuPG 2.5 (--verify, -e, --import --check-sigs), git verify-commit gpg.program=keythra-gpg, keythra pgp …
HOTP (RFC 4226), OCRA (RFC 6287) RFC vectors, oathtool `keythra otp hotp
HMAC-SHA1 challenge-response (YubiKey slot semantics) RFC 2202, Python hmac keythra otp chalresp
Yubico OTP (own validation server) independent AES/CRC decode keythra otp yubico
minisign minisign -V keythra minisign …
JWS / JWT (ES256, ES384, EdDSA, RS256, PS256) PyJWT keythra jws …
Container / artifact signing (cosign, Notation) cosign 3.1 (sign-blob/verify-blob, sign/verify, attest/verify-attestation in a local registry), Notation 1.3 (sign/verify, strict trust policy) --key keythra://<key>, notation-keythra, keythra artifact …
Nostr: NIP-46 remote signer ("bunker"), NIP-01 events, NIP-04/NIP-44, NIP-19 nak (go-nostr NIP-46 client) through a local relay; go-nostr nostrconnect:// client keythra nostr bunker / connect, then paste the link into the Nostr app
OpenPGP card for stock GnuPG (sign, decrypt, SSH auth) gpg-agent 2.5 + gpg --card-status/--edit-card/--sign/-d, git commit -S, ssh via enable-ssh-support scdaemon-program keythra-scdaemon, keythra pgp card …
WebAuthn security key for websites (browser extension) Chrome for Testing 153, Brave 1.96, Firefox 157, the Safari build in WebKit's extension engine; native host in iPhone mode → python-fido2 Fido2Server (registration, sign-in, PRF, fallback) Browser extension: Mac app → Browsers…, or keythra browser install

TOTP and website passwords stay in Apple Passwords. Keythra can also serve passkeys through iOS AutoFill: Apple only accepts synced passkeys from a provider, so these are iCloud Keychain software keys (BE/BS set, signCount 0, "none" attestation, Keythra's synced AAGUID) approved with Face ID on Keythra's own screen. Secure Enclave security keys work through the Mac bridge, and in Safari on the iPhone through the Keythra extension (Browser extension).

When the Mac app is needed

The iPhone works on its own wherever iOS or another device can talk to it directly; the Mac app is only a bridge for protocols that have no way to reach a phone. Over the bridge, the iPhone connects over Wi-Fi while Keythra is open and over Bluetooth LE when it is nearby — also while Keythra is in the background, where a request arrives as a notification (tap it, then approve with Face ID). The Mac uses Wi-Fi when both are up. Both carry the same Noise-encrypted, mutually authenticated link.

Protocol How it reaches the iPhone Mac app needed
Passkeys in Safari, other iOS browsers and apps iOS AutoFill (Keythra's credential provider) No
Passkeys on a nearby computer ("Use a phone or tablet" in Chrome, Edge, Safari; Firefox where the OS provides it) iOS hybrid transport: QR code, Bluetooth proximity check, relay No (any OS; no Keythra software on the computer)
Safari on the iPhone (Keythra Safari extension) In the iPhone itself No
HOTP codes, Scan (pairing, otpauth://, FIDO:/, key checks) On the iPhone No
Bluetooth FIDO security key for other computers (CTAP BLE) Not offered: iOS cannot advertise a compliant FIDO service (build plan §15) —
SSH login, SSH certificates, OpenSSH -sk keys Mac bridge → Wi-Fi or Bluetooth Yes
Git signing (SSH, OpenPGP, X.509/CMS) Mac bridge → Wi-Fi or Bluetooth Yes
OpenPGP card for stock GnuPG, keythra-gpg Mac bridge → Wi-Fi or Bluetooth Yes
PKCS#11 module, macOS smart card (CryptoTokenKit) Mac bridge → Wi-Fi or Bluetooth Yes
cosign / Notation, minisign, JWS Mac bridge → Wi-Fi or Bluetooth Yes
Nostr remote signer (bunker) Mac bridge → Wi-Fi or Bluetooth Yes
Security keys in desktop browsers on the Mac (browser extension, ctaphid.sock) Mac bridge → Wi-Fi or Bluetooth Yes

Pairing still happens once over Wi-Fi (scan the Mac's QR code with both devices on the same network); after that the Bluetooth path is used automatically whenever the Mac is in range, including when the iPhone is on another network or none. iOS relaunches Keythra in the background for Bluetooth after it ended the app itself and after a restart (once unlocked), but not after you force-quit it or turned Bluetooth off and on (Settings or Control Center; Apple TN3115): open Keythra once after those.

Build and test

~/Documents may be iCloud-synced, and codesign rejects build products that the File Provider tags, so build output lives in ~/Library/Caches:

make build        # swift build
make test         # unit tests (469)
make integration  # 40 end-to-end tests against the real tools listed above (a few minutes)

Integration tests need OpenSSH (system), brew install gnupg opensc minisign libfido2 oath-toolkit and a Python venv (make venv: python-fido2, cryptography, pyjwt). The Nostr test needs nak (go install github.com/fiatjaf/nak@latest) and is skipped without it.

Apps (xcodegen spec in apps/project.yml): Keythra for iOS (keys, approvals, pairing) and Keythra for macOS, a menu-bar app that runs the bridge (keys on the Mac with Touch ID, or on a paired iPhone), pairs the iPhone with a QR code, and can start at login. Icons are generated by swift apps/design/make-icons.swift.

cd apps && xcodegen generate && open Keythra.xcodeproj

apps/ios/scripts/e2e-mac-ssh.sh runs the whole chain with the app in the Simulator: ssh on the Mac → bridge → Noise link → iOS app → Face ID approval → login. apps/ios/scripts/e2e-passkey-provider.sh turns Keythra on in Settings, then registers and signs in on a local WebAuthn page in Safari through the AutoFill extension (Face ID simulated), verified by python-fido2. apps/ios/scripts/e2e-safari-extension.sh turns on the Keythra Safari extension in Settings, then registers a security key and signs in through it in Safari (approval page, Face ID simulated), also verified by python-fido2. KEYTHRA_CTK_APP=<Debug Keythra.app> make integration also has macOS use the smart card (the test registers the token extension with pluginkit and removes it again), and KEYTHRA_SAFARI_APP=<Debug Keythra.app> the Safari extension. Build those apps with xcodebuild … KEYTHRA_SOCKET_TAG=t1: test instances share the app group container with the installed app, and the tag gives the test build's app and extensions sockets of their own (ctk-t1.sock, safari-t1.sock). It also gives the test build a token class and token extension of its own (…bridge.smartcardt1), so the installed Keythra can keep running during the smart-card test. An untagged test instance (KEYTHRA_HOME or CFFIXED_USER_HOME elsewhere) uses sockets no extension reaches and leaves the smart card alone. The app build also puts release builds of the command-line tools in Keythra.app/Contents/Helpers (KEYTHRA_SKIP_HELPERS=YES skips that for quick UI builds; KEYTHRA_HELPERS_SCRATCH sets their SwiftPM build directory). The Bluetooth link needs real devices: keythra-ble-probe runs a Bluetooth-only Mac bridge on a test KEYTHRA_HOME and checks the paired iPhone every few seconds; see docs/ble-device-test-plan.md.

Using it

Open Keythra on the Mac: a setup window asks where keys live (on the iPhone or on this Mac), pairs the iPhone with a QR code or creates a Touch ID–protected SSH key, and adds the agent to ~/.ssh/config. The menu-bar icon shows whether Keythra is ready and can pause it. The CLI does the same without the app.

On the Mac, with keys on the Mac itself:

keythra key generate --purpose ssh-auth --algorithm p256 --storage secure-enclave --label laptop
keythra daemon                      # Touch ID approves each request
keythra ssh config                  # ssh_config and Git snippets

With keys on the iPhone:

keythra daemon --authenticator remote   # bridge only; holds no keys
keythra link pair                        # shows a QR code; scan it in Keythra on the iPhone

Container and artifact signing

Artifact-sign keys (P-256, P-384, RSA, and Ed25519 for cosign blobs) sign for cosign through the sigstore KMS plugin sigstore-kms-keythra and for Notation through the plugin notation-keythra; both talk to the daemon, so the key can be on the Mac or on the iPhone. keythra artifact setup <key> prints these commands with the right paths.

# sigstore-kms-keythra and notation-keythra are built next to keythra; cosign finds its plugin on PATH.
keythra key generate --purpose artifact-sign --algorithm p256 --label release

# cosign. --tlog-upload=false keeps the signature and public key out of the public Rekor log.
cosign public-key --key keythra://release > cosign.pub
cosign sign-blob --key keythra://release --tlog-upload=false --use-signing-config=false --bundle app.tgz.sigstore.json app.tgz
cosign verify-blob --key cosign.pub --insecure-ignore-tlog=true --bundle app.tgz.sigstore.json app.tgz
cosign sign --key keythra://release --tlog-upload=false --use-signing-config=false registry.example/app@sha256:…
cosign verify --key cosign.pub --insecure-ignore-tlog=true registry.example/app@sha256:…

# Notation needs a code-signing certificate: self-signed here (or `keythra artifact csr` for a CA,
# then `keythra artifact import-cert`). Notation accepts x509.subject identities with C, ST and O.
keythra artifact cert release --subject "C=US,ST=WA,O=Example,CN=Release signing" -o release.crt
notation plugin install --file "$(command -v notation-keythra)"
notation key add --plugin keythra --id release --default release
notation cert add --type ca --store keythra release.crt
notation sign registry.example/app@sha256:…
cat > policy.json <<'EOF'
{"version": "1.0", "trustPolicies": [{"name": "keythra", "registryScopes": ["*"],
  "signatureVerification": {"level": "strict"}, "trustStores": ["ca:keythra"],
  "trustedIdentities": ["x509.subject: C=US, ST=WA, O=Example, CN=Release signing"]}]}
EOF
notation policy import policy.json && notation verify registry.example/app@sha256:…

The approval shows what the signed bytes say, read by the authenticator itself: for cosign sign the image digest and annotations (verified; cosign 3 signs an in-toto statement that does not contain the image name, and the repository named by the legacy format is shown as claimed); for blobs the size and SHA-256 the authenticator computed over the streamed file; for Notation the artifact's media type, digest, size, annotations and the signing time, and that the image or file name is not part of the signature. Bytes another verifier would read as something else (a JWS signing input, a COSE structure, an X.509 to-be-signed certificate, CMS signed attributes) are refused, and so is a request that carries only a digest without the content (its signature would fit anything with that digest, a Notation JWS included). Nostr apps (NIP-46): create a Nostr key (iPhone: Keys → New Key → Used for: Nostr; or keythra nostr import), then keythra nostr bunker --relay wss://… prints a one-time bunker:// link (and QR code) to paste into the app; keythra nostr connect 'nostrconnect://…' answers an app that shows its own link. keythra nostr clients lists and revokes apps.

Stock GnuPG: Keythra as an OpenPGP card

For tools that run gpg and gpg-agent themselves (Git with the default gpg.program, pass, mutt, encrypted mail), keythra-scdaemon takes the place of GnuPG's smartcard daemon and shows Keythra's OpenPGP keys as an OpenPGP card (application 3.4), as a YubiKey's OpenPGP applet would:

keythra pgp generate --user-id "Me <me@example.com>" --signing-subkey --authentication-subkey
keythra pgp export me@example.com | gpg --import
keythra pgp card                    # slots, and the scdaemon-program line for this install
# ~/.gnupg/gpg-agent.conf
scdaemon-program /path/to/keythra-scdaemon
enable-ssh-support                  # optional: SSH with the card's authentication key

Then gpgconf --kill gpg-agent and gpg --card-status once, which links the imported subkeys to the card (ssb>). From then on gpg --sign, gpg -d, git commit -S and (with enable-ssh-support) ssh use Keythra, on this Mac or on the paired iPhone.

  • With a single OpenPGP key, its signing, encryption and authentication (sub)keys fill the card's three slots. Otherwise pick: keythra pgp card use KEY, or keythra pgp card set sig|dec|aut KEY. keythra pgp card url URL sets the URL that gpg --edit-card → fetch downloads.
  • A card only receives a hash to sign or a message key to decrypt. The approval therefore says that Keythra can't see the content and doesn't know which program asked gpg-agent, and names the key, its fingerprint and its slot. Where a tool allows it, keythra-gpg (full commit shown) and Keythra's SSH agent (destination verified) show more.
  • There is no card PIN: every use is approved in Keythra. The card reports the PIN as not forced, and refuses PIN changes, key import, on-card key generation and other admin commands.
  • The serial number uses manufacturer ID 0xFF4B, from the OpenPGP card spec's range for self-assigned serial numbers, and names Keythra as the manufacturer. It does not imitate any vendor's token.

Unlocking the Mac's lock screen with the iPhone (opt-in)

An x509 key with a certificate (P-256, P-384 or RSA) can unlock the Mac's lock screen and screensaver. You type a Keythra unlock PIN on the Mac, then approve on the iPhone. Nothing changes how the Mac logs in until you pair the key with your account yourself:

  1. iPhone: Keys → the key → Unlock your Mac with this key. The key becomes the Mac login key. It is used for nothing else: apps that could sign with it ("Allow Signing…") no longer can, and like a PKCS#11 key it makes no more certificates, CSRs or CMS signatures, also after you turn this off. With keys on the Mac: Keys window → right-click → Unlock This Mac With This Key…, or keythra pkcs11 mac-login <key>. Turning it on also adds the key's keychain key (you approve its certificate), so macOS can unlock your login keychain too. A key marked before keychain keys existed gets one with Add Keychain Key on the same page (or keythra pkcs11 mac-login <key> again); then pair it again (step 3).
  2. Mac: Keythra menu → Unlock This Mac… → set an unlock PIN of 4–8 digits, or use keythra pkcs11 unlock-pin. It is stored in ~/.keythra/link-vault (sealed with this Mac's Secure Enclave) only as a salted PBKDF2-HMAC-SHA256 hash (600,000 iterations). After 5 wrong PINs in a row, unlocking stays off until you turn it on again in that window (or set a new PIN).
  3. Terminal, which only you run: sc_auth identities, then sudo sc_auth pair -u $USER -h <hash>, using the hash the Unlock window shows. To undo it: sudo sc_auth unpair -u $USER -h <hash>. If you paired before the key had a keychain key, unpair and pair again with the same hash. macOS may then ask once for your keychain password ("Smartcard Agent wants to use keychain") to store it for the keychain key; after that it shouldn't ask again.

How it works:

  • The Keythra smart card offers the login key with isSuitableForLogin and a PIN constraint. macOS hands the token the PIN it collects (at the lock screen, its PIN field), and the bridge checks it, counting wrong ones, before anything goes to the iPhone. A correct PIN earns a one-time ticket for one signature.
  • The iPhone approves with Face ID. A notification asks "Unlock “Ben's MacBook Air”?". macOS doesn't tell a token which app is asking, so the approval says "Unlock “Ben's MacBook Air”, or another use of your Mac login key". It shows the paired Mac (verified), the time and that the PIN was entered (observed). The request is also refused on the iPhone unless the bridge's token service says the PIN was checked. The control socket can't send that.
  • The keychain key is a P-256 key-agreement key in the login key's storage (the Secure Enclave when the login key is there) with its own certificate (key usage keyAgreement). The token offers it next to the login key as a second identity that only exchanges keys (raw ECDH), behind the same PIN. Pairing has macOS wrap your login keychain's password for it; unlocking unwraps it. That one ECDH, within a minute of an unlock you approved and from the same Mac, rides on that approval (it is in the activity log as "Approved with the request just before"); any other asks "Unlock the login keychain on “Ben's MacBook Air” (with your Mac login key)". It does nothing else, and is deleted with the login key.
  • Every other smart-card key stays isSuitableForLogin = false, and no other key exchanges keys.

Safety:

  • It works at the lock screen and screensaver only. After a restart, FileVault and the first login still need your password: Keythra isn't running yet.
  • Your password always keeps working. Keythra never sets smart-card-only login (enforceSmartCard); don't set it yourself.
  • While the key is offered, macOS may ask for the PIN instead of the password. The key is offered only while the paired iPhone is connected. After an unlock that was denied, went unanswered or found no iPhone, it is withdrawn for 5 minutes. After 5 wrong PINs it is withdrawn until you turn unlocking on again. Each of these should bring the password field back (not yet tried at a real lock screen); a restart always does.
  • With keys on the Mac, the key isn't offered to the lock screen: the approval would be a Touch ID prompt in your session, which macOS can't show over the lock screen.

The lock screen itself hasn't been tried yet: see docs/mac-unlock-test-plan.md.

Browser extension

Keythra works as a FIDO2 / U2F security key on websites in Safari, Chromium-family and Firefox-family browsers through the Keythra extension (apps/browser-extension, Manifest V3: one code base, one manifest per browser family). When a site calls WebAuthn, a small panel asks whether to use Keythra or the browser's own flow; Keythra requests are approved on the iPhone (or with Touch ID when keys are on the Mac) like every other request. That covers what passkeys in AutoFill cannot: "add a security key" pages, non-discoverable credentials and old U2F registrations (AppID).

Browser (macOS unless noted) Status Set up
Safari Tested in WebKit's Web Extensions engine (the one Safari's extensions run on), not in Safari's own window Built into Keythra.app: Safari → Settings → Extensions → turn on Keythra Security Key, then allow it on websites
Safari on iPhone Tested in the iOS Simulator (registration, sign-in, denial; Face ID simulated); not yet on a device Built into the iOS app: Settings → Apps → Safari → Extensions → Keythra Security Key → Allow Extension, and Other Websites → Allow (or Ask, then allow per site)
Chrome, Chrome Beta / Dev / Canary, Chromium Tested (Chrome for Testing 153) Load unpacked (below)
Brave (also Beta, Nightly) Tested (Brave 1.96) Load unpacked; Brave reads manifests from Chrome's directory only
Microsoft Edge (also Beta, Dev, Canary) Expected to work (Microsoft documents the location) Load unpacked
Opera, Opera GX Expected to work (Opera documents Chrome's directory) Load unpacked (opera://extensions, Developer mode)
Arc, Vivaldi, Dia, Comet, Thorium, Helium Expected to work (locations from their source or tested by other native hosts) Load unpacked
Firefox Tested (Firefox 157) Temporary add-on, or a signed .xpi (below)
Firefox Developer Edition, Nightly, LibreWolf, Waterfox, Zen, Floorp Expected to work Temporary add-on, or the .xpi with xpinstall.signatures.required off
Orion Unsupported for now: Orion starts native hosts, but their replies never reach the extension (Kagi's bug tracker, marked planned) —
DuckDuckGo Unsupported: no third-party extensions —
Tor Browser, Mullvad Browser Not set up: possible in principle, but an add-on and a security key that ties accounts together work against what these browsers are for —
Chrome, Firefox, Edge, … on iPhone Passkeys only (Keythra in AutoFill): iOS browsers other than Safari cannot run extensions with native messaging —

Set up on the Mac: menu → Browsers…. Set Up Browsers writes the native-messaging manifests for every Chromium- or Firefox-family browser found on the Mac, pointing at the host inside Keythra.app (Contents/Helpers/keythra-webauthn-host); Show Extension in Finder shows the extension, kept at ~/Library/Application Support/Keythra/browser-extension/{chromium,firefox} (refreshed when Keythra starts, so the path stays valid across updates); Open Safari Extension Settings opens Safari's page for the extension. Then load the extension once in each browser:

  • Chromium family: chrome://extensions (edge://, brave://, opera://, arc://, vivaldi://) → Developer mode → Load unpacked → the chromium folder. Its ID, gieklbdnfohbhkbimdbgggmemfdjdioc, is fixed by the public key in manifests/chromium.json, and only that ID may start the native host.
  • Firefox family: about:debugging → This Firefox → Load Temporary Add-on → manifest.json in the firefox folder. Release Firefox keeps only add-ons signed by Mozilla, so a temporary add-on is gone when Firefox quits. To keep it: sign it as an unlisted (self-distributed) add-on with your own AMO API key — WEB_EXT_API_KEY=… WEB_EXT_API_SECRET=… apps/browser-extension/sign-firefox.sh — and install the .xpi (about:addons → Install Add-on From File); or, in Developer Edition, Nightly, LibreWolf, Waterfox, Zen or Floorp, set xpinstall.signatures.required to false and install the unsigned build.

The CLI does the same:

apps/browser-extension/build.sh            # dist/chromium, dist/firefox, dist/safari (and a .zip of each)
keythra browser list                       # every browser it knows, and which have a manifest
keythra browser install                    # manifests for the browsers found (the host next to this keythra)
keythra browser install --browser opera    # or one: chrome, edge, brave, opera, arc, vivaldi, firefox, zen, …
keythra browser uninstall                  # removes them

Keythra.app carries release builds of the command-line tools in Contents/Helpers (keythra, keythra-webauthn-host, keythra-scdaemon, keythra-gpg, keythra-gpgsm, keythra-ssh-sign, sigstore-kms-keythra, notation-keythra, libkeythra-pkcs11.dylib, libkeythra-sk.dylib), signed with the app's identity; keythra browser install from there uses the bundled host (to use them from a shell: export PATH="/Applications/Keythra.app/Contents/Helpers:$PATH"). Nothing is published to an extension store (that is your decision). Store listings would give one-click installs, updates and permanent Firefox installs; their extension IDs differ from the unpacked one, so allow them with keythra browser install --extension-id <id> (Chromium) — every Chromium browser that reads Chrome's directory shares that manifest.

How it works and what is checked:

  • page.js runs in the page's world at document_start (top-level documents only; Safari 18+ supports this too) and wraps navigator.credentials.create/get for publicKey requests. Conditional mediation (autofill), requests for a platform authenticator, mixed credential types, required largeBlob and anything it cannot read go to the browser's saved original functions untouched; so does "Use browser".
  • The background script takes the origin from the browser (sender.origin), never from the page. Chromium and Firefox report an opaque ("null") origin for sandboxed documents, which is refused. Safari (WebKit) computes sender.origin from the frame's URL instead, so it would report a sandboxed document's URL origin: the content scripts check the document's own origin (window.origin in the extension's isolated world, which the page cannot change) and stand down in opaque-origin documents.
  • Chromium and Firefox start keythra-webauthn-host over native messaging; closing the port (abort, tab closed) ends it, and the approval is withdrawn. Safari hands native messages to the extension inside Keythra.app instead (one reply per message): on the Mac its handler, sandboxed with the app group only, forwards each message over a Unix socket in the app group container to the bridge, which serves only the Safari extension's code signature (identifier + team, checked against the kernel's audit token) and runs the same WebAuthn client; an abort becomes a "cancel" message for that request.
  • The WebAuthn client (WebAuthnClient, one implementation for every browser) checks the RP ID against that origin with the browser's registrable-domain-suffix rules and the complete Public Suffix List (ICANN and private sections, compiled in: a hand-picked subset would silently let the tenants of any missing hosting suffix share credentials), builds the client data, maps the options to CTAP2 (allow/exclude lists, rk, uv, ES256/EdDSA, credProps, credProtect, hmacCreateSecret, PRF, and the AppID extension for U2F registrations) and returns a PublicKeyCredential (with getTransports, getPublicKey, toJSON, …) on the daemon's webauthn channel. In iPhone mode that channel crosses the link and the phone approves.
  • The authenticator does not trust the client: it rebuilds the client data from (ceremony, challenge, origin) and requires the request to sign exactly its hash, checks the RP ID again, and refuses silent (up=false) and PIN-token requests. The prompt shows the website as claimed — Website (reported by the Keythra browser extension), since any local process that can reach the bridge could report another, or Website (reported by the Keythra Safari extension), which only the Safari socket's verified peer can set (the control socket refuses that mark) — and the Relying party (checked against the website) as verified. That origin is inside what is signed, so a site rejects the signature if it was not the site asking.
  • Results are honest about what Keythra is: authenticatorAttachment "cross-platform", transports [] (the browser cannot reach Keythra by itself), "none" attestation unless the site asks (then packed self attestation with Keythra's AAGUID and no vendor certificate).
  • "Remember for this site" is stored per origin, only from a click in the panel; the toolbar popup lists remembered sites (with Forget) and whether Keythra answers. Either way every Keythra signature is still approved on the phone or with Touch ID.

On the iPhone the extension is the security key itself: its handler runs the same WebAuthn client and the FIDO security-key engine in the extension's process, with credentials in a keychain access group of their own (…keythra.securitykeys; the extension parses web input, so it cannot reach the app's other keys, and the app lists and deletes these under Keys → Security keys (Safari)). They are device-only Secure Enclave keys (P-256; a device-only software key for EdDSA-only sites), separate from the Mac bridge's: register them as another key. Face ID shows no text, so every use first opens Keythra's approval page, an extension page the website cannot script or cover, with the website (claimed: reported by Safari to the extension) and the RP ID (verified against it); only an Approve tapped there continues to Face ID, and the handler approves only the request it described (an HMAC token over the request and the details, valid for two minutes, recomputed rather than trusted). Other iOS browsers cannot run extensions with native messaging; there, and in every iOS browser, Keythra's passkeys work through AutoFill. Mac browsers reach the iPhone's keys through the Mac app's extensions with keys On my iPhone, and any desktop browser on any system can use "Use a phone or tablet" (the QR code, scanned with Keythra's Scan or the Camera). The app's About → Browsers screen says the same.

Tests/integration/test-browser-webauthn.sh drives Chrome for Testing and Firefox (if available), and Brave with KEYTHRA_BRAVE=<executable>, against a local page; see its header for the tools it needs. It skips without them. KEYTHRA_SAFARI_APP=<Keythra.app built with KEYTHRA_SOCKET_TAG=t1> Tests/integration/test-safari-extension.sh loads the Safari build into WebKit's extension engine and registers and signs in through a test instance of the app (Safari's own window needs your settings, so no test drives it). test-link-requests.sh checks the native host in iPhone mode.

On the iPhone, Scan (Keys tab) reads a QR code from the camera, the clipboard (Paste) or a photo (Choose Photo) and says what it is before anything happens: a Mac's pairing code starts pairing; an otpauth://hotp/… code adds a HOTP credential (the key's Show Next Code asks for Face ID and advances the counter); an otpauth://totp/… code goes to Apple Passwords (Add to Passwords); a FIDO:/… code from a browser's "use a phone" prompt goes to iOS for the hybrid sign-in; an SSH public key line or SHA256: fingerprint, an OpenPGP fingerprint (openpgp4fpr:), a PEM public key or a minisign key or a Nostr npub1… is compared exactly with the keys on the iPhone ("Matches your key …"). nostrconnect:// and bunker:// codes are explained (Nostr signing is set up on the Mac). An otpauth-migration:// export (Google Authenticator) is explained but never shown or copied, since it holds every account's secret. A photo with several codes lists them to choose from. Anything else is shown as sanitized text; links in codes are never opened.

Limitations

  • iOS background: over Wi-Fi, requests reach the iPhone only while Keythra is open. Over Bluetooth LE they also reach it in the background (iOS wakes the app; a time-sensitive notification leads to the approval), as long as the Mac is in Bluetooth range and Keythra was not force-quit (iOS 26 relaunches force-quit apps only for AccessorySetupKit accessories). Otherwise the Mac app shows a notification asking you to open Keythra. The Bluetooth path was built against Apple's documented background behaviour and tested with an in-memory transport; it has not yet run between real devices (docs/ble-device-test-plan.md). A push relay for phones out of Bluetooth range is not built.
  • Bluetooth link: the Mac advertises one fixed service UUID (no name) while in iPhone mode, which tells nearby devices that a Keythra Mac is there, not whose. No Bluetooth pairing is used (Noise authenticates and encrypts end to end). Two Keythra apps advertising on one Mac (e.g. a test instance with KEYTHRA_LINK_BLUETOOTH=1) confuse the phone; test instances leave Bluetooth off.
  • USB security-key clients: websites reach Keythra through the browser extension; native apps that open a security key over USB (libfido2, pam_u2f, …) only through the CoreHID virtual HID device, which needs Apple's request-only com.apple.developer.hid.virtual.device entitlement. It is implemented but untested.
  • AutoFill passkeys: device builds need App IDs with the AutoFill Credential Provider capability for the app and …keythra.credential-provider; the first device build registers them (-allowProvisioningUpdates with an Apple account signed in to Xcode). Hybrid use from a nearby computer comes from iOS and was not exercised (the Simulator has no Bluetooth). In the Simulator the system's identity store reports Keythra as off and rejects identities, so QuickType suggestions are untested (sign-in works through "More from Keythra…"). Approvals in the extension are not in the app's Activity log (no shared container). AutoFill passkeys live in their own keychain access group (…keythra.passkeys), the only one the extension is entitled to, so the Mac bridge's security keys do not see them, and AutoFill does not offer synced credentials made through the bridge. The app moves passkeys made before this split into that group when it starts.
  • AutoFill passkey website names are unchecked by Keythra: the approval shows the RP ID as the website name the browser or app asking gave to iOS. iOS checks it for Safari and for apps (associated domains), but third-party browsers holding Apple's browser passkey entitlement and software on a nearby computer (hybrid) supply it themselves, and the extension is not told which one is asking. The passkey still only works for that website name.
  • Synced keys on the Mac need a provisioned build of the Mac app: keychain-access-groups is a restricted entitlement on macOS, so the app needs a Mac development profile that includes this Mac (automatic signing with -allowProvisioningUpdates registers the Mac and makes it). Builds without it keep working with keys on the Mac only and say so. iCloud Keychain sync between the two apps was not exercised end to end (no provisioned Mac build or device yet). The CLI's file vault supports Secure Enclave and device keys only.
  • Mac LAN: the unsigned CLI's link listener was verified on loopback only; LAN connections likely need the signed app's Local Network permission.
  • Real Touch ID / Face ID prompts and Secure Enclave keys with user presence were exercised only in the Simulator (tests elsewhere use --access none and an explicit test approval mode).
  • OpenPGP is an in-house v4 implementation over CryptoKit (validated against GnuPG, not a maintained OpenPGP library); gpgsm cannot verify Ed25519 CMS signatures.
  • With keys on the iPhone, the Mac keeps only its link identity and pairings, in ~/.keythra/link-vault: bound to the Mac's Secure Enclave but without Touch ID, so Keythra starts at login without a prompt (the phone approves every use). Pairings made before this change must be made again.
  • The Mac file vault authenticates key metadata but cannot prevent rollback (restoring an older copy of a vault file); keep the vault on the iPhone (keychain) where that matters.
  • On the Mac, the Touch ID prompt is the approval screen; requests with more detail than it can show in full (a 1200-character budget, not yet checked against the real dialog's layout) are refused there and must be approved on the iPhone.
  • SSH login keys set to "never asks" skip the prompt only on connections bound directly to the destination (OpenSSH 8.9+ session-bind); forwarded or unbound requests always prompt. SSH signing and SSH CA keys set to "never asks" sign or issue certificates for any local process (or paired Mac) without a prompt. FIDO credentials marked with keythra fido allow-silent answer silent (no user presence) requests without a prompt. Everything else always prompts, so the app offers "never ask" only for the three SSH purposes.
  • OpenPGP decryption stops at 64 MiB of plaintext by default (keythra pgp decrypt --max-size, up to 1 GiB).
  • Artifact signing: cosign signs images with Ed25519ph, which Keythra cannot make (Ed25519 keys sign blobs only, and cosign 3.1 verifies those only from --new-bundle-format=false --output-signature); P-384 signatures need --signature-digest-algorithm sha384 when verifying (cosign's own behaviour). The Notation plugin makes JWS signatures only (not COSE); notation blob needs Notation 2 and was not tested (Homebrew has 1.3). Attestations (cosign attest) are shown by predicate type and subjects; the predicate itself is not shown.
  • Nostr: every signature, encryption and decryption asks (no "never ask"), so apps that decrypt many DMs prompt once per message. The bunker runs only while the Mac bridge runs; its transport key and app list live in ~/.keythra/link-vault (no Touch ID, like the pairings). App names and URLs are the apps' own claims. Events with control characters other than tab and line breaks are refused (implementations serialize them differently). NIP-44 plaintexts are limited to 65535 bytes (the published vectors), and the relay must be wss:// (ws:// on localhost only). Request replay protection is in memory: within 10 minutes of a request, a relay replaying it after a bridge restart causes one more prompt (the answer is encrypted to the app). Tested with nak and a go-nostr client on a local relay, with the key on the Mac and on the phone simulator (keythra link run-authenticator); not yet with the iOS app on a device or a GUI Nostr client.
  • OpenPGP card (keythra-scdaemon): run gpg --card-status once after importing a key or changing slots. Until then gpg-agent 2.5 cannot decrypt with an ECC card key (it passes a binary keygrip to READKEY); RSA works. Authentication subkeys are only created with a new key (--authentication-subkey). There is no cardholder data, on-card key generation or key import. The signature counter counts the card's own signatures only. The approval cannot show what is signed or decrypted, or which program asked gpg-agent.
  • Smart card: the token extension and its app group need the signed Mac app (any team; no provisioning profile). Tested with Debug builds signed with an Apple Development certificate and registered with pluginkit -a (an app installed in /Applications should be discovered without it; not tried, nor a notarized Developer ID build). It offers PKCS#11-enabled P-256, P-384 and RSA keys that have a certificate (not Ed25519); RSA keys sign or decrypt (PKCS#1 v1.5, OAEP SHA-1/256), EC keys only sign, so S/MIME decryption with EC certificates (ECDH) does not work. macOS does not tell a token which app is asking, so approvals say "not identified" and cannot show what is signed. Only the key you mark "Unlock your Mac with this key" is offered for macOS login (see below). macOS publishes the token's items in the keychain only while the login keychain is unlocked. Verified with the Security framework, URLSession, openssl s_server and codesign; Safari, Chrome, Mail S/MIME and Kerberos PKINIT were not exercised by hand, and the token was not tested with the app in iPhone mode (the application firewall asks before the signed app may accept the phone's connection; the same requests through keythra daemon --authenticator remote and a phone simulator are tested).
  • Unlocking the Mac with the iPhone is untested at a real lock screen. Apple documents token login for smart cards. For tokens an app provides ("persistent tokens"), Apple DTS says they can't be used at the login window, and says nothing about the lock screen.
    • What was verified, with a tagged test build: the token offers the login key, sc_auth identities lists it as unpaired, and it signs only after the PIN. The PIN was handed over as an LAContext smart-card PIN credential, the credential type macOS's lock-screen code appears to use. A wrong PIN is refused and counted once.
    • The paired-phone simulator approved with the unlock wording.
    • sc_auth identities lists every Keythra certificate key, not only the login key, so pair only the hash the Unlock window shows.
    • The login keychain is unlocked with the login key's keychain key (ECDH). Verified through the token the way macOS's token login unwraps the keychain password (ECIES with the certificate's public key, then decryption through the token), and on the phone simulator; not yet with a real pairing. Keys marked before the keychain key existed need Add Keychain Key and a new sc_auth pair.
    • Unlock PINs are 4–8 digits, the token's PIN format.
    • The key is offered only while the iPhone is connected, so an iPhone out of reach means the password field.
    • Steps and undo: docs/mac-unlock-test-plan.md.
  • Reviewed by independent AI review agents (findings fixed, see docs/build-plan.md §7); no human security audit.
  • Browser extension: WebAuthn in iframes stays with the browser (the extension serves top-level documents only). Tested with Chrome for Testing (branded Chrome ignores --load-extension, so tests cannot load it there), Brave 1.96 and Firefox 157 in temporary profiles; Edge, Opera, Arc, Vivaldi, Dia, Comet, Thorium, Helium and the Firefox forks are expected to work from their documented or observed manifest locations but were not run. Brave, Opera and Arc read manifests from Chrome's directory, so they share Chrome's manifest. The native host talks to ~/.keythra (or $KEYTHRA_HOME from the browser's environment). PRF evalByCredential is honoured for a single allowed credential; with several, only results for a credential without its own entry are returned. The in-page panel can be covered or hidden by the page; it is a convenience, not the approval.
  • Safari on the Mac was verified with the Safari build running in WebKit's Web Extensions engine (WKWebExtension) and a harness standing in for Safari's hand-off to the extension's handler, through a test instance of the app; turning it on in Safari's settings, Safari's per-site permission prompt and Safari's own native-message delivery were not exercised (that needs your Safari settings). Safari runs the extension only on sites you allow. Opaque-origin (sandboxed) documents are refused by the content scripts, since Safari reports a frame's URL origin to the extension. Keythra.app's bundled tools are built for the Mac's own architecture.
  • Safari on iPhone: verified in the iOS Simulator only. Face ID from the extension's handler, and Secure Enclave keys made there, still need a check on a device (the Simulator gets software keys). Its security keys are separate from the Mac bridge's and have no backup (register a second key). Cancelling from the page reaches a request only within the same extension process, and these uses do not appear in the app's Activity log (no shared container). A device build registers the extension's App ID (io.github.gmkbenjamin.keythra.safari-extension) with -allowProvisioningUpdates.
  • Firefox keeps only Mozilla-signed add-ons in release builds; nothing here signs or publishes the extension (sign-firefox.sh does it with your AMO key). Orion starts native hosts but drops their replies, so it cannot use the extension yet; DuckDuckGo takes no extensions; Tor and Mullvad Browser are deliberately not set up.

About

Keythra: iPhone as your security key — SSH, Git signing, FIDO2/WebAuthn, smart card, OpenPGP card, cosign, Nostr — with a macOS bridge

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages