No description
  • Zig 91.9%
  • Shell 8.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-03-01 23:09:36 +01:00
script added creation of passkeez.service file to script 2026-02-14 10:39:19 +01:00
src implemented pin change 2026-02-16 00:55:51 +01:00
static changed image 2026-03-01 23:06:13 +01:00
.gitignore added install instructions to readme 2026-02-14 11:50:05 +01:00
build.sh initial commit 2026-02-07 13:10:49 +01:00
build.zig initial commit 2026-02-07 13:10:49 +01:00
build.zig.zon initial commit 2026-02-07 13:10:49 +01:00
README.md fixed minor inconsistencies 2026-03-01 23:09:36 +01:00

PassKeeZero

PassKeeZ for the Raspberry Pi Zero 2 W.

This is a research project! Use at your own risk!

This project turns a Raspberry Pi Zero 2 W into a FIDO2 (Passkey) capable authenticator with the following features:

  • Authenticator uses always UV, i.e. a PIN is required for most operations.
  • Secrets are stored in a .kdbx password database file (same as KeePass, KeePassXC, etc.). The PIN hash (left(SHA256(PIN), 16)) is used to unlock the database.
  • To configure the authenticator visit chrome://settings/securityKeys with a chrome based browser.

Getting Started

To get started, you need a Raspberry Pi Zero 2 W and a SD card.

Raspberry Pi Zero 2 W

There are two ways to setup you Raspberry Pi. You can either run the authenticator on a plain OS or provision your Raspberry Pi with full disk encryption (fde). Unfortunately, secure boot is not supported for Zero 2 W devices.

If you run into any problems, please consider opening an issue.

With FDE

https://github.com/raspberrypi/rpi-sb-provisioner

Comming Soon!

Without FDE

If you just want to test out this project or don't have the required hardware for provisioning available, you can proceed with a plain installation.

Setup the Raspberry Pi

  1. Download and install the Raspberry Pi Imager.
  2. Flash a image on your SD card
    • Device: Raspberry Zero 2 W
    • OS: Raspberry Pi OS (Other) -> Raspberry Pi OS Lite (64 Bit)
    • Storage: <Your SD Card>
    • You also need to provide SSID and password (or a key) for your local network so you can connect to the device using SSH.
  3. After flashing an OS on the SD card, insert it into your Raspberry Pi and connect the Raspberry to a power source.
  4. After the Raspberry has booted, you should be able to SSH into the device: ssh passkeez@10.252.11.209 (assuming passkeez is the username and 10.252.11.209 is the IP address. You can also specify the hostname you configured via the imager instead of an IP address.).

After setting up the Raspberry Pi, you can now proceed to setting up the authenticator.

Creating a Database

Note: This step should be covered by the installer in the future.

Next you need a .kdbx database for your credentials. The easiest way is to create one using a password manager like KeePass or KeePassXC.

As master password, select a secure password and then calculate its SHA-256 hash, e.g. echo -n "12345678" | sha256sum. The take the first 16 bytes as a password. This is necessary, as the CTAP2 protocol uses only the PIN hash (left(SHA256(PIN), 16)) for authentication.

$ echo -n "12345678" | sha256sum
ef797c8118f02dfb649607dd5d3f8c7623048c9c063d532cc95c5ed7a898a64f

The password would then be: ef797c8118f02dfb649607dd5d3f8c76.

You also need to lower the settings for the key derivation function, e.g. Argon2d as the Raspberry Pi Zero 2 W is much slower. You can later play with these settings and adjust them to your liking, but the following ensures a reasonably fast en-/decryption:

  • Transform Rounds: 22
  • Memory Usage: 4 MiB
  • Parallelism: 1

You can always increase these settings but this will also increase the time it will take to open the database.

After you've created the database, copy it to your Raspberry Pi via scp, e.g. scp /path/to/db.kdbx passkeez@10.252.11.209:/home/passkeez. You can place this file wherever you want but you've to manually adjust the path to the database file in /etc/passkeez/config.json after the file has been created in the next step. The default is /etc/passkeez/db.kdbx, i.e. you could just move the file to this location.

Copy the Executable

The next step is to copy the executable passkeez_zero to /usr/bin on the Raspberry Pi. You can either use a pre-built executable or build it from source by running: zig build -Dtarget=aarch64-linux-gnu -Doptimize=ReleaseSmall and then using the file located in ./zig-out/bin/.

  1. SCP the file to the Raspberry Pi: scp ./zig-out/bin/passkeez_zero passkeez@10.252.11.209:/home/passkeez
  2. Move the file to /usr/bin on the Raspberry:
    • ssh passkeez@10.252.11.209
    • sudo mv passkeez_zero /usr/bin

Copy the Installer Script and Execute It

Last but not least, you have to copy the installer script script/install.sh to the Raspberry, e.g. scp script/install.sh passkeez@10.252.11.209:/home/passkeez. Then SSH into the Raspberry and run sudo ./install.sh. After that you should have a fully functional authenticator.

You can test it on platforms like passkey.org.