SiRFIDaL - Simple RFID authentication for Linux
-----------------------------------------------
v1.6.2This is a set of utilities to use RFID or NFC transponder UIDs as authentication tokens on a Linux computer - typically for login purposes.
/!\ WARNING: do not use the PAM module as a single form of authentication /!\ /!\ without an additional mandatory password-based authentication /!\ /!\ on a computer onto which users are allowed to login remotely! /!\ /!\ /!\ /!\ If you do, bad things can happen, such as a remote user doing /!\ /!\ su while the right RFID or NFC transponder is on a reader and /!\ /!\ becoming you or root without any checks, unbeknown to you! /!\ /!\ /!\ /!\ Only use it for 1FA login on a computer with a single local /!\ /!\ console and no SSH server, VNC server, remote X or any other /!\ /!\ kinds of remote login enabled - i.e. a workstation. /!\ /!\ /!\ /!\ !YOU HAVE BEEN WARNED! /!\
The utilities included are:
sirfidal_server Core program used by all the others. It manages RFID or NFC readers and authenticates users against RFID / NFC UIDs on behalf of other programs.
sirfidal_pam PAM module that uses the SiRFIDaL server to authenticate users against RFID or NFC UIDs, typcally to login.
sirfidal_useradm Utility to add or delete users allowed to authenticate with RFID / NFC UIDs.
sirfidal_beep Program to beep when a RFID or NFC transponder is read by a reader, or taken off the reader.
sirfidal_autolockscreen Program to lock/unlock a graphical interface screensaver automatically using authenticated RFID or NFC transponders.
sirfidal_autotype Program to automatically type custom strings in predefined X application windows (passwords for example) upon authenticating with a RFID or NFC transponder. Can also copy a UID into the system clipboard.
sirfidal_keyboard_wedge Program to emulate a RFID / NFC keyboard wedge reader, by typing out the UIDs read by the SiRFIDaL server as if they came from a keyboard. This utility must be run as root.
sirfidal_getuids Continuously displays new UIDs being read by the SiRFIDaL server. This utility must be run as root, as the SiRFIDaL server will not expose actual UIDs to non-root users.
sirfidal_auto_send_enter_at_login Utility that automatically types ENTER in a console or graphical login screen when a RFID / NFC transponder is read by the SiRFIDaL server, to avoid having to type an empty password when using pam_unix and sirfidal_pam together in the same PAM configuration.
The following are instructions to install the utilities on Linux Mint, which is based on Ubuntu, and running systemd and the Cinnamon environment.
SiRFIDaL was also tested and works on Debian and Ubuntu with minor configuration changes (see below). It also works well on Fedora and CentOS, but the PAM configuration for those distribution is completely different.
If your Linux system isn't Linux Mint, please modify the configuration files and/or system as needed.
Installation from the pre-build .deb package:
See https://github.com/Giraut/ppa to add the PPA repository to your APT sources
apt install sirfidal
Installation from the pre-build .rpm package:
See https://github.com/Giraut/rpm to add the RPM repository to your YUM or DNF
dnf install sirfidal
AUR package for Arch Linux:
https://aur.archlinux.org/packages/sirfidal-git/
Manual installation:
As root:
* Common:
apt install python3
apt install python3-psutil
apt install python3-passlib
apt install python3-filelock
apt install python3-setproctitle
apt install python3-cryptography
apt install libpam-python
cp sirfidal_server.py /usr/local/bin
cp sirfidal_client_class.py /usr/local/bin
cp sirfidal_autolockscreen.py /usr/local/bin
cp sirfidal_auto_send_enter_at_login.py /usr/local/bin
cp sirfidal_autotype.py /usr/local/bin
cp sirfidal_beep.py /usr/local/bin
cp sirfidal_getuids.py /usr/local/bin
cp sirfidal_keyboard_wedge.py /usr/local/bin
cp sirfidal_pam.py /usr/local/bin
cp sirfidal_useradm.py /usr/local/bin
cp sirfidal_server_parameters.py /etc
cp sirfidal_clients_parameters.py /etc
cp sirfidal_pam.config /usr/share/pam-configs
cp *.service /lib/systemd/system
cp *.desktop /etc/xdg/autostart
mkdir -p /usr/local/share/sounds/sirfidal
cp sounds/* /usr/local/share/sounds/sirfidal
* Additional to use PC/SC readers:
apt install pcscd pcsc-tools python3-pyscard
- Configure PC/SC for your readers. If pcsc_scan works, SiRFIDaL will
work also. See https://pcsclite.apdu.fr/
* Additional to use nfcpy-supported readers:
pip install nfcpy
* Additional to use serial readers, Halo Scanners, Proxmark3, Chameleon or
uFR devices in serial mode:
apt install python3-serial
* Additional to use NFC-enabled Android devices as readers:
apt install adb
- Configure your Android device following the instructions below
- When connecting your Android device to the computer running the
SiRFIDaL server for the first time, it will ask you if you want to
allow USB debugging: check "Always allow from this computer" and
tap Ok.
* Additional to use HID readers:
apt install python3-evdev
* Additional to use uFR readers:
git clone https://github.com/Giraut/pyuFR
- Copy pyufr.py in /usr/lib/python3/dist-packages/
* Additional to use sirfidal_autotype.py:
apt install pyperclip
apt install python3-tk
apt install python3-xlib
apt install python3-xdo
-or-
apt install xautomation
-or-
python3 -m pip install pynput
* Additional to use sirfidal_beep.py:
apt install soxServer configuration:
As root:
All the SiRFIDaL server configuration options are located in the
/etc/sirfidal_server_parameters.py file:
* Readers declararion:
All the readers the server should read UIDs from are declared in the
"readers" dictionary. The default values are reasonable / sample values
for one of each type of reader supported by the SiRFIDaL server.
You may declare several of the same type of reader. Simply reuse the same
type and parameters in a new section with a new reader name.
For example, it you want to use 2 serial readers with different baudrates:
...
"serial_reader_#1": {
"enabled": True,
"type": "serial",
"uids_timeout": 1, #s
"device": "/dev/ttyUSB0",
"baudrate": 9600,
"bytesize": 8,
"parity": "N",
"stopbits": 1
},
"serial_reader_#2": {
"enabled": True,
"type": "serial",
"uids_timeout": 1, #s
"device": "/dev/ttyUSB1",
"baudrate": 115200,
"bytesize": 8,
"parity": "N",
"stopbits": 1
},
...
* Configuration options common to all types of readers:
- enabled: If set to True, the reader is enabled. If set to False,
the rest of the declaration is ignored.
- type: Type of reader
- uids_timeout: If set to a value in seconds, the UIDs read by that
reader exist in the server as active UIDs for that
number of seconds, then time out unless the reader
re-reads them before they time out. In the case of
repeating readers that send the same UIDs repeatedly,
this maintains the UIDs active as long as the
transponders are read. In the case of one-shot readers,
this maintains the UIDs active for the duration of the
timeout only.
If set to None, the UIDs sent by the reader never time
out. The reader or the SiRFIDaL reader listener must
actively inform the server when the UIDs become
inactive. The reader is said to be persistent.
* Configuration options for USB PC/SC readers:
- readers_regex: Regular expression only PC/SC readers with a matching
name will be used
- poll_every: Delay in seconds between reader polls
* Configuration options for nfcpy-supported readers:
- device: nfcpy-style device specification. E.g. usb:072f:2200
for an ACR ACR122U. The list of supported devices is
at https://nfcpy.readthedocs.io/en/latest/overview.html
- flash_and_beep: Make the reader flash and beep when a UID is read, if
the device is equipped with a LED and a buzzer
- poll_every: Delay in seconds between reader polls
* Configuration options for serial readers:
- device: Serial device file
- baudate: Serial communication speed
- bytesize: 7 or 8 bits
- parity: "N" for none, "E" for even, "O" for odd, "M" for mark,
"S" for space
- stopbits: 1, 1.5 or 2
* Configuration options for Halo Scanners:
- device: Serial device file
- new_firmware: Set to True for use with Halo Scanners with firmware
version 7.0 or above
- auto_rescan: For new firmwares that support th scan command,
automatically trigger a new scan after a UID has been
read, so the device is polled continuously
- alive_min_temp: With firmware version 8.0 or above, if a Destron Fearing
with Bio Thermo implant is read, minimum temperature
below which the implant isn't considered implanted in a
living being
- alive_max_temp: With firmware version 8.0 or above, if a Destron Fearing
with Bio Thermo implant is read, maximum temperature
above which the implant isn't considered implanted in a
living being
- alive_prefix: With firmware version 8.0 or above, if a Destron Fearing
with Bio Thermo implant is read and the reported
temperature is between the minimum and maximum "living
being" values above, hex digits to prefix the UID with
* Configuration options for HID readers - aka keyboard wedges:
- device: HID input device file
* Configuration options for Android devices used as NFC readers:
- client: Full path to the ADB client executable
- logcat_prefix: Prefix used to spot UIDs reported by the Android Tasker
script (see below). This shouldn't have to be changed
unless the prefix is changed in the Tasker script
accordingly.
* Configuration options for Proxmark3 devices used as NFC or RFID readers:
- device: Serial device file of the Proxmark3
. client: Full path to the Proxmark3 client executable
- client_workdir: Working directory in which to run the Proxmark3 client,
where it will try to log things to a fake proxmark3.log
that is in fact a symlink to /dev/null
- client_timeout: How long the Proxmark3 client may stay silent before
it's considered crashed and restarted
- read_iso14443a: If set to True, read ISO 14443A transponder UIDs (HF)
- read_iso15693: If set to True, read ISO 15693 transponder UIDs (HF)
- read_em410x: If set to True, read EM410x transponder UIDs (LF)
- read_indala: If set to True, read HID Indala transponder UIDs (LF)
- read_fdx: If set to True, read FDX-B transponder UIDs (LF)
Note: The above transponder type flags may be combined. However, note
that the more types you combine, the less responsive the
Proxmark3 will becomes. Additionally, if you combine HF and LF
transponders, the Proxmark3's FPGA will be reprogrammed at each
polling cycle to switch back and forth from HF to LF, which is
not only very slow, but also quite harmful for the FPGA.
It is highly recommended to stick to HF or LF transponders.
* Configuration options for Chameleon Mini / Tiny devices:
- device: Serial device file of the Chameleon device
* Configuration options for uFR or uFR Nano Online in slave mode:
- device: Unified pyuFR-style device specification
- poll_every: If set to a value in second, the uFR reader is driven
in polled mode, and the value is the delay between
polls. If set to None, the uFR reader is driven in
asynchronous mode.
- poll_powersave: If the uFR device is driven in polled mode, put the
reader to sleep between polls, to reduce energy usage
- debounce_delay: Delay before reporting no active UID to the server in
asynchronous mode. This prevents the active UID
flitting on and off at high speed if the transponder
doesn't couple quite well enough with the reader if it
leaves the field too slowly, due to the very fast
nature of asynchronous scanning.
- no_rgb1: Color to set the uFR Nano Online-specific RGB LED #1 to,
or None
- no_rgb2_on: Color to set the uFR Nano Online-specific RGB LED #2 to
when a transponder is in the field, or None
- no_rgb2_off: Color to set the uFR Nano Online-specific RGB LED #2 to
when no transponder is in the field, or None
- conn_watchdog: How many seconds of silence before the connection to
the uFR reader is rechecked in asynchronous mode
* Configuration options for the HTTP server for networked readers sending
UIDs using the HTTP GET or POST methods:
- bind_address: Address (interface) to bind the server to
- bind_port: Port to bind the server to
- get_data_fmt: Regular expression used to extract UIDs from
GET request data, or None to disable the GET method
- get_reply: Fixed string to send to the client after it sends a
UID using the GET method
- post_data_fmt: Regular expression used to extract UIDs from
POST data, or None to disable the POST method
- post_reply: Fixed string to send to the client after it sends a
UID using the POST method
* TCP client to get UIDs from a reader running a TCP server
- server_address: Address of the reader
- server_port: Port of the reader
- tcp_keepalive: How many seconds of silence before the TCP connection
is rechecked by sending something to the reader,
or None to disable
* Enable and start the SiRFIDaL server's systemd services:
systemctl enable --now sirfidal_serverOptional systemd services:
As root:
* Configuring, enabling and starting the SiRFIDaL beep service:
- Change the system-wide configuration settings related to sirfidal_beep
in /etc/sirfidal_clients_parameters.py if needed
systemctl enable --now sirfidal_beep
* Enabling and starting the SiRFIDaL keyboard wedge simulation service:
systemctl enable --now sirfidal_keyboard_wedge
* Enabling and starting the SiRFIDaL "auto send ENTER at login" service:
systemctl enable --now sirfidal_auto_send_enter_at_login
Note: Doesn't work with Wayland - see below.PAM configuration:
As root:
* Configure PAM for single factor authentication (password or RFID / NFC):
- Edit /usr/share/pam-configs/unix and add "nodelay" after "pam_unix.so"
in the Auth sections
* Configure PAM for two-factor authentication (password and RFID / NFC):
- Edit /usr/share/pam-configs/unix and replace
"success=end default=ignore" with "success=ok" in the Auth sections
* Finalize the PAM configuration
pam-auth-updateAdding and deleting user, UID and optional authentication token associations:
A user is only authenticated if at least one active UID is associated with their username. Therefore, one or more UIDs must first be enrolled for a particular user.
Use the sirfidal_useradm.py utility to add a user / UID association (-a), delete a user / UID association (-d) or delete all user / UID associatons for a given user (-D).
In additionm when adding an association, you may specify a secondary authentication token to be added to this association: when this token is specified, it will be used by the SiRFIDaL PAM module to set the PAM authtok variable, which is passed to other PAM modules to unlock the keyring or mount an encrypted Private space for example.
You can therefore set the optional secondary authentication token to your regular Unix password to automate everything in your session as if you had logged in from the regular Unix prompt, but logging in using SiRFIDaL.
Note that if you don't want to set the optional secondary authentication token, the PAM authtok will be set to the authenting UID - meaning that, if you want to automate unlocking your keyring or mounting your encrypted Private space, you'll have to set your Unix password to match your UID instead.
As root:
sirfidal_useradm.py -a username
sirfidal_useradm.py -d username
sirfidal_useradm.py -D usernameAs user (only associations and deletions for the same user allowed):
sirfidal_useradm.py -a
sirfidal_useradm.py -d
sirfidal_useradm.py -DNote: Authentication tokens don't work in RPM-based distributions - see below
Optional user utilities configuration:
As user:
* Running the automatic screensaver locker / unlocker:
- Change the system-wide configuration settings related to
sirfidal_autolockscreen in /etc/sirfidal_clients_parameters.py if
needed. Alternatively, you may partly or fully override them with
user-specific settings in ~/.sirfidal_clients_parameters.py
- In Preferences > Startup Applications, enable SiRFIDaL auto lock screen
- Select the entry and click on the gears icon to run it now
* Running the autotyper:
- Change the system-wide configuration settings related to
sirfidal_autotype in /etc/sirfidal_clients_parameters.py if
needed. Alternatively, you may partly or fully override them with
user-specific settings in ~/.sirfidal_clients_parameters.py
- In Preferences > Startup Applications, enable SiRFIDaL autotype
- Select the entry and click on the gears icon to run it now
- To tie / untie a string to type in a particular window with a particular
UID, or copy that UID into the system clipboard, from the command line:
sirfidal_autotype.py -w <string> [-n]
sirfidal_autotype.py -r
sirfidal_autotype.py -c
- To tie / untie a string to type in a particular window with a particular
UID, or copy that UID into the system clipboard, using the GUI panel:
- Put the target window in focus
- Press and maintain the modifiers defined in "edit_scan_hotkeys" in
sirfidal_clients_parameters.py (the modifiers may be specified by name
such as "Shift_L", "Shift_L", "Control_L", "Control_R", "Alt_L",
"Alt_R"... or by keysym, such as 0xfe03 for Alt-Gr, as reported by
the xev utility)
- Read the tag you want to associate / disassociate or copy into the
clipboard to bring up the GUI panel
Note: Doesn't work with Wayland - see below.Configuring an Android device as an external NFC reader for SiRFIDaL:
In Settings > System, enable Developer options and USB debugging: https://developer.android.com/studio/debug/dev-options
-then-
Install and run the standalone SiRFIDaL_NFC_reader.apk app: https://github.com/Giraut/SiRFIDaL/raw/master/SiRFIDaL_NFC_reader.apk
-or-
Install Tasker: https://play.google.com/store/apps/details?id=net.dinglisch.android.taskerm
In Preferences > Monitor, tap the NFC Detection Enabled check box
Install the script in tasker:
File import method:
. Copy the sirfidal_tasker_script.xml file to your Android device . In the Profiles tab, tap Profiles then select Import Profile . Select the storage location you copied the file to then select the file . In the main screen, tap the tick mark to save everything
Entering the script manually if the import fails:
. In the Profiles tab, tap + . Select Event > Net > NFC Tag . In the Event Edit screen, tap <- . Select New Task and tap the tick mark . In the Task Edit window, tap +, then select Net > NFC Tag . in the Action Edit screen, Leave everything blank and tap <- . In the Task Edit window, tap + again, then select Code > Run Shell . In the Action Edit screen, enter the line below in the Command field:
log nfcuid:%nfc_id
then tap <- . In the Task Edit window, tap <- . In the main screen, tap the tick mark to save everything
Note regarding persistence in Android devices:
To provide persistent mode with an Android device used as an external NFC reader - i.e. to emulate a PC/SC reader, nfcpy-supported reader or a repeating serial device, that continuously reports whether a transponder is on the device - SiRFIDaL abuses the Android system log and uses it to catch "tag off" debug events.
This is a bit dirty however, and it may not always work, as Google may modify or remove that particular logging without notice at any time. If the feature fails to work properly, the symptom is SiRFIDaL "seeing" a transponder getting read, but failing to see it leave the reader.
If you experience that problem, you can disable persistent mode by changing uids_timeout from None to some value in seconds (for example 1) so that active UIDs read by the Tasker script time out on their own. When persistent mode is disabled, the Android device still works as an external NFC reader, but degrades to the equivalent of a keyboard wedge or non-repeating serial reader.
Choosing between the PC/SC and nfcpy listeners for readers supported by both:
Some readers - most notably the ubiquitous ACS ACR122U - are supported by both PC/SC and nfcpy. The difference between the two is that PC/SC adds a layer of abstration in the form of the pcscd daemon, that lets multiple applications read multiple readers concurrently in a unified manner, while nfcpy communicates with a single reader directly and prevents other applications from using it.
PC/SC is therefore generally more desirable, but it does require some setup, and running an extra daemon. If you don't mind dedicating a reader to SiRFIDaL or you don't want to bother setting up PC/SC, nfcpy is a lighter alternative.
Incompatibility with Wayland:
The Wayland X compatibility libraries aren't fully compatible with X11, and Wayland has no concept of window in focus as X understands it, nor does it supports synthetic keyboard events targeted at a single window like X does. Those features are needed by the SiRFIDaL autotyper to function properly.
In addition, the Wayland input stack doesn't seem to accept uinput events either, which breaks sirfidal_auto_send_enter_at_login.
Therefore, in distributions that feature Wayland as the default display server such as Debian or Ubuntu, in order to use those SiRFIDaL utility, Wayland must be disabled and replaced by the traditional Xorg display server.
See for instance https://wiki.debian.org/GDM#Disabling_Wayland or https://linuxhint.com/enable-disable-wayland-ubuntu/
Authentication tokens in RPM-based distributions:
Unlike Debian-based distributions, the pam_python package isn't included in RPM-based distributions such as Fedora or CentOS. As a result, unless you're willing to build and install it yourself from sources onto your system, you'll have to execute sirfidal_pam.py from pam_exec.so instead of pam_python.so.
Unfortunately, while pam_exec.so is ubiquitous, it's more limited than pam_python.so: it only lets sirfidal_pam.py report the authentication status, whereas the latter also let it set the PAM authtok variable, which is necessary to pass a the authentication token further down the PAM stack to other PAM modules.
Therefore, in RPM-based distributions, while SiRFIDaL works for basic authentication purposes, it won't work for more advanced functionalities such automatic keyring unlocking unless you're willing to spend time to install pam_python manually.
---------------------------------------------------------
Bug reports? Questions? You can email me.
Run this command to get my email address:
C=base64\ -d;$C<<<Y205emEybHpRSEoxYm1KdmVDNWpiMjBLCg==|$C
---------------------------------------------------------