How to enable integrated fingerprint reader with BioAPI

From ThinkWiki
Revision as of 19:58, 12 November 2005 by Spiney (Talk | contribs) (→‎Installing the bioapi source: add link to bioapi Debian packages)
Jump to: navigation, search

This page describes the process of getting the fingerprint reader to work. It is based on experiences in Ubuntu on a T43. The same works on Fedora 4.

Basic driver installation

Getting required libs and tools

Installing the bioapi framework

Binary packages
  • 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.
Installing from source
  • Get the bioapi source:
$ wget http://www.qrivy.net/~michael/blua/bioapi/bioapi-1.2.2.tar.bz2
  • I could not compile bioapi with the graphical Qt tools. To do it manually, do the following:
$ tar xjf bioapi-1.2.2.tar.bz2
$ cd bioapi-1.2.2
$ ./configure --with-Qt-dir=no
$ make
and then as root
# 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!

Installing the driver

# sh install.sh
  • 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), do the following as root:
# chmod 777 -R /usr/local/var/bioapi/
Actually this depends on where you installed, if you did as suggested, it should work. Otherwise you probably know what you're doing anyways. :)
# touch /var/log/BSP.log && chmod 666 /var/log/BSP.log
# chmod -R a+X /proc/bus/usb
# chmod 666 /proc/bus/usb/`/sbin/lsusb | sed -ne "/0483:2016/s/Bus\ \(.*\)\ Device\ \(.*\):\ .*/\1\/\2/p"`
It might be nessecary to put the above line into a startup script somewhere.

Testing the driver

Go to the folder where you extracted TFMESS_BSP_LIN_1.0beta2.zip and do:

# cd NonGUI_Sample
# chmod +x Sample
# ./Sample

If it doesn't work, ask for help at: t43fingerprint (at) badcode.de

GDM Login via pam_bioapi

Getting required libs & tools

Installing pam_bioapi

  • Get and compile the pam_bioapi module.
$ wget http://www.qrivy.net/~michael/blua/pam_bioapi/pam_bioapi-0.2.1.tar.bz2
$ tar xjf pam_bioapi-0.2.1.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
NOTE!
If encountering 'rpl_malloc' symbol, remove the related term in the makefile. (FC3)
and as root
# make install
# cp /usr/local/lib/security/* /lib/security/
  • 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/bioapi1.10/pam/$SERIAL
# cp <username>.bir /etc/bioapi1.10/pam/$SERIAL

Configuring pam

The following part is distribution specific. On Ubuntu 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/bioapi1.10/pam/
password   sufficient   pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi1.10/pam/
auth       required     pam_unix.so nullok_secure

With this modification pam immediatelly starts to use the fingerprint reader to do local authorization (e.g. sudo/gdm use the fingerprint reader).

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

On Fedora, you may need to add /usr/local/lib to your LD_LIBRARY path so that the libraries referenced from pam_bioapi.so get picked up properly. Also the original 'session' terms in /etc/pam.d/system-auth need to be kept.

Now gdm should pop up an (ugly) image to swipe your finger and... magic - you can login without a password.

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
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/bioapi1.10/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:
# /sbin/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 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. 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, 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.
Retrieved from "https://www.thinkwiki.org/w/index.php?title=How_to_enable_integrated_fingerprint_reader_with_BioAPI&oldid=12193"