## Fingerprint GUI User's Manual

### (Version 1.07)

### Wolfgang Ullrich

## Preface

Fingerprint GUI is a set of tools for the use of fingerprint scanners on Linux systems. It enables recording and checking of fingerprint data and allows login and authentication of users by their fingerprint using a fingerprint scanner.

### Security Advice

The safety and reliability of the fingerprint-recognition depends very much on the hardware used, the associated device drivers and the software used to verify the biometric data. According to the current state of the art fingerprint recognition for security-critical applications is only limited suitable. More information about the safety of fingerprints can be found here: http://www.bromba.com/faq/fpfaqe.htm

### License

Fingerprint GUI is subject to the GNU General Public License Version 2 (GPLv2) http://www.gnu.org/licenses/gpl-2.0.html

## Fingerprint Enrollment

Start the program "Fingerprint GUI" from the menu "System | Preferences”, or by the command:

> fingerprint-gui -d

in a terminal window. The argument "`-d`" generates debugging information to syslog (auth facility). You can find the log output in `/var/log/auth.log`.

### Choosing a Fingerprint Scanner

In the “Devices” tab a list of all detected USB devices appears in the list “Attached USB Devices”. In the combo box “Finger Print Devices” appears a selection of the detected fingerprint scanners. If more than one fingerprint scanners have been detected, the desired scanner can be selected here. With the "Rescan" button, a re-examination on the USB bus can be initiated. By selecting "Show Vendor/Device" and "Show Driver Name" you can switch between displaying the device name or the device driver name.

### Choosing a Finger

With the "Next" button or by selecting the "Finger" tab you get the finger selection.

Above the fingers are radio buttons. Here are the fingers marked green that are already enrolled. Select the finger to be detected.

### Scanning and Verifying

With the "Next" button or by selecting the tab "Scan/Verify" you get the card for enrolling or verifying of the fingerprint.

Now enroll the fingerprint. Depending on the scanner hardware, the driver software and the quality of the data you have to repeat this process until a message about the successful storage of the data appears.

Click “Yes” to return to the finger choice if you want to enroll another finger or click “No” if you don't want it.

If a finger was selected that has been enrolled already a dialog appears where this finger can be verified or newly enrolled.

With the “Verify” button you can verify the existing fingerprint data against this finger. With “Acquire new” the existing fingerprint data for this finger is removed and the finger is newly enrolled. Click “Cancel” to go back to the finger choice.

## Testing Settings and exporting Fingerprint Data

With the "Next" button or by selecting the tab "Settings" you get the card for saving your fingerprint data and testing your PAM settings.

By clicking “Export now” all existing fingerprint data of the current user are saved to a file. This is only required if these data need to be external backed up or if you want to use them on another computer. A file “`Fingerprints.tar.gz`“ will be created in the selected directory.

With the “Test” button you can check the PAM settings for authentication. Chose the PAM service to be tested first then click “Test”. If all PAM settings for this service are correct the fingerprint-authentication dialog appears.

If a valid fingerprint was recognized a message “Authentication successful” appears in the text field.

If the fingerprint dialog doesn't appear some settings are invalid. You can stop the test by pressing the “Enter” key. A message “Fingerprint authentication failed” appears in the text field then.

In this case the settings in the appropriate “`/etc/pam.d/...`“ file for this service are invalid and need to be corrected.

## Saving a Password

With the “Next” button or by selecting the “Password” tab you arrive at the dialog for storing a password to an external media.

PLEASE USE THIS FEATURE ONLY IF YOU COMPLETELY UNDERSTAND HOW IT WORKS. THIS FEATURE CAN OPEN A SECURITY RISK FOR YOUR DATA!

Explanation: If you use fingerprints for log-on to your system, no password is entered, since you were detected on the basis of your fingerprint. Depending on the configuration of your system a password might be needed to decrypt important data. For example this is the case if your home directory or the gnome-keyring is encrypted with your login password. Fingerprint GUI features the use of an external storage (USB stick) to store your password in an encrypted file on that media. If this media is connected to your computer while login, this file can be decrypted and the password can be used to unlock gnome-keyring or your home directory.

Security warning: Everyone who has access to both, your computer and the external media, can decrypt the password-file! Never leave the computer and the media unattended at the same place! Connect this media only while logon and don't use it if other persons have root-access to your computer.

If you want to save your password, first connect the external media to your computer. The media must be mounted, you must have write access to it and it must be a removable device.

Chose the path to the mounted device, invoke your password twice into the password fields and click “Save”. A hidden directory “`.fingerprints`“ will be created in the given path and a file “`<username>@<hostname>.xml`“ will be created there. This file contains the encrypted login password. Moreover a file „`/var/lib/fingerprint-gui/<username>/config.xml`“ will be created on your local harddrive containing the UUID of the media, the given path and the key to decrypt the password.

Note: If you later change your login password, you need to repeat this process.

You can now exit the program by clicking “Finish”.

## Special Settings

Here are some special settings for advanced users, that can not be automatically setup by the installation.

### Disabling the User List

In the menu "System | Administration | Login Screen" it is possible to disable the "Show list of users" item. While login there is shown only a text field for typing the username then. For showing the fingerprint request below this field the file "`/etc/pam.d/gdm`" must be changed. Insert the following text as the first line: auth optional pam_fingerprint-gui.so -d

Please check the file "`/etc/pam.d/common-auth`" for having the argument "`try_first_identified`" in the line with the pam_fingerprint-gui.so entry. If missing, append this argument to the line. You need root permissions to make changes to these files.

If this is properly setup and the user list is disabled, you should be identified by your fingerprint and logged-in automatically.

### Authentication by Policykit-1

The autentication by policykit-1 is performed by the polkit-gnome-authentication-agent, that is started for each session. For starting this agent a starter file "`/etc/xdg/autostart/polkit-gnome-authentication-agent.desktop`" is used. By the installation of fingerprint-gui a starter "`/etc/xdg/autostart/fingerprint-polkit-agent.desktop`" has been added to this directory, that starts the fingerprint-polkit-agent. To avoid conflicts between these two agents, the file "`polkit-gnome-authentication-agent.desktop`" must be removed from "`/etc/xdg/autostart`". After removing you need to logoff and login again for being able to authenticate by fingerprint in policykit-1.

### NVM Emulation

The installation package installs default settings for UKEK devices that require NVM emulation. However it might be necessary to fine tune these settings. Below are quoted some excerpts from the documentation for UPEK fingerprint scanners:

1 Introduction

UPEK TCD4C and TCD4E sensors exist in two variants - with and without the EEPROM chip. The NVM functionality for sensors without EEPROM must be emulated. BSAPI for Linux uses file emulation for NVM functionality. This document describes the fundamental configuration.

...

2 NVM emulation configuration

NVM contents for EEPROMless sensors is stored in files. There is one file per sensor. The location of these files is determined by 'nvmprefix' configuration parameter. This parameter contains a path to NVM-emulation files and a prefix of their names. This allows (for example) to make the files hidden (names start by '.'). The 'nvmprefix' parameter can be set the following way: …

As root create the configuration file “`/etc/upek.cfg`“ with the following line (Example):

nvmprefix="/var/upek_data/.NVM"

...

The setup directory must have read and write access rights set for everyone who can use BSAPI. The /etc/upek.cfg file must have read access right set for everybody.

...

3 Additional DSN parameters

The EEPROMless sensors are preconfigured for dual direction swipes. If you prefer to swipe only in one direction, you can override this setting by using dualswipe=0 parameter. ...In the /etc/upek.cfg configuration file Add the following line to the file:

dualswipe=0

...

Note: Use the 'dualswipe' parameter only in the cofiguration where you have used the 'nvmprefix' parameter.

…

## Troubleshooting

### Installed Files and Helper Applications

Fingerprint GUI makes use of the following programs, helper applications, libraries and files. Depending of compiler settings while creating the installation packages the location in the file system can differ slightly (located in `/usr/...` or `/usr/local/...`).

1. `/usr/local/bin/fingerprint-gui`

   Main application for enrollment and verification of fingerprints and for special settings;

2. `/usr/local/bin/fingerprint-identifier`

   Program for testing fingerprint identification, usable in scripts and other applications. The login name of the identified user is printed to stdout;

3. `/usr/local/lib/fingerprint-gui/fingerprint-helper`

   Helper application for prompting finger swipes out of PAM;

4. `/usr/local/lib/fingerprint-gui/fingerprint-plugin`

   Helper application for embedding the finger swipe dialog into the gnome-screensaver instead of a on screen keyboard;

5. `/usr/local/lib/fingerprint-gui/fingerprint-rw`

   Helper application for reading and writing fingerprint data and settings with required permissions;

6. `/usr/local/lib/fingerprint-gui/fingerprint-polkit-agent`

   Authentication agent for policykit-1;

7. `/lib/security/pam_fingerprint-gui.so`

   PAM library module for identification and authentication of users by their fingerprints;

8. `/var/lib/fingerprint-gui/<benutzername>`

   Directory per user to store fingerprints and user settings to.

### Debugging

All programs and libraries can create debug output in syslog (auth facility), if they are called with the argument “`-d`“ or “`--debug`“. By default the debug output goes to `/var/log/auth.log`.

### Special Arguments

“`decorated`” - Argument given on the command line to fingerprint-identifier shows the finger swipe dialog as decorated window. Default is undecorated;

“`try_first_identified`” - Argument given to pam_fingerprint-gui.so in PAM configuration files causes pam_fingerprint-gui.so to return “PAM_SUCCESS” immediately if the given user was identified already by a previous run of the module in the same PAM stack.

### Online-Help

Online-Help is available in the Fingerprint GUI forum on:

http://home.ullrich-online.cc/fingerprint/Forum

or on the homepage:

http://www.ullrich-online.cc/fingerprint