## Fingerprint GUI Step-by-Step Manual

### Package Maintainer's Manual (version 1.06)

### Wolfgang Ullrich

## Preface

This guide is not intended for normal users. It is intended for package maintainers and those advanced users, who want to test Fingerprint GUI on a Linux system, that has no installation package available yet. All settings, filenames and locations, packet names and so on are based on a fresh installation of Ubuntu Linux 10.10. Ubuntu users, who want to use Fingerprint GUI only, can install a package from a personal package archive (ppa) on https://launchpad.net/~fingerprint/+archive/fingerprint-gui that is maintained by David Jurenka.

### Debugging and Getting Help

If you encounter any problems with your installation, please try to debug. When started with the “`-d`” (or “`--debug`”) argument, all executables print lots of debug output to the auth facility of syslog. The debug output goes by default into `/var/log/auth.log`. If this can't solve the problem, try to get help by using the forum on http://home.ullrich-online.cc/fingerprint/Forum/ or looking at the homepage http://www.ullrich-online.cc/fingerprint/ for newest informations and known bugs. If this doesn't help, contact me (the author) directly by mail to contact_at_ullrich_dash_online_dot_cc.

### Distribution

Since version 1.00 the software is not distributed as executable binaries any more on the homepage. If there is no installation package available for your system, you need to compile and install by makefile. Please read the README file for information about compiling and installing.

### Library Dependencies

On Ubuntu 10.10 the following libraries (incl. their development headers) must be installed: libfakekey, libqca2, libpam0g, libfprint, libusb-1.0-0, qt4-dev-tools, libpolkit-qt-1. Other Linux distributions might require more packages to be installed or might have different package names.

### Conflicting Software

The following applications are known to conflict with Fingerprint GUI: thinkfinger, pam-fprint, pam-fprintd and, of course, earlier versions of Fingerprint GUI. Remove these software and undo all configuration changes made for them.

IMPORTANT NOTE ABOUT KDE: Because kdm and kscreenlocker don't meet the requirements in the “PAM Application Developers Guide” they will not work (see Bug 105631). Please don't report “bugs” against Fingerprint GUI about login or unlocking the screensaver on KDE systems. Other services like su, sudo, kdesudo and policykit-1 should work. At least on Kubuntu 10.10 they do.

## Installing Fingerprint GUI

When installing by executing “sudo make install” the following files and directories are installed to your system:

1. in `/usr/local/bin/`: fingerprint-gui, fingerprint-identifier;

2. in `/usr/local/lib/fingerprint-gui/`: fingerprint-helper, fingerprint-plugin, fingerprint-polkit-agent, fingerprint-suid;

3. in `/lib/security/`: pam_fingerprint-gui.so;

4. in `/var/lib/`: `fingerprint-gui/` (directory for user fingerprint data);

5. in `/usr/share/applications/`: `fingerprint-gui.desktop`;

6. in `/usr/share/doc/`: `fingerprint-gui/` (directory containing html documentation);

7. in `/usr/share/man/man.1/`: `fingerprint-gui.1.gz`, `fingerprint-identifier.1.gz`, `pam_fingerprint-gui.1.gz`;

8. in `/etc/xdg/autostart/`: `fingerprint-polkit-agent.desktop`;

When installing the proprietary driver “`libbsapi.so`” for fingerprint scanners manufactured by UPEK Inc. or SGS Thomson, that is made by executing “sudo make install-upek”, the following additional files and directories are installed:

1. in `/etc/`: `upek.cfg`;

2. in `/var/`: `upek_data/` (directory for NVM emulation);

3. in `/etc/udev/rules.d/`: `91-fingerprint-gui-upek-rules`;

## Accessing Fingerprint Devices

For Fingerprint GUI to work, all users need read and write permissions to the connected fingerprint reader. By default you need a group named “plugdev” that all users are members of. If you don't want to create or use this group you need to change the group name in the udev rules file and restart or reconfigure udev with udevadm.

## First Start and Enrolling Fingerprints

By default a start entry “Fingerprint GUI” is installed in the “System | Preferences” menu. Start Fingerprint GUI from there or start it in a terminal with “fingerprint-gui -d”. Enroll your fingerprints. The “Test” button in the “Settings” tab will not work in this stage yet. If acquiring fingerprints does work with Fingerprint GUI you can go ahead with the system configuration.

## System Configuration

Because configuration errors can lock access to your system completely, you should always keep open a root session in a secure tty for being able to undo configuration changes.

You need root permissions to make the following changes.

The following settings are only examples, working on Ubuntu 10.10, that demonstrate the configuration principles. On other Linux distributions the filenames in question or file contents might differ.

### Configuring the PAM Stack

First of all make a copy of your `/etc/pam.d/` directory. So you can easily revert all changes if something goes wrong.

1. Edit the file `/etc/pam.d/common-auth`: insert a line “auth sufficient pam_fingerprint-gui.so -d try_first_identified” before the line “auth … pam_unix.so ...”, so that pam_fingerprint-gui.so is called before a password is requested;

2. Edit the file `/etc/pam.d/gdm`: insert a line “auth optional pam_fingerprint-gui.so -d”, so that pam_fingerprint-gui.so is called as a first action when a user performs a login;

These settings assume, that all other configuration files for the PAM authentication services include the file “`common-auth`”.

### Configuring Gnome-Screensaver

Gnome-screensaver needs a plugin for showing a widget that requests a finger-swipe from the user when he tries to unlock the screensaver. This plugin is configured as an “embedded keyboard” in the gnome-screensaver settings. Open the “gconf-editor”, find the “apps | gnome-screensaver” entry and edit the “embedded_keyboard_command”. Edit the command line to “`/usr/local/lib/fingerprint-gui/fingerprint-plugin -d`” and enable the “embedded_keyboard_enabled” checkbox.

### Configuring Policykit-1

For authenticating by policykit-1 a polkit authentication agent must run in every user's session. Therefore the file “`fingerprint-polkit-agent.desktop`” is installed to `/etc/xdg/autostart/` by “sudo make install”. This file starts the fingerprint-polkit-agent when a user session is started. But the fingerprint-polkit-agent conflicts with the “polkit-gnome-authentication-agent-1” or the “polkit-kde-authentication-agent-1” that are installed by default on your system. To solve this conflict remove the “`polkit-gnome-authentication-agent-1.desktop`” or “`polkit-kde-authentication-agent-1.desktop`” file from the directory `/etc/xdg/autostart/`.

Brave users can restart their system now. The less brave should continue with some tests as follows:

## Testing the System

The following should work after configuration is done:

1. sudo: Open a terminal and type “sudo xterm”. In the terminal should appear a line prompting for a password while at the same time a GUI widget should request a finger-swipe. You should be able to open xterm with root permissions by typing your password and by swiping your finger over the reader as well.

2. su: If you have registered a fingerprint for the root user (start fingerprint-gui with sudo to do this), you can “su” with root's finger. Open a terminal and type “su”. The terminal should prompt as follows:

   > Password:

   > Fingerprint Login 1.06

   > Authenticating root

   > Swipe your finger or type your password:

   No GUI widget should appear and you should be able to “su” with root's password or root's fingerprint.

3. login (in a secure tty): Change to a secure tty (Ctrl-Alt_F2), type your username and press enter. You'll be prompted with:

   > Password:

   > Fingerprint Login 1.06

   > Authenticating <username>

   > Swipe your finger or type your password:

   You should be able to login with your password or your fingerprint.

4. gnome-screensaver: Lock your screen and move the mouse. The unlock dialog should appear and a GUI widget requesting a finger-swipe should appear below. Unlocking should work with password and with fingerprint.

5. gdm login: Logout from your gnome session and try to login with your fingerprint again. Please note: This will not work if you have an encrypted home directory. Please read about “password on external media” in the user's manual about this problem and it's solution.

6. policykit-1: Before you can test policykit-1 you must reboot or kill the “polkit-gnome-authentication-agent-1” or the “polkit-kde-authentication-agent-1” for your session and start the /usr/lib/fingerprint-polkit-agent manually. Then open “System | Administration | Users and Groups” and click the “Advanced Settings” button. A GUI dialog should appear, requesting a password and a finger-swipe for a user with administration rights. Unlocking the advanced settings should be possible with fingerprint and with password as well.

## Advanced Tests

By default, the GDM (and other display managers) login screen presents a list of users possible for login. Fingerprint GUI is not only able to authenticate a user by his fingerprint but can “identify” the user by a one-to-many comparison of the given finger-swipe to all available fingerprint data for login. This allows to “switch off” the userlist and to identify and login an user only by his fingerprint. On Ubuntu 10.10 you can open “System | Administration | Login Screen”, unlock it and uncheck the “Show list of users” entry. On other GDM versions you can execute the following command to disable the user list (this is one line): "sudo gconftool-2 --direct --config-source xml:readwrite:/etc/gconf/gconf.xml.defaults --type bool --set /apps/gdm/simple-greeter/disable_user_list true". After this is done, you can logout. The GDM greeter should show only the username-prompt and the fingerprint widget now. By swiping your finger, the system should recognize you and login you immediately.

When authenticating an user for an administrative task by policykit-1, an user who is member of the admin group is requested to authenticate. If there are more than one users members of this group, a list of admin users is shown by fingerprint-polkit-agent for selecting the user to be authenticated. You should be able to select the user and, depending whether fingerprint data for this user is availbale, the fingerprint widget should be shown or not below the password field for authentication. If the current user is member of the admin group, this user will be preselected.

## Known Limitations

While requesting a finger-swipe, the fingerprint device is opened exclusively. This means you can not authenticate by fingerprint for more than one service at the same time. For example you can not request “su” in one terminal and “sudo something” in another. In this case both authentications will fail.

Because pam_fingerprint-gui.so always requests a fingerprint and a password at the same time, an <enter> key is fed into the password prompt by libfakekey or uinput, when the user was authenticated by his fingerprint. If the keyboard focus has been moved away from the requesting application, this <enter> key can not complete the password prompt and the authentication procedure “hangs”. For example open two terminals, then perform a “sudo something” in one terminal and click into the other one before swiping your finger. The authentication for sudo will fail.