SiRFIDaL - Simple RFID authentication for Linux
                -----------------------------------------------
                                    v1.6.0


This 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.



Installation / configuration instructions for the busy man
----------------------------------------------------------

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-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 sox



Server 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_server



Optional 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-update



Adding 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 username

  As user (only associations and deletions for the same user allowed):

    sirfidal_useradm.py -a
    sirfidal_useradm.py -d
    sirfidal_useradm.py -D

  Note: 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
           ---------------------------------------------------------