Hardware Authentication

Security 2026-08-28

Shani OS ships with hardware authentication plumbing out of the box — fingerprint readers, FIDO2/U2F tokens, smart cards (PIV), and NFC tokens all work without a driver download, via packages pulled in by the shani-peripherals package. The CLI utilities for YubiKey management, PC/SC diagnostics, and TOTP/HOTP codes are not part of the default image — because Shanios is immutable, they cannot be installed with pacman at runtime. Install them via Nix (nix-env -iA nixpkgs.<pkg>) or run them inside a Distrobox container — see the callout in each section below.

Fingerprint Authentication

Package: fprintd (pulls in libfprint as a dependency) — pre-installed via shani-peripherals

Fingerprints can be used to unlock the login screen, sudo prompts, and the lock screen.

# Enroll a finger (replace 'right-index-finger' with the finger you want)
fprintd-enroll -f right-index-finger

# List enrolled fingers
fprintd-list "$USER"

# Test a fingerprint
fprintd-verify

# Delete enrolled fingers
fprintd-delete "$USER"

Enrollment via GUI: System Settings → Users → Fingerprint Login (KDE) or Settings → Users (GNOME).

Supported Hardware

Any fingerprint reader with a libfprint driver is supported. Check compatibility:

# Is your device recognised?
lsusb | grep -i finger
fprintd-enroll   # will fail with a clear error if the device is unsupported

YubiKey and FIDO2/U2F

Packages: libfido2, pam-u2f — pre-installed via shani-peripherals. yubikey-manager (the ykman CLI used below) is not part of the default image and cannot be installed on the immutable host with pacman. Install it via Nix instead:

nix-env -iA nixpkgs.yubikey-manager

These CLI tools can also run inside a Distrobox container if you prefer not to install them on the host.

⚠️ Before editing PAM: keep an existing root shell open when editing PAM files, and test sudo in a second terminal before logging out. A broken PAM stack can lock you out of sudo and login entirely.

# 1. Create the U2F key mapping directory
mkdir -p ~/.config/Yubico

# 2. Register your YubiKey (touch the key when it blinks)
pamu2fcfg > ~/.config/Yubico/u2f_keys

# If you have a second key for backup, append it
pamu2fcfg -n >> ~/.config/Yubico/u2f_keys

Edit /etc/pam.d/sudo to require the YubiKey in addition to the password:

auth required pam_u2f.so

Or to allow either password or YubiKey:

auth sufficient pam_u2f.so

YubiKey Manager

# Show YubiKey info
ykman info

# List configured applications
ykman list

# Configure FIDO2 PIN
ykman fido access change-pin

# Reset FIDO2 application (clears all credentials)
ykman fido reset

FIDO2 for SSH

# Generate a FIDO2-backed SSH key (resident key stored on the YubiKey)
ssh-keygen -t ed25519-sk -O resident -O application=ssh:myserver

# Non-resident (key file required alongside the token)
ssh-keygen -t ed25519-sk

Smart Card / PIV

Packages: opensc, ccid, acsccid — pre-installed via shani-peripherals; pcscd/pcsc-lite come along transitively as a dependency of opensc/ccid. The pcsc-tools diagnostic package (used for pcsc_scan below) is not part of the default image and cannot be installed on the immutable host with pacman — install it via Nix:

nix-env -iA nixpkgs.pcsc-tools

Or run it inside a Distrobox container.

# Start the PC/SC daemon
sudo systemctl enable --now pcscd

# List connected smart cards
pcsc_scan

# Show card info via OpenSC
opensc-tool --list-readers
opensc-tool --list-algorithms

# List certificates on a PIV card
pkcs11-tool --module /usr/lib/opensc-pkcs11.so --list-certificates

SSH with Smart Card

# List keys visible via PKCS#11
ssh-keygen -D /usr/lib/opensc-pkcs11.so -e

# Use the card for SSH authentication
ssh -I /usr/lib/opensc-pkcs11.so user@host

NFC Authentication

Packages: libnfc, pre-installed via shani-peripherals; NFC access rides on the same pcscd/pcsc-lite stack pulled in for smart cards above

NFC tokens are accessed via the PC/SC stack. Once pcscd is running, NFC cards compatible with pcsc-lite are accessible in the same way as contact smart cards:

sudo systemctl enable --now pcscd
pcsc_scan   # shows NFC card when tapped

TOTP / HOTP (Two-Factor)

Package: oath-toolkit — not part of the default image and cannot be installed on the immutable host with pacman. Install it via Nix:

nix-env -iA nixpkgs.oath-toolkit