For Users

User Manual

Prerequisites

Linux-based operating system (tested on Ubuntu 22.04)
Python 3.8 or above
OpenCV (cv2) library for python
face_recognition library for python
dlib library version 19.22 (The functionalities of the face_recognition library haven't been updated for the more recent dlib versions)

Setup

METHOD 1: Setup file method

After cloning the repository you can set up the program by running the setup file, but first you need to make the file executable. The following command can do this:

chmod +x setup.sh

After this the shell file can be run directly by the command:

./setup.sh

METHOD 2: Step by Step Installation

1. Depencies

Check for all the necessary dependencies, especially the ones mentioned above, or simply just install them using the commands:

pip install opencv-python
pip install face_recognition

2. Enrollment and Authentication Scripts

Set up the required scripts in the directory of your choice and make sure to set up the paths of the template directory too within the scripts.

3. Python Call Program and PAM Module

Create a C program that calls the Python authentication script and captures the output.
This C program also includes the necessary functions for the functioning of a PAM module in different modes.
After setting up the program, compile the C code and install the PAM module. This will create a shared object file that needs to be shifted to the necessary directories as this is what PAM framework operates on. This is setup with the following commands.

gcc -fPIC -shared -o pam_face_auth.so pam_face_auth.c -lpam -lpam_misc

This shared object file is needed to be shifted to the security folder where all the pam modules are present, this is done by the following command:

sudo cp pam_face_auth.so /lib/x86_64-linux-gnu/security

sudo cp pam_face_auth.so /lib/security

sudo cp pam_face_auth.so /usr/lib/security

depending on your system configurations.

4. Configure PAM for Face Recognition Login

Edit the PAM configuration files to enable face recognition authentication.

Add the following line at the beginning or just above the pam_unix.so file configuration of /etc/pam.d/common-auth:
```
auth    sufficient                      pam_face_auth.so
```

Edit /etc/pam.d/login and /etc/pam.d/gdm-password:
Replace the line:

@include common-auth

with:

auth    sufficient                      pam_face_auth.so
@include common-auth

5. Run the Enrollment Script

Run the enrollment script to capture images and create templates for each user. Replace with the desired username.

python enrollment_script.py <USERNAME>

6. Test the Face Recognition Login

You can test the system using the pamtester functionality of linux, you can get it by running the command:

sudo apt-get pamtester

You can further test the module by running the following command:

pamtester login <username> authenticate

Once this test is succesfully passed you can try the system by logging out of the current session and trying to login again.