How to enable integrated fingerprint reader with BioAPI

This page describes the process of getting the integrated fingerprint reader to work under Linux. It is based on experiences in Ubuntu on a T43. The same works on Fedora 4, SuSE 9.3, SuSE 10, and Gentoo.

Basic installation

Installing the bioapi framework

Automated installation script

The Script for enabling the fingerprint reader automates the installation of most components (bioapi framework, driver, pam_bioapi, pam setup, device permissions, pamtester and enrolling), for some Linux distributions.

Binary packages

Debian

• If you're using Debian Sid (the unstable branch) you can try the packages from Michael R. Crusoe's site, either version 1.2.3 (recommended) or older versions which might not work with the steps in this howto.
• This seems to work for Ubuntu Breezy/Dapper too, so save yourself some trouble and grab it.

Gentoo

You can either grab the ebuild, or use the source-install procedure below.

Also see http://toe.ch/~tsa/ibm-fingerprint/ for alternative documentation on installing on Gentoo including ebuilds for all the packages used.

Installing from source

• Get the bioapi source:

$ wget http://www.qrivy.net/~michael/blua/bioapi/bioapi-latest.tar.bz2

• I could not compile bioapi with the graphical Qt tools. To do it manually, do the following:

$ tar xjf bioapi-latest.tar.bz2

$ cd bioapi-1.2.2

$ ./configure --with-Qt-dir=no

$ make

and then as root

# make install

If make install fails, be sure you're root and then:

# export LD_LIBRARY_PATH=/usr/local/lib

# make install

and if you want to compile pam_bioapi for auth later

# cp include/bioapi_util.h include/installdefs.h imports/cdsa/v2_0/inc/cssmtype.h /usr/include

Be aware that checkinstall will not work!

(I got through configure with Qt, but got a cryptic build error. It all worked fine with Qt disabled as above)

buzz: This is due to a wrong qt include path, set it manually in configure and everything should work.

• Bioapi (at least version 1.2.2) doesn't compile with GCC4. You need to patch it:

$ wget http://upir.cz/linux/patches/bioapi-1.2.2-gcc4.patch

$ patch -p1 < bioapi-1.2.2-gcc4.patch

• By default, bioapi will install numerous files in /usr/local/{bin,lib,include}, including files with "self-explanatory" names such as /usr/local/bin/Sample. To prevent this pollution:

Create a dedicated directory, for example /opt/bioapi .

Append --prefix=/opt/bioapi to the above ./configure command.

Append /opt/bioapi/bin to $PATH and /opt/bioapi/lib to $LD_LIBRARY_PATH.

When installing the driver (below), tell it the new install path: # sh install.sh /opt/bioapi/lib

Adjusting ldconfigs library search path

At least on Fedora or Aurox Linux 11, you may need to add /usr/local/lib to the library path so that the libraries referenced from pam_bioapi.so get picked up properly. The usual way to do this is adding it to the ldconfig configuration:

# echo '/usr/local/lib' > /etc/ld.so.conf.d/bioapi.conf

# ldconfig

Alternatively you can add it to the LD_LIBRARY variable.

If you see bioapi libs in the output of

# ldconfig -p

then it should work.

Installing and configuring the driver

Installing the driver

• Download TFMESS_BSP_LIN_1.0.zip from the UPEK support site and unzip it into a seperate folder, as it will not create one.
• Change to that folder and do as root:

# sh install.sh

If you're running Gentoo, use

# sh install.sh /usr/lib

If that fails, it may be that make install failed up above -- try setting LD_LIBRARY_PATH, do the make install again, and come back here and try this again. You also need mod_install from bioapi in your PATH.

Configuring permissions for non-root use

If you want to use PAM-aware applications like xscreensaver that are NOT running with root permissions (as opposed to login, gdm or other authentication mechanisms), you may need to do all or at least some of the things in this section. More details on what is necessary on which distributions would be greately appreciated.

• Create two groups, one for access to BioAPI files and the other for access to the usb files. (This is done for full generality; i.e., you may have other USB devices which you want accessable to other users, without exposing your BioAPI configuration to them). Add your normal user (the one you wish to use PAM-aware applications with) to both of these groups.

On Debian this is done with

# addgroup --system bioapi

# addgroup --system usbfs

# adduser yournormaluser bioapi

# adduser yournormaluser usbfs

On SUSE this is done with

# groupadd --system bioapi

# groupadd --system usbfs

# groupmod -A yournormaluser bioapi

# groupmod -A yournormaluser usbfs

On Mandriva this is done with

# groupadd -r bioapi

# groupadd -r usbfs

# usermod -G bioapi,usbfs yournormaluser

(where yournormaluser is your normal user name). You will need to log out and log back in for this to take effect.

• Set permissions on the BioAPI config/registry directory:

# chown -R root:bioapi /usr/local/var/bioapi/

# chmod -R 770 /usr/local/var/bioapi/

(change this path if you used an alternate BioAPI install directory above)

• Set permissions on the files in /proc/bus/usb:

# chown -R root:usbfs /proc/bus/usb

# chmod -R g+X /proc/bus/usb

# chown root:usbfs /proc/bus/usb/`lsusb | sed -ne "/0483:2016/s/Bus\ \(.*\)\ Device\ \(.*\):\ .*/\1\/\2/p"`

# chmod 660 /proc/bus/usb/`lsusb | sed -ne "/0483:2016/s/Bus\ \(.*\)\ Device\ \(.*\):\ .*/\1\/\2/p"`

You may need to replace lsusb with its full path, which is something like /sbin/lsusb or /usr/bin/lsusb depending on your distro. It might be necessary to put these lines into a script which is run at startup and resume from suspend/hibernate.

• As an alternative to the chown/chmod commands above, you can set mount options for usbfs with a line in /etc/fstab; an example would be

none /proc/bus/usb usbfs defaults,devgid=108,devmode=0660,busgid=108,busmode=0770,listgid=108,listmode=0660 0 0

where 108 is replaced with the numerical group ID of the usbfs group (you can determine this with something like cat /etc/group | grep usbfs | cut -d':' -f 3). Make sure you only have one /proc/bus/usb entry in /etc/fstab. See the mount(8) manpage for more information on these options. This is "cleaner" but seems to have a few weird issues -- see the talk page for details.

• You may also have files in /dev/bus/usb, which the driver will try before /proc/bus/usb. If this is another usbfs mount point (mount shows a line containing /dev/bus/usb type usbfs), then simply follow the above instructions with /dev/bus/usb rather than /proc/bus/usb. Otherwise, you may be running a new kernel (i.e. 2.6.15) that makes usbfs-like files available through /dev/bus/usb. On systems running udev these files are dynamically created; you can configure their permissions by editing a udev config file. On Debian this is done by changing the usb_device line of /etc/udev/permissions.rules to read

SUBSYSTEM=="usb_device", MODE="0660", GROUP="usbfs"

• For the beta versions only, there is a logfile, which needs to exist with the proper permissions:

# touch /var/log/BSP.log && chown root:bioapi /var/log/BSP.log && chmod 660 /var/log/BSP.log

Miscellaneous configuration

• To increase the security level (minimize false accept rate), set this in /etc/tfmessbsp.cfg:

security-level="5"

Testing the driver and enrolling a fingerprint

To test the driver and generate the file containing your fingerprint information, you need a sample program included with the driver. The compilation steps below were discovered by trial and error; if they don't work for you, try the binary Sample utility that came with the beta versions of the driver (i.e., TFMESS_BSP_LIN_1.0beta2.zip as mentioned above). Go to the folder where you extracted TFMESS_BSP_LIN_1.0.zip and do:

# cd NonGUI_Sample

Edit main.c and remove (or comment out) the line

#include "port/bioapi_port.h"

# gcc -o Sample main.c -L/usr/local/lib -lbioapi100 -DUNIX -DLITTLE_ENDIAN

# ./Sample

Note that Sample may only run as root, unless you've already configured the usbfs file permissions.

You can try to "e"nroll (to record a fingerprint for an account) and then "v"erify (to test a fingerprint against the one it expects for an account).

You'll save a step later if you use your own login username as the username to enroll here.

Login via pam_bioapi

The following explains how to add fingerprint authentiation to programs that use the PAM (Pluggable Authentication Modules) framework, such as Gnome's GDM and KDE's KDM and screensaver.

Getting required libs & tools

Installing pam_bioapi

• Prerequisites

On SuSE 10, I needed to install the pam-devel RPM

In general, you will need pam itself (standard for most distros) as well as the pam development files (probably an optional package for your distro).

• Get and compile the pam_bioapi module.

$ wget http://www.qrivy.net/~michael/blua/pam_bioapi/pam_bioapi-latest.tar.bz2

$ tar xjf pam_bioapi-latest.tar.bz2

$ cd pam_bioapi-0.2.1

$ wget http://badcode.de/downloads/fingerprint.patch

$ patch -p0 < fingerprint.patch

If you want to, review the patch. In general you should review all code you download and compile, if possible. The patch comes from this thread.

$ ./configure && make

and as root

# make install

# cp /usr/local/lib/security/* /lib/security/

NOTE!

If you get a 'rpl_malloc' error in /var/log/auth.log when trying to use the fingerprint reader, redo these steps and remove the related term from Makefile after running ./configure. (FC3, Debian etch)

• If you get 'PAM [dlerror: /lib/security/pam_bioapi.so: undefined symbol: BioAPIMemoryFuncs]' error in your syslog, replace 'LIBS = ' line in libpam_bioapi/makefile with the following (of course, replace /opt/bioapi/ with the path where you installed bioapi):

LIBS = -L/opt/bioapi/lib -lbioapi100 -lbioapi_mds300 -lmds_util

• Use the sample tool from the fingerprint reader to create <username>.bir (<username> must be the username you want to login with. gdm will probably break for any login name that has no .bir file).
• As root do:

# SERIAL=`BioAPITest | sed -ne "/Fingerprint/{n;n;s/^.*: \(.\{9\}\)\(.\{4\}\)\(.\{4\}\)\(.\{4\}\)\(.*\)/\1-\2-\3-\4-\5/gp}"`

# echo $SERIAL should print something like {5550454b-2054-464d-2f45-535320425350} now.

If it does, do:

# mkdir -p /etc/bioapi/pam/$SERIAL

# cp <username>.bir /etc/bioapi/pam/$SERIAL

If not, you might just try

# SERIAL={5550454b-2054-464d-2f45-535320425350}

as this value is hardcoded into the UPEK docs.

Configuring pam

The following part is distribution specific. On Ubuntu or SUSE you can modify /etc/pam.d/common-auth (on Gentoo and Fedora it is /etc/pam.d/system-auth) to look like this:

#
# /etc/pam.d/common-auth - authentication settings common to all services
#
# This file is included from other service-specific PAM config files,
# and should contain a list of the authentication modules that define
# the central authentication scheme for use on the system
# (e.g., /etc/shadow, LDAP, Kerberos, etc.).  The default is to use the
# traditional Unix authentication mechanisms.
#
auth       sufficient   pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
password   sufficient   pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth       required     pam_unix.so nullok_secure

---

For Gentoo-Users - this allows you to attempt a password first. If you simply press enter, it then prompts for a fingerprints. Create a file named /etc/pam.d/bioapi. This also means that remote services, such as SSH keep working:

auth       required     pam_env.so
auth       sufficient   pam_unix.so likeauth nullok
auth       sufficient   pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth       required     pam_deny.so

account    required     pam_unix.so

session    required     pam_limits.so
session    required     pam_unix.so

---

Now, simply replace "auth include system-auth" in all services that you wish to use fingerprint for with "auth include bioapi". For example, /etc/pam.d/kde by default contains

 auth       include      system-auth
 auth       required     pam_nologin.so
 
 account    include      system-auth
 
 password   include      system-auth
 
 session    include      system-auth

Simply replace the first "system-auth" with bioapi and you can also get rid of KDE desktop lock with a fingerprint. If you do not wish to allow for "password fallback" then remove

auth       sufficient   pam_unix.so likeauth nullok

from /etc/pam.d/bioapi.

ATTENTION!

If su/sudo expects to receive the root password (SuSE 10), you need to have fingerprint settings for root (that is, copy in a root.bir as well as a your-username.bir). Otherwise, they get a segmentation fault. Which is a little unfortunate, given that you need to su or sudo to change your settings...

Note that sshd may pick up the fingerprint settings from /etc/pam.d/common-auth. I didn't want that, so I removed the "auth include common-auth" line from /etc/pam.d/sshd and replaced it with the lines that were originally in my /etc/pam.d/common-auth. That way most local services use the fingerprint reader, but sshd does not.

Another way to do this is to create a file (/etc/pam.d/bioapi for example) which contains the pam_bioapi.so lines, and explicitly @include this before /etc/pam.d/common-auth in the files for services which should use the fingerprint reader. In this case you should leave /etc/pam.d/common-auth alone.

NOTE!

This was discovered through trial and success, if it is plain wrong, wikorrect it, please.

In Fedora the original 'session' terms in /etc/pam.d/system-auth need to be kept.

Hint:

The setup described above will/could affect remote ssh logins to also use biometric logins, which is a bit silly (who wants to remote ssh to the laptop, and then have to walk over to it and swipe your finger)
To avoid that you can copy the default /etc/pam.d/system-auth to /etc/pam.d/sshd which will allow the sshd service to use the standard authentication procedure.

You can do some useful testing with pamtester, which calls the pam modules as if it were a program of your choice. Examples:

# pamtester xdm yourusername authenticate

$ pamtester xscreensaver yourusername authenticate

where yourusername is your username. Note that pamtester should run as root if and only if the program in question does.

Application support

The implementation of fingerprint scanning support in the relevant applications varies.

Here is the behaviour of the most common ones:

• gdm should pop up an (ugly) image to swipe your finger and... magic - you can login without a password.
• kdm doesn't give any visual indication, other than that the cursor stops blinking. Just swipe your finger and hope it lets you log in.
• In xdm, enter your username and a blank password, then swipe (there is no popup as well).
• The KDE screen saver in SUSE 10 requires you to enter an empty password (or select the correct user and then enter an empty password) in order to get the fingerprint prompt.
• For Fedora users, the redhat-config tools will crash if no root.bir presents. Also, there won't be any visual idication unless X server is properly configured for root to access. Just swipe your finger when the HDD stopped blinking or issue the following command in advance:

$ xhost +local:

kdm support

To add graphical popup to kdm, you need following:

• Patch for pam_bioapi. This patch adds third parameter to pam_bioapi.so module, which is a name of file with additional environment variables that will be supplied to the UPEK driver.

# wget http://upir.cz/linux/patches/pam_bioapi-0.2.1-alter-environ.patch

# patch -p1 < pam_bioapi-0.2.1-alter-environ.patch

• Edit your Xsetup file (on SUSE 10 it's /etc/X11/xdm/Xsetup) and add these lines:

echo "XAUTHORITY=$XAUTHORITY" > /var/lib/xdm/kdm_env
echo "DISPLAY=$DISPLAY" >> /var/lib/xdm/kdm_env

• In /etc/pam.d/xdm file, add /var/lib/xdm/kdm_env as a third parameter for pam_bioapi.so module:

auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/xdm/kdm_env

Please note, that this won't work if you have more than one Xserver.

Make xscreensaver use the scanner

• Get the needed xscreensaver sources:

$ wget http://www.jwz.org/xscreensaver/xscreensaver-4.23.tar.gz

$ tar xzf xscreensaver-4.23.tar.gz

$ cd xscreensaver-4.23

$ wget http://nax.hn.org/pub/bioapi/xscreensaver-4.22_alternativeAuth.diff

• After reviewing the patch (it's small and straightforward), do

$ patch -p1 < xscreensaver-4.22_alternativeAuth.diff
The patch prevents xscreensaver from opening an authentification window and dispatches the authentification request to another program, in our case pam and pam_bioapi. It should apply with some offset, don't mind that. If it says something about rejected though, then there's a problem.

• Compile with

$ ./configure --with-pam && make

• If you recieve an error like "undefined reference to `XmuPrintDefaultErrorMessage'" then install the libxmu-dev package and run the previous line again
• and then install as root with

$ su -c make install .

• Make sure that the newly compiled xscreensaver is used:

$ which xscreensaver should return

/usr/local/bin/xscreensaver .

• In case it doesn't, try

$ export PATH=/usr/local/bin:$PATH
and retry.

• Kill the running instance of xscreensaver:

$ xscreensaver-command -exit

• Make sure you have the following line in your ~/.xscreensaver:

alternativeAuth: True

• Now edit /etc/pam.d/xscreensaver to include the following line (If you're on Ubuntu Breezy and you already changed /etc/pam.d/common-auth you should not need to do this.):

auth    sufficient      pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/

• Start the new xscreensaver

$ xscreensaver
There should be a splash screen with version 4.23.

• Now try:

$ xscreensaver-command -lock

If you have questions or problems with this procedure, ask: t43fingerprint (at) badcode.de .

Package for Debian sid

If you're running Debian sid (the unstable branch) you can also try the patched .deb-package (built from current Debian sources fetched with apt-get source) from this page, which also has Debian-specific instructions on how to setup the fingerprint reader. Use it on your own risk.

Troubleshooting and Hints

1. After installing the driver, don't forget to reboot!
   1. This might not be necessary. it worked here without having to reboot.
2. To see if the fingerprint device is know on the USB bus do:

# lsusb

as root and you should see a line like:

Bus 003 Device 004: ID 0483:2016 SGS Thomson Microelectronics

The bus and device number can be different. This should work without the driver installed. If the device does not show up, you have a hardware problem/quirk, Rebooting or removing/inserting USB kernel modules might fix this.

1. For some installation, after installing the driver as in section Installing the driver and making´sure the device is recognized, try to test it by going to NonGUI_Sample directory and run # ./Sample, one get segmentation fault. In this case, try getting the Beta1 instead of Beta2 of the driver and installing it
2. There was some confusion about the /etc/bioapi1.10/pam{5550454b-2054-464d-2f45-535320425350} path, this has been fixed in the howto, if you have problems, check the section again, the path needs to have the '-' in them
3. When something goes wrong look at the tail of /var/log/auth.log. (on Fedora it is /var/log/secure) Specifically if you see an entry saying something like

pam_bioapi[10480]: Unable to load BioAPI BSP with UUID of {5550454b-2054-464d-2f45-535320425350}, BioAPI error #194d.

Check whether your /proc/bus/usb directory permissions are set up as in the section Installing the driver.

1. To get the xscreensaver compiled you might need a bunch of header files (depending on which xscreensaver features you want), in my case I need the following:
   • python-gtk2-dev
   • libgstreamer0.8-dev
   • xlibs-dev
2. Sometimes $HOME/.xscreensaver got overwritten, try changing it to read-only.
3. If after suspending to RAM and resume, lsusb no longer have "SGS Thomson Microelectronics" entry, try adding a line

/etc/init.d/hotplug restart

to your /etc/acpi/resume.sh file

1. If after resume lsusb shows the device but xscreensaver does not ask for fingerprint for login, you might want to check the permission of the usb bus in the appropriate /proc/bus/usb/ entry. If necessesary you might need to add a line to /etc/acpi/resume.sh as in section Installing the driver to set the permission right.

---

If it still doesn't work, ask me for help (and make sure all usefull stuff makes it back into this wiki :) to get a starting point as to where your problem is please include the output of:

$ lsusb

# ldconfig -p | grep bioapi

# updatedb && locate bioapi

t43fingerprint (at) badcode.de