            SiRFIDaL - Simple RFID authentication for Linux
            -----------------------------------------------
                                v1.7.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-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 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

SiRFIDaL

Install / Use

README

Installation / configuration instructions for the busy man