Linux package repository

Linux Passkey

Windows Hello-style passkeys for Linux: create and use passkeys on any website, confirmed with your Linux password or fingerprint.

Install

Add the repository

First time installing from packages.akileswar.com? Set up the signing key once, then:

Debian 13+, Ubuntu 24.04+, Mint, Pop!_OS apt

Signed with the site's key: set it up for apt

echo "deb [signed-by=/usr/share/keyrings/akileswar-packages.gpg] https://packages.akileswar.com/linux-passkey/apt stable main" | sudo tee /etc/apt/sources.list.d/linux-passkey.list
sudo apt update && sudo apt install linux-passkey gnome-shell-extension-linux-passkey

Fedora 41+, RHEL, Alma, Rocky 10 dnf

Signed with the site's key: set it up for dnf · zypper

sudo curl -fsSL https://packages.akileswar.com/linux-passkey/rpm/fedora/linux-passkey.repo -o /etc/yum.repos.d/linux-passkey.repo
sudo dnf install linux-passkey gnome-shell-extension-linux-passkey

openSUSE Tumbleweed zypper

Signed with the site's key: set it up for dnf · zypper

sudo zypper addrepo https://packages.akileswar.com/linux-passkey/rpm/opensuse/linux-passkey.repo
sudo zypper install linux-passkey gnome-shell-extension-linux-passkey

Arch, Manjaro, EndeavourOS pacman

Signed with the site's key: set it up for pacman

printf '\n[linux-passkey]\nServer = %s\n' https://packages.akileswar.com/linux-passkey/arch | sudo tee -a /etc/pacman.conf
sudo pacman -Sy linux-passkey gnome-shell-extension-linux-passkey
systemctl --user enable --now linux-passkey.service

Afterwards

Start using it

Log out and back in. On GNOME, turn on the shell extension:

gnome-extensions enable passkey@haythmkenway.github.io
  • Until the browser extension is in the stores, load it unpacked from /usr/share/linux-passkey/browser-extension.
  • Updates arrive with the rest of the system.

About

Linux Passkey

Linux Passkey: a website asks to create a passkey, and you approve it with your Linux password or fingerprint

Windows Hello-style passkeys for Linux.

Create and use passkeys on any website, confirmed with your Linux password or fingerprint.
No phone, no hardware key, and no "partial passkey support" warnings.

Install · Using it · Contributing · Support the project

Linux Passkey makes your computer a built-in passkey authenticator, like Windows Hello on Windows or Touch ID on a Mac. Browsers have no such feature on Linux, so a small browser extension hands passkey requests to the Linux Passkey service, which asks you to approve them and confirm with your password or fingerprint. Websites then see a computer that supports passkeys fully.

It comes in these pieces; one install brings the service and the app, and the extensions are one click each:

Piece What it does
linux-passkey (service and app) The passkeyd authenticator service, the Passkeys manager app, and an approval window
Linux Passkey browser extension Makes Chrome, Chromium, Brave, Edge, Vivaldi, Firefox and their relatives use the service as a built-in authenticator
gnome-shell-extension-linux-passkey (optional) Approval prompts as GNOME Shell system dialogs, and a Passkeys menu in the top bar

Without the GNOME extension, approval prompts open in a window of their own, so Linux Passkey works on KDE, Xfce and other desktops too.

GNOME Shell prompt for creating a passkey GNOME Shell prompt for choosing an account

The Passkeys app Fallback approval window

Features

  • A built-in authenticator in every major browser: through the browser extension, sites see a user-verifying platform authenticator, as on Windows and macOS. Requests meant for something else (a hardware security key, a phone, a site you have no passkey for here) go to the browser's own dialog unchanged.
  • Also a USB security key (distribution packages and source installs): browsers without the extension see the computer as a plugged-in FIDO2 key.
  • Passkeys and regular security-key logins: supports discoverable credentials (passkeys, username-less sign-in) and non-discoverable credentials (second factor), with no limit on how many you store.
  • CTAP 2.1: built-in user verification through pinUvAuthToken (protocols 1 and 2), credential management (so browsers' security key settings can list, rename and delete passkeys), credProtect, hmac-secret (so the WebAuthn PRF extension works), ES256 and EdDSA keys, account selection, and authenticatorSelection. See docs/COMPLIANCE.md for the standards audit.
  • Identity verification uses your system login: polkit shows GNOME's own authentication dialog. It accepts your password, or your fingerprint if you have enabled fingerprint login.
  • Encrypted at rest: private keys are wrapped with AES-256-GCM under a master key kept in your login keyring. The metadata file is encrypted too.
  • The Passkeys app: search, inspect and delete passkeys, see the service status, require verification every time, and reset everything.

Install

Signed repositories for every major distribution family are at packages.akileswar.com/linux-passkey, so updates arrive with the system's own. Each release also has the packages to download.

Debian 13+, Ubuntu 24.04+, Mint, Pop!_OS

curl -fsSL https://packages.akileswar.com/linux-passkey/linux-passkey.gpg | sudo tee /usr/share/keyrings/linux-passkey.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/linux-passkey.gpg] https://packages.akileswar.com/linux-passkey/apt stable main" | sudo tee /etc/apt/sources.list.d/linux-passkey.list
sudo apt update && sudo apt install linux-passkey gnome-shell-extension-linux-passkey

Ubuntu Desktop kernels include the uhid module. Minimal and server installs (the linux-image-virtual kernel) keep it in linux-modules-extra; the package warns at install time if it is missing:

sudo apt install linux-modules-extra-$(uname -r)

Fedora 41+, RHEL 10, AlmaLinux 10, Rocky Linux 10

sudo curl -fsSL https://packages.akileswar.com/linux-passkey/rpm/fedora/linux-passkey.repo -o /etc/yum.repos.d/linux-passkey.repo
sudo dnf install linux-passkey gnome-shell-extension-linux-passkey

openSUSE Tumbleweed

sudo zypper addrepo https://packages.akileswar.com/linux-passkey/rpm/opensuse/linux-passkey.repo
sudo zypper install linux-passkey gnome-shell-extension-linux-passkey

Arch Linux, Manjaro, EndeavourOS

curl -fsSL https://packages.akileswar.com/linux-passkey/linux-passkey.asc -o /tmp/linux-passkey.asc
sudo pacman-key --add /tmp/linux-passkey.asc && sudo pacman-key --lsign-key 392A1EEB594EC9FB0300BC66A1AE3F549366D3D9
printf '\n[linux-passkey]\nServer = https://packages.akileswar.com/linux-passkey/arch\n' | sudo tee -a /etc/pacman.conf
sudo pacman -Sy linux-passkey gnome-shell-extension-linux-passkey
systemctl --user enable --now linux-passkey.service

The recipe is packaging/arch/PKGBUILD for building it yourself.

Then

Log out and back in. This lets udev give your session access to /dev/uhid and starts the service. Then turn on the GNOME extension:

gnome-extensions enable passkey@haythmkenway.github.io

From source

The dependencies, by family:

sudo apt install python3-gi python3-cryptography gir1.2-gtk-4.0 gir1.2-adw-1 gir1.2-secret-1 publicsuffix   # Debian, Ubuntu
sudo dnf install python3-gobject python3-cryptography gtk4 libadwaita libsecret publicsuffix-list           # Fedora
sudo pacman -S python-gobject python-cryptography gtk4 libadwaita libsecret publicsuffix-list               # Arch

Then:

sudo make install            # installs to /usr/local (udev/systemd/polkit files go to /usr)
sudo modprobe uhid && sudo udevadm control --reload-rules && sudo udevadm trigger
systemctl --user daemon-reload && systemctl --user enable --now linux-passkey.service
gnome-extensions enable passkey@haythmkenway.github.io   # after logging in again

make deb, make rpm and makepkg in packaging/arch build the distribution packages; tools/make-repo.sh builds the signed repositories from them, and CI does both for each release.

The browser extension

The service registers the extension's native messaging host with every browser it finds each time it starts, so the extension needs no setup beyond installing it. Until it is on the Chrome Web Store and Firefox Add-ons:

  • Chrome, Chromium, Brave, Edge, Vivaldi: open chrome://extensions (brave://extensions, edge://extensions), turn on Developer mode, choose Load unpacked and pick /usr/share/linux-passkey/browser-extension (from a source install: /usr/local/share/linux-passkey/browser-extension).
  • Firefox and its relatives: make browser-extension-zip builds dist/linux-passkey-firefox-*.zip; load it from about:debugging → This Firefox → Load Temporary Add-on.

Just the GNOME extension

make extension-zip builds dist/passkey@haythmkenway.github.io.shell-extension.zip for extensions.gnome.org or for gnome-extensions install. It needs the linux-passkey service.

Using it

  1. On a website, choose Create a passkey (on some sites this is under Security → Passkeys / Security keys).
  2. Approve the "Create a Passkey?" prompt, then confirm with your password or fingerprint.

Without the browser extension, the browser asks where to save the passkey first: choose USB security key (also shown as "security key" or "external security key").

To sign in, choose Sign in with a passkey and approve the prompt. If you have several accounts on the site, pick one in the prompt.

Open Passkeys from the app grid to view or delete passkeys. Deleting a passkey revokes it straight away.

How it works

 Browser + extension ──native messaging──▶ native host ──D-Bus──┐
                                                                ▼
 Browser ──WebAuthn/CTAP2 over HID──▶ /dev/hidrawN ◀── kernel uhid ──▶ passkeyd (user service)
                                                                        │  CTAPHID framing, keepalive, cancel
                                                                        │  CTAP2 authenticator
                                                                        │  encrypted credential store ◀─ master key in login keyring
                                                                        │  polkit (pkcheck) ─▶ password / fingerprint dialog
                                                                        └─ D-Bus io.github.haythmkenway.Passkey.Daemon
                                                                               ▲                      ▲
                                                           GNOME Shell extension (prompts)    Passkeys app (management,
                                                                                              fallback prompt window)
  • Browser extension: replaces navigator.credentials.create() and get() in each page and reports a user-verifying platform authenticator. Its background script takes each request's origin from the browser's record of the sending page, never from the page itself, and passkeyd acts as the WebAuthn client: it builds clientDataJSON from that origin and checks that the requested RP ID is the origin's host or a registrable suffix of it, using the Public Suffix List. A page can therefore only get signatures for its own site, as with the browser's own WebAuthn. Requests the extension leaves to the browser: security-key or phone hints, sign-ins with no passkey stored here, conditional (autofill) requests and cross-origin frames.
  • Transport: passkeyd creates a virtual HID device with the FIDO usage page through /dev/uhid. systemd's 60-fido-id.rules recognizes it as a security token and grants the logged-in user access, as it would for a hardware key.
  • Credentials: every credential ID is self-contained. It holds the private key encrypted with a key derived from the master key and bound to the site's RP ID hash. Discoverable credentials also have a metadata record (site, account name, user handle) in ~/.local/share/linux-passkey/credentials.enc, which is also encrypted. Discoverable credentials are only honored while their record exists, so deleting one really revokes it.
  • User presence is an explicit approval in the prompt. User verification is polkit action io.github.haythmkenway.passkey.verify (auth_self, never cached).
  • Attestation: packed self-attestation (no vendor certificate). AAGUID 5a5b2c1e-6f3d-4b7a-9c2e-8d1f0a3b4c5d.

Files

Path Purpose
~/.local/share/linux-passkey/credentials.enc Encrypted passkey metadata and signature counter
~/.local/share/linux-passkey/key-backend Where the master key lives (keyring or file)
Login keyring item "Linux Passkey master key" The 256-bit master key (or master.key, mode 0600, when no keyring exists)
~/.config/linux-passkey/config.json Settings

Back up your login keyring and ~/.local/share/linux-passkey together. Neither works without the other. Passkeys are not synced to other devices.

Security notes

  • Passkeys are protected the same way as other secrets in your session (browser passwords, SSH keys in the keyring). Malware running as your user could talk to the session bus or read the keyring after you log in, so it could misuse them. Hardware security keys protect against that; this project does not.
  • The udev rule gives the user at the local seat access to /dev/uhid (TAG+="uaccess"). uhid can create any kind of HID device, keyboards included. That is a broader permission than this project strictly needs.
  • Only agents registered on the session bus (the extension or the fallback window started by the service) can answer approval prompts. Approving still needs a deliberate click, and verification goes through polkit.

Known limitations

  • The browser extension is needed for the built-in experience. Without it, browsers on Linux show Linux Passkey as a USB security key, because they have no platform-authenticator API. The credentialsd project is working on one for the Linux desktop.
  • Passkey autofill (conditional mediation) still goes to the browser, so passkeys stored here are not listed in the sign-in field's suggestions; use the site's Sign in with a passkey button.
  • Snap-packaged browsers and the USB key. The snap u2f-devices interface only exposes hidraw devices whose USB IDs are on snapd's allow-list. The virtual key reports the pid.codes test ID 1209:0001 by default, which may not be on that list. If a snap browser does not see the key, use the browser's .deb or Flatpak build. passkeyd --usb-id VID:PID changes the reported ID. Getting a registered ID onto the list is planned.
  • U2F/CTAP1 (CTAPHID_MSG) is not implemented. All current browsers use CTAP2.
  • No client PIN: user verification is always your system login (password or fingerprint).
  • Passkeys are device-bound (the WebAuthn backup eligible flag is not set) and are not synced. There is deliberately no export feature, because an exportable credential would have to be reported as backup-eligible.

Troubleshooting

systemctl --user status linux-passkey.service
journalctl --user -u linux-passkey.service -f
passkeyd --verbose          # run in the foreground (stop the service first)
  • "permission denied opening /dev/uhid": install the package's udev rule, then log out and back in. Check with getfacl /dev/uhid.
  • "/dev/uhid not found": run sudo modprobe uhid. If the module is missing, install linux-modules-extra-$(uname -r) (Debian, Ubuntu) or kernel-modules-core-$(uname -r) (Fedora); if the kernel was just updated, restart.
  • "Your passkeys cannot be opened": the login keyring is locked or unavailable, or the passkey file cannot be decrypted. Unlock the keyring and choose Try Again. Delete All Passkeys… starts over and keeps the unreadable file aside as credentials.enc.unreadable-<time>.
  • The browser doesn't see a security key: check that ls -l /dev/hidraw* lists a device your user can access. If you use a snap browser, see the limitations above.
  • No verification dialog appears: a polkit authentication agent must be running. GNOME Shell provides one.

Development

make check        # unit, CTAPHID, D-Bus, fuzz and end-to-end WebAuthn tests (python-fido2 client + server)
make lint         # pyflakes, ESLint, desktop-file, AppStream and polkit validation
make pot          # regenerate po/linux-passkey.pot for translators
make deb          # build the Debian packages into ../

Translations

Translations live in po/. To add a language, run msginit -i po/linux-passkey.pot -o po/<lang>.po -l <lang>, translate it, and add the language code to po/LINGUAS. The same catalog serves the app and the GNOME extension.

The end-to-end tests drive the authenticator with python-fido2's WebAuthn client and verify the results with its server implementation. That covers registration, sign-in, PRF/hmac-secret, exclude lists, cancellation, deletion and reset.

D-Bus API

Bus name io.github.haythmkenway.Passkey.Daemon, object /io/github/haythmkenway/Passkey/Daemon, interface io.github.haythmkenway.Passkey1:

Member Description
RegisterAgent(), UnregisterAgent() Become or stop being an approval-prompt agent
Respond(u id, b approved, i choice) Answer a prompt (registered agents only)
GetPendingRequests() → a(usssasb) Prompts waiting for an answer
ListCredentials() → aa{sv}, DeleteCredential(s id) → b Manage passkeys
ResetAll() → b Delete everything (requires verification)
Retry() Try to open the passkey storage again (after unlocking the keyring)
WebAuthnCreate(s origin, s top_origin, s options, s handle) → s, WebAuthnGet(…) → s navigator.credentials.create() / get() with WebAuthn JSON options and results; errors are io.github.haythmkenway.Passkey.WebAuthn.<DOMException name>
WebAuthnHasCredentials(s origin, s options) → b, WebAuthnCancel(s handle) Whether a sign-in could use a passkey stored here; cancel a ceremony this caller started
GetStatus() → a{sv}, GetSettings() → a{sv}, SetSetting(s, v) Status (state is starting, ready or error) and settings. Only always_verify and approval_timeout can be set over D-Bus
signal ApprovalRequested(u id, s operation, s rp_id, s rp_name, as accounts, b verify) A prompt should be shown
signal ApprovalClosed(u id) A prompt was answered, cancelled or timed out
signals CredentialsChanged, StatusChanged Refresh hints

Contributing

Bug reports, test results from your distribution and browser, translations and code are all welcome.

  • Report a problem: open an issue with your distribution, desktop, browser, how you installed Linux Passkey, and the output of journalctl --user -u linux-passkey -b | tail -50.
  • Send a change: fork the repository, make your change on a branch, run make check and make lint, and open a pull request. Add a test for every fix; CI runs the suite on Ubuntu 22.04 and 24.04 and builds the packages.
  • Translate: see Translations.
  • Security issues: please report them privately through GitHub's security advisories rather than in a public issue.

Support the project

Linux Passkey is free and open source, made in spare time. If it helps you, a donation keeps it going.

PayPal paypal.me/0x4kil
UPI akileswar2002@oksbi
Bitcoin 13pu8fvcNt6Rx8tXJGfFDVWf59uhZuaFEp

UPI QR code for akileswar2002@oksbi   Bitcoin QR code for 13pu8fvcNt6Rx8tXJGfFDVWf59uhZuaFEp

License

GPL-3.0-or-later. See LICENSE.

From README.md at v0.1.0.