Securing Linux Authentication with Immurok Wireless Fingerprint Device

After reading this guide, the reader will be able to integrate an Immurok wireless fingerprint reader into a Linux workstation, configure PAM for desktop unlock, sudo and polkit approvals, set up SSH key storage, enable TOTP generation, and understand the security implications of each feature.

Understanding Immurok’s Authentication Model

Immurok is a compact Bluetooth Low Energy (BLE) peripheral that stores biometric templates, SSH private keys, and a secret for Time‑Based One‑Time Password (TOTP) generation. All cryptographic material remains on the device; the host never receives raw fingerprint data or private keys. Pairing uses a P‑256 Elliptic Curve Diffie‑Hellman exchange protected by HMAC‑SHA256, and each authentication response is signed with the device’s private key. The host validates the signature before granting access.

The device presents itself to the operating system through three integration points:

• PAM module – invoked for local login, screen unlock, sudo, and any Polkit‑protected action.
• SSH agent shim – supplies an SSH private key stored on the device when the user requests a remote connection.
• TOTP daemon – returns a one‑time password after a successful fingerprint verification.

Because the device communicates over BLE, the host must maintain a trusted Bluetooth pairing. The pairing process is performed once, after which the host stores the peer’s public key in a local configuration file.

Prerequisites and Initial Pairing

The following packages are required on most distributions:

sudo apt-get install libpam0g-dev bluez-tools python3-pip
pip3 install immurok-pam immurok-ssh immurok-totp

The command installs the PAM, SSH, and TOTP helper libraries provided by Immurok. Package names are illustrative; replace them with the distribution‑specific equivalents if necessary.

Pair the device using the standard Bluetooth CLI. This step creates a persistent link key that the Immurok libraries will reuse:

bluetoothctl
[bluetooth]# scan on
[bluetooth]# pair AA:BB:CC:DD:EE:FF
[bluetooth]# trust AA:BB:CC:DD:EE:FF
[bluetooth]# exit

Replace AA:BB:CC:DD:EE:FF with the MAC address shown during the scan. The pairing process stores the link key in /var/lib/bluetooth. To remove the device later, delete the corresponding directory and restart the Bluetooth service.

Configuring PAM for Fingerprint‑Based Unlock and sudo

Immurok provides a PAM module named pam_immurok.so. The module can be placed in any PAM stack that supports auth and authinfo_unavail control flags. The typical configuration adds the module after the standard Unix password check.

Edit the common‑auth file (or the distribution‑specific equivalent) to include the Immurok line:

sudo nano /etc/pam.d/common-auth

Insert the following line before the pam_deny.so entry:

auth    sufficient      pam_immurok.so

The sufficient control flag means that a successful fingerprint verification bypasses further authentication modules. If the fingerprint check fails, the stack falls back to password authentication.

For sudo, the same PAM configuration is used because the sudo command references common-auth. Verify the sudo PAM stack includes the common file:

sudo nano /etc/pam.d/sudo

Ensure it contains a line such as:

@include common-auth

After editing, test the configuration with a non‑privileged user. The command will prompt for a fingerprint; a successful scan grants sudo access without a password.

Polkit Integration for GUI Elevation

Graphical applications that request elevated privileges rely on Polkit. Immurok’s PAM module can be referenced from the Polkit authentication agent by adding a custom rule.

Create a Polkit rule file:

sudo nano /etc/polkit-1/rules.d/50-immurok.rules

Populate it with the following JavaScript‑style rule:

polkit.addRule(function(action, subject) {
    if (subject.isInGroup("wheel")) {
        return polkit.Result.YES;
    }
    return polkit.Result.AUTH_SELF;
});

The rule grants automatic approval for members of the wheel group after a successful PAM authentication, which now includes the fingerprint check. Adjust the group name to match the local policy.

Using Immurok as an SSH Agent

Immurok can store an SSH private key internally and expose it through a local agent socket. The helper binary immurok-ssh-agent implements the SSH agent protocol and forwards signing requests to the device after fingerprint verification.

Start the agent in a user session, for example by adding the following to ~/.bash_profile:

export SSH_AUTH_SOCK=$HOME/.immurok/ssh-agent.sock
immurok-ssh-agent -s &

The -s flag runs the agent in the background and creates the socket file. To stop the agent, terminate the process or remove the socket file.

Verify that the agent is providing a key:

ssh-add -L

The output should list a public key that corresponds to the private key stored on the Immurok device. When an SSH connection requires authentication, the remote server will receive a signature generated only after the user’s fingerprint is verified on the device.

Enabling TOTP Generation for Two‑Factor Authentication

Immurok’s TOTP daemon, immurok-totpd, listens on a Unix domain socket and returns a 6‑digit code after a successful fingerprint scan. The daemon can be used by PAM or by external tools such as google-authenticator.

Start the daemon as a system service:

sudo systemctl enable --now immurok-totpd.service

The service creates the socket at /run/immurok/totp.sock. To request a code, use the client utility:

immurok-totp-client

The command blocks until the user touches the sensor, then prints the current TOTP value. Integrate the client into a PAM module for login by adding a custom entry to /etc/pam.d/common-auth:

auth    required        pam_exec.so quiet /usr/bin/immurok-totp-client | grep -q '^[0-9]\{6\}$'

The pam_exec.so line runs the client, checks that the output matches a six‑digit pattern, and only then allows authentication to continue. To revert, comment out or remove the line.

Physical Approval for AI‑Assisted Commands

Immurok can act as a gatekeeper for automated agents that generate privileged commands. The typical workflow involves the agent writing a command to a predefined FIFO, then waiting for a fingerprint‑approved token before execution.

Create a FIFO that the agent will use:

mkfifo /tmp/immurok-approval

The agent writes a command string to the FIFO. A wrapper script reads the command, invokes the Immurok approval client, and executes the command only if the fingerprint is verified:

#!/usr/bin/env bash
read -r cmd < /tmp/immurok-approval
if immurok-totp-client >/dev/null; then
    eval "$cmd"
else
    echo "Fingerprint not verified; command aborted" >&2
fi

Place the script in a secure location, make it executable, and configure the AI agent to invoke it. The script does not modify system files; it only executes the supplied command after a successful biometric check. To disable the mechanism, stop the agent from writing to the FIFO and remove the script.

Security and Operational Trade‑offs

Immurok’s design isolates secret material on the peripheral, reducing the attack surface on the host. However, the reliance on Bluetooth introduces additional considerations:

• Bluetooth pairing security – The initial pairing uses ECDH with HMAC‑SHA256, but the link key is stored on the host. Compromise of the host’s /var/lib/bluetooth directory could allow an attacker to reconnect without re‑pairing. Regularly back up and, if necessary, delete the pairing directory to force a fresh exchange.
• Device availability – Because authentication depends on a wireless peripheral, loss of battery or signal can lock out legitimate users. Maintaining a fallback password or secondary authentication method is advisable.
• Latency – Bluetooth round‑trips add a few hundred milliseconds to each authentication event. This delay is noticeable for frequent sudo usage but does not affect security.
• Physical security – The device stores private keys and TOTP seeds. Physical theft could expose these secrets if the attacker can extract data from the hardware. Immurok’s firmware encrypts stored material, but a determined adversary with hardware access may attempt side‑channel attacks. Deploy the device in a physically secured environment.

From an operational standpoint, the configuration files introduced (PAM, Polkit, systemd service) are standard and survive package upgrades. Removing Immurok requires stopping the services, deleting the configuration snippets, and unpairing the Bluetooth device.

Verification and Troubleshooting

After completing the setup, verify each component independently:

• Desktop unlock – Lock the session (e.g., loginctl lock-session) and attempt to unlock with the fingerprint.
• sudo – Run sudo -v and confirm that no password prompt appears after a successful scan.
• Polkit – Launch a GUI action that requires elevation (e.g., installing a package via a software manager) and observe the fingerprint prompt.
• SSH – Connect to a remote host that accepts the public key shown by ssh-add -L. The remote server should log a successful authentication without a password.
• TOTP – Compare the output of immurok-totp-client with a known good TOTP generator using the same secret (if the secret is exported for testing).

Common failure points include:

• Bluetooth not powered or blocked by a firewall – ensure the bluetooth.service is active and that rfkill does not list the adapter as soft‑blocked.
• PAM module not found – verify that the pam_immurok.so library resides in /lib/security or the directory specified by pam.d.
• Agent socket permission errors – the socket directory must be owned by the user; adjust with chown if necessary.

Log files provide additional insight. PAM failures appear in /var/log/auth.log, while the Immurok daemons write to /var/log/immurok/. Review these logs when troubleshooting unexpected behavior.

Source: feed.itsfoss.com