Skip to content

About

Virtual FIDO2 authenticator using ML-DSA 44/65/87 and ES256 algorithms with CTAP 2.3 and UHID implementations written Rust.

Topics

Resources

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

pqkey

A FIDO2 security key in software for Linux, with post-quantum ML-DSA passkeys.

CI E2E Security License: MIT

pqkey shows up in your browser as an ordinary USB security key. A user daemon creates a virtual HID device through the kernel's uhid driver, so any FIDO2 client can use it, and asks you to approve, in a desktop notification, each registration, reset and sign-in that needs your presence.

  • Post-quantum: ML-DSA-44, ML-DSA-65 and ML-DSA-87 (FIPS 204), alongside ECDSA (NIST, secp256k1 and Brainpool curves), EdDSA (Ed25519 and Ed448) and RSA-2048.
  • CTAP 2.3 and U2F: PIN, passkeys and their management, always-UV, PIN policies, large blobs, PRF (hmac-secret) and the other standard extensions.
  • Rust throughout: pure-Rust cryptography, and unsafe code only where pqkey calls the operating system and in the allocator that wipes freed memory.

Warning

pqkey is a research project, not for production use. A software key is not a hardware key: its private keys are files in your home directory, which anything running as you, or as root, can use. See SECURITY.md.

Install

You need Linux with systemd and the uhid module (Ubuntu, Debian and Fedora have it), and a desktop whose notifications show request text and support approval actions (GNOME, KDE Plasma or Dunst). Then run:

git clone --branch stable https://github.com/rainzhang05/SoftwareAuthenticator.git && SoftwareAuthenticator/install.sh

stable is the newest commit on main that passed CI, E2E and Security. The installer builds and installs pqkey, starts it as a systemd user service and asks you to choose a PIN. It says "pqkey is ready" once the key works, and otherwise what to fix; the user guide has the details.

Use

Register pqkey on any site that supports passkeys or security keys, and approve the notification that appears; the user guide says how on each desktop, Dunst included.

Command What it does
pqkey Shows the key's status, and a fix for each problem it finds
pqkey pin Sets or changes the PIN
pqkey config Shows or changes always-UV and the PIN policy
pqkey passkeys Lists passkeys; pqkey passkeys delete QUERY deletes one
pqkey repair Repairs a damaged credential store, with the key stopped
pqkey reset Erases every credential, large blob and the PIN
pqkey stop, pqkey start Unplugs and plugs in the key

The key keeps its state in ~/.local/share/pqkey. If something does not work, run pqkey and follow the fix it names; the user guide covers the rest.

Update

Stop the key with pqkey stop, back up ~/.local/share/pqkey, keys/ included, and run git pull && ./install.sh in the clone (switch a clone of main to stable first: git fetch origin && git switch stable). Updates keep your passkeys, PIN and policy, and ask for a PIN only if the policy requires a new one.

Recovery: if setup fails after an update, the previous executable stays at /usr/local/bin/pqkey.previous, and the installer says how to retry or restore it. Restore it alone only if it reads the store's current format; otherwise restore your backup with it, losing the credentials created since.

Uninstall

pqkey setup --uninstall

This stops the key and removes its service, then prints one sudo command that removes pqkey, its udev rules and the uhid setting. Your passkeys stay in ~/.local/share/pqkey until you delete that directory.

Documentation

  • User guide: installing, approving requests, the PIN policy, passkeys, browsers, troubleshooting and repair
  • SECURITY.md: the threat model, and how to report a vulnerability
  • Architecture: how pqkey works, and what it supports of CTAP 2.3
  • Development notes: building, testing and releasing pqkey

License

pqkey is free software under the MIT License, with no warranty.

About

Virtual FIDO2 authenticator using ML-DSA 44/65/87 and ES256 algorithms with CTAP 2.3 and UHID implementations written Rust.

Topics

Resources

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Contributors

Languages