Fingerprint Reader

Submitted by Wolfgang Karall... on Wed, 2005-11-02 09:40

Finally found time to fiddle around with the fingerprint reader, and getting it to work was easier than I thought. The HowTo in the ThinkWiki was very helpful, as usual.

There are 4 components to make the whole thing work:

the BioAPI framework to use various biometric authentication systems, Debian packages (and lots of infos about Linux and Biometrics) can be found at Michael R. Crusoe's great website http://www.qrivy.net/~michael/blua/. Note: I used the package (version 1.2.3) found in http://www.qrivy.net/~michael/temp/ because it was the only version that worked in all respects. YMMV.
the driver (called Biometric Service Provider, BSP) for the fingerprint reader in the Thinkpad provided by UPEK, Inc., the direct link to the download page is http://www.upek.com/support/dl_linux_bsp.asp.
the pam_bioapi module found at http://www.qrivy.net/~michael/blua/pam_bioapi/, which makes the BioAPI accessible from the Linux PAM system.
a pam configuration for the services that should use the fingerprint reader, e.g. the login in the text console or in the graphical display manager. And of course you need to collect fingerprints of the users that should be able to use the reader for authentication. If no sample fingerprints are found or if they do not match, the system falls back to using passwords.

BioAPI framework

Just installe the downloaded .deb file with

dpkg -i bioapi_1.2.3_i386.deb

Ignore the warning about not finding /usr/lib/libqtpwbsp.so, it's not fatal.

UPEK Fingerprint BSP

The software comes in a zip file, so

apt-get install unzip

if you haven't got it installed already. Then create a new directory and change into it, then unpack and install the driver:

mkdir fingerprint-driver
cd fingerprint-driver
unzip -q /path/to/the/downloaded/UPEK_BSP_file.zip
sh install.sh

pam_bioapi

It's necessary to use a patch from http://badcode.de/downloads/fingerprint.patch to make the pam module work, I also attached the fingerprint.patch file below in case it vanishes from the current URL.

Otherwise the installation is straightforward with the usual 3 steps ./configure, make and make install: (make sure you have libpam-dev or specifically libpam0g-dev installed)

tar -xjf /path/to/the/downloaded/pam_bioapi-0.2.1.tar.bz2 
cd pam_bioapi-0.2.1/
patch -p0 < /path/to/the/downloaded/fingerprint.patch
./configure
make
make install

Enrolling users and PAM configuration

Since the BioAPI framework could work with various biometric devices each and every one of them has a unique serial number (a long hexadecimal number) called Module ID. The process of gathering sample fingerprints and the PAM configuration both need the Module ID of your fingerprint reader. You can print the ID in the needed format with the following rather ugly command:

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

The result, in my case {5550454b-2054-464d-2f45-535320425350} (check if your ID differs and change accordingly in the following steps), is needed in several places. First create a directory in /etc/bioapi1.10/pam with that name, e.g. with

mkdir -p /etc/bioapi1.10/pam/{5550454b-2054-464d-2f45-535320425350}

Into that directory the files containing the sample fingerprints (one file per user, with .bir as extension) need to be copied. Creating these files is done using the Sample program that comes with the UPEK software (in the NonGUI_Sample subdirectory), which needs to be made executable first. Then run it (from the current directory with ./Sample), choose "enroll" and enter a valid username. You'll then be prompted to collect 3 fingerprints. Once you're done, choose "quit" and look into the current directory. It should contain a .bir-file for the username you just entered. Copy that file into the directory created in the last step. E.g. for the user spiney:

cd /path/to/fingerprint-driver/NonGUI_Sample
chmod a+x  Sample 
./Sample 
cp spiney.bir /etc/bioapi1.10/pam/{5550454b-2054-464d-2f45-535320425350}

Repeat for each user you want to use the fingerprint reader with.

The next and final step is to configure services to use the pam_bioapi module as authentication source. For each PAM-aware service there's a configuration file in /etc/pam.d/ plus the fallback configuration file called common-auth which you could use to enable the reader system-wide. I just enabled it for gdm (the Gnome Display Manager, i.e. the graphical login) and login (for the text consoles) by adding the following line before the line with @include common-auth:

auth       sufficient /usr/local/lib/security/pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi1.10/pam/

Note: by using the complete path to the pam_bioapi.so module it's not necessary to copy it to /lib/security.

After that logging in using the fingerprint reader should work for configured services. If not, check /var/log/auth.log for any pam-related error messages.

Using the fingerprint reader with programs that run as unprivileged user

For PAM-aware applications like xscreensaver which are run as normal user without root privileges it's necessary to change the permissions on two files so that files can be read and written:

/var/log/BSP.log (the log file of the UPEK driver, since this is a beta release there's no way to disable logging)
the entry for the fingerprint reader USB devices in the /proc filesystem, something like /proc/bus/usb/004/002

The latter can be printed with the following command:

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

Either set to permissions on both to world read/writeable (pass 666 to chmod, probably ok security-wise since notebooks are single user systems in most cases) or assign a special group to them and give it write permission, and then add all users that should be able to use the fingerprint reader to that group. In my case I used the group adm, because my normal user was already member in it (I do like to read log files without changing to root). So I did the following

chgrp adm /var/log/BSP.log
chmod g+rw /var/log/BSP.log
DEVICE=/proc/bus/usb/`lsusb | sed -ne "/0483:2016/s/Bus\ \(.*\)\ Device\ \(.*\):\ .*/\1\/\2/p"`
chgrp adm $DEVICE
chmod g+rw $DEVICE

Since you have to set the permissions on the proc entry every time you boot (or come back from suspend/hibernation), it's best to put the last three lines into some shell script that gets run every time you boot.

Now also non-root users can use the fingerprint reader. The only application at the moment that comes to mind and is PAM-capable is xscreensaver. It needs a patch from http://nax.hn.org/pub/bioapi/xscreensaver-4.22_alternativeAuth.diff by Josef Hajas so that you are first asked to swipe your finger and it falls only back to password authentication when that fails. You can either get the source code from the xscreensaver website, but if you run Debian sid you can also download my patched xscreensaver package (built from the current source from Debian via apt-get source) which is attached below. I'll try to keep them updated whenever there's a new version in Debian until the patch makes it into the xscreensaver source code upstream. But I disclaim all warranties regarding that package, so beware!

Now just change /etc/pam.d/xscreensaver to

#
# /etc/pam.d/xscreensaver - PAM behavior for xscreensaver
#

auth       sufficient /usr/local/lib/security/pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi1.10/pam/
@include common-auth

and add the following option

alternativeAuth: True

to your ~/.xscreensaver configuration file, restart xscreensaver and you're set. Lock the screen, press a key and there should be the window telling you to swipe your finger over the reader.

Again, if it doesn't work, take a look into /var/log/auth.log and check those file permissions.

New patch for xscreensaver

Since the original patch was sometimes confusing to the user (see Brice Goglin's comment below) I tried to come up with a different approach: use a different PAM configuration for xscreensaver when using the alternativeAuth option.

Below is the patch (xscreensaver-4.23_fingerprint.patch) and also an updated version of the package for Debian sid (xscreensaver_4.23-3fingerprint_i386.deb). To use it, follow the instructions above, but instead of modifying /etc/pam.d/xscreensaver (if you did already, remove the bioapi line again), create a new file /etc/pam.d/xscreensaver-alternative with the following content:

#
# /etc/pam.d/xscreensaver-alternative - PAM behavior for xscreensaver
#                                       when running with alternativeAuth
#

auth       sufficient /usr/local/lib/security/pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi1.10/pam/

Again, I disclaim all warranties regarding the patch and the package, so beware!

Attachment	Size
fingerprint.patch	1.07 KB
xscreensaver_4.23-2fingerprint_i386.deb	3.6 MB
xscreensaver-4.23_fingerprint.patch	8.9 KB
xscreensaver_4.23-3fingerprint_i386.deb	3.6 MB

Sections:

Printer-friendly version

Comments

Anonymous (not verified)

Tue, 2005-12-06 05:49

Main menu

You are here