- Description
- Contribution
- Acknowledgement
- Prerequisites
- Setup
- Compilation
- Usage
- Security
- Troubleshooting
This program uses Linux Pluggable Authentication Modules (PAM) to authenticate users via the use of Near-Field Communication (NFC). It can be used with traditional NFC smart cards, as long as they are configured correctly, although the intended use of this program is with the OS_auth_application Android App.
Please see the CONTRIBUTING.md file for information on contributing to the project
Whilst this project is novel work, it takes inspiration from pam_nfc. Thank you to the developers of that project for releasing it under a GNU General Public license so that it could be used to benefit this work.
In order to use this program, you must have:
- A Linux system (preferably Debian based)
- libnfc installed on your system (see setup for details)
- A physical NFC card reader and tags
- Create an empty file called pam_nfc.conf in /etc/
- An Android phone with NFC, and the app installed (in the app folder)
In order to use NFC in Linux with C support, you must use the free libnfc library. This can be installed using
sudo apt-get install libnfc-bin libnfc-examples libnfc-pn53x-examples
in Debian based systems.
If using an ACR122 reader, as in the project, a few extra steps must be taken in order for it to work properly. Firstly, pcscd must be installed using
sudo apt-get install pcscd
and pcsc which can be installed from Here and by following the instructions in the README.
Following this, the libccid_Info.plist file located within etc must be modified. Locate <key>ifdDriverOptions</key> and turn <string>0x0000</string> value into 0x0001.
Finally, run
sudo vim /etc/modprobe.d/blacklist-libnfc.conf
and add the line blacklist pn533_usb, before rebooting your machine. libnfc should now be configured correctly, which can be verified by running
nfc-list
To use libnfc within C, run on the command line
sudo apt-get install libnfc-dev
and then at the top of the C file #include <nfc/nfc.h>
PAM applications must contain certain header files in order to work. These files can be found in
usr/include/security
If they do not yet exist, install them from the command line by using
sudo apt-get install libpam0g-dev
Download the APK file in the app folder on this repo to your Android smartphone, and install (may need to allow install from unknown sources). Once downloaded, create an account on the app, and use this is sign in. To use the app, simply tap on the reader.
For ease of compilation, a makefile has been included with this solution. To compile both programs, simply run:
cd program
make
Once the program has been compiled, two executable files will be generated in the program folder.
The add_user program is used to add new users to the pam_nfc.conf file. To use this program, simply run:
sudo ./add_user $USERNAME$
where $USERNAME is replaced with the username of the user you are adding. The program will establish a connection to the NFC reader where it will wait for the device to be touched to the reader. Once the device has been touched to the reader, it will perform the APDU transaction, and assuming everything is setup correctly, add the new user and their authentication ID to the config file.
The authenticate program carrys out the actual user authentication with Linux-PAM, using the entries in the config file. To use this program, simply run:
sudo ./authenticate
This program takes in no parameters via the command line, but Linux-PAM will prompt you to enter your username once the program is running. Once again, a connection to the NFC reader will be established, and once a device is touched, the APDU transaction is performed. The authentication ID received will then be compared to the configuration file, and Linux-PAM handles the authentication as a result.
The app and program are already configured to use the same AID to work. However, if you do need to know this, the AID used for this project is A0000002471001.
In order to make authentication more secure, this project uses application protocol data unit (APDU) for authentication, as opposed to the UID of the device. UIDs are not secure as can be easily read and spoofed. APDU is more secure, although still not perfect, but hopefully this project will be extended in future to use a secure channel for all NFC transactions, making it much more secure. For more information on APDU and how this works, there is plenty of papers and knowledge articles on the Internet.
If you have any problems with setting up, running, or using this program, please use the discussion tab on GitHub.