UPEK TouchChip TFM/ESS Fingerprint BSP on FreeBSD

Reversed engineered GPL drivers exists

UPEK offers a large numer of different fingerprint sensors, both embedded solutions and stand-alone USB-readers. Their fingerprint sensors can be found in many devices such as IBM Thinkpad notebooks, ASUS notebooks, NEC Versa notebooks and some Samsung notebooks. A full list is available athttp://www.upek.com/solutions/pc_and_networking/default.asp

Since February 2006 UPEK provides a native driver for FreeBSD, although it is binary only and closed source. The binary itself is available at http://www.upek.com/support/dl_freeBSD_bsp.asp. This article shows how to get it working with FreeBSD.

Document revisions

20060224 – Updated to reflect pam_bsdbioapi 1.5

Requirements

  • Atleast FreeBSD 6.0-RELEASE
  • BioAPI (security/bioapi)
  • UPEK TouchChip TFM/ESS Fingerprint BSP (security/bsp_upektfmess)
  • pam_bsdbioapi (security/pam_bsdbioapi) for PAM autentication

Identifying the sensor

Take a look at your /var/run/dmesg.boot, you should have something like this

ugen0: STMicroelectronics Biometric Coprocessor, rev 1.00/0.01, addr 2

usbdevs reports vendor id 0×0483 and device id 0×2016

Swipe sensors based on the chipset TCD42/TCS3C (such as IBM) should be supported (these devices does fingerprint matching in hardware). It does not work on “sensor only” models where matching is done in software.  Also, older models based on the TCD41/TCS3B chipset (Sony laptops) are also not supported.

Installing

Everything is available through FreeBSD ports.

> cd /usr/ports/security/bsp_upektfmess && make install
> cd /usr/ports/security/pam_bsdbioapi && make install

These instructions are for pam_bsdbioapi 1.5

Configuring

A large part of the pam_bsdbioapi package is libbirdb. This library allows multiple database backends for BIR (Biometric Identification Record) storage.

A sample configuration file should have been placed in /usr/local/etc/birdb.conf.sample.
It contains acceptable default values and you should be fine unless you have special requirements.

> cp /usr/local/etc/birdb.conf.sample /usr/local/etc/birdb.conf

This file tells libbirdb which backend modules that are available and which options they require.
You should now check that the configured backends are identified correctly

> bbdm -l birdb
Installed BIRDB modules
filedb   Filebacked database (b-tree)
plain    Plain text file

Selecting a backend module

This depends on your requirements. However, “filedb” is recommended for normal usage.
Note, if you need backwards compatibility with previous versions of pam_bsdbioapi you must use the “plain” backend.

If you want to use a MySQL database as a backend, you must create a database and table. See the pam_bsdbioapi documentation for more information.

Creating fingerprint records

First, check if the BSP was installed correctly

> bbdm -l bsp
UUID {ffffffff-ffff-ffff-ffff-ffffffffffff}
Example Vendor libbioapi_dummy100.so (BioAPI v1.1 Dummy BSP)
UUID {263a41e0-71eb-11d4-9c34-124037000000}
BioAPI Consortium libpwbsp.so (BioAPI Password BSP)
UUID {5550454b-2054-464d-2f45-535320425350}
UPEK, Inc. libtfmessbsp.so (TouchChip TFM/ESS Fingerprint BSP)

Now enroll the user(s) to whom you want to add fingerprint login. To enroll the user “foo” with the database backend “filedb”, run the following

> bbdm -b "{5550454b-2054-464d-2f45-535320425350}" -m filedb -c foo
Enrollment  start
Put finger
[SWIPE FINGER]
Image processing
Put finger 2nd time
[SWIPE SAME FINGER AGAIN]
Image processing
Put finger 3rd time
[SWIPE SAME FINGER AGAIN]
Image processing
Scanned good image
Operation succeeded
Please verify record
Verification start
Put finger
[SWIPE SAME FINGER AGAIN]
Image processing
Scanned good image
Operation succeeded
Record for ``test'' created successfully

You might get error messages saying that your finger is not centered correctly, or that you swiped too fast. Just swipe your finger again if this happens.

You can create any number of records for each user (except for the plain backend which only supports one).

You can view the created records with

> bbdm -b "{5550454b-2054-464d-2f45-535320425350}" -m filedb -r foo
Records for user ``test''
1        Fri Feb 24 10:00:12 2006
2        Fri Feb 24 09:55:51 2006

If you want, you can now try verifying your newly created record.

> bbdm -b "{5550454b-2054-464d-2f45-535320425350}" -m filedb -v foo
Verification start
Put finger
[SWIPE FINGER]
Image processing
Scanned good image
Operation succeeded
Verification sucessful
User record verified (creation time Fri Feb 24 09:55:51 2006)

It also supports user identifying, however if you enroll the “same”
biometric data for alot of users this will not work correctly because it
will stop on the first match.

> bbdm -b "{5550454b-2054-464d-2f45-535320425350}" -m filedb -i
Verification start
Put finger
[SWIPE FINGER]
Image processing
Scanned good image
GUI finished
User identified as ``foo''

Configuring PAM to allow fingerprint authenticated login

To allow both biometric login and password based login you should configure /etc/pam.d/system in the following way (this is for the “filedb” backend)

# auth
auth        sufficient  pam_opie.so     no_warn no_fake_prompts
auth        requisite   pam_opieaccess.so   no_warn allow_local
#auth       sufficient  pam_krb5.so     no_warn try_first_pass
#auth       sufficient  pam_ssh.so      no_warn try_first_pass
auth        sufficient  /usr/local/lib/pam_bsdbioapi.so {5550454b-2054-464d-2f45-535320425350} filedb
auth        required    pam_unix.so     no_warn try_first_pass nullok

The “sufficient” keyword will allow fallback to pam_unix if no biometric data was found for a user or if biometric login failed. Change this to “required” if you want to force biometric login.

Now, you can try to login as the user you previously enrolled.

FreeBSD/i386 (genesis) (ttyv0)

login: foo
Verification start
Put finger
[SWIPE FINGER]
Image processing
Scanned good image
Operation succeeded
Last login: Fri Jan 13 14:51:37 on ttyv1
Copyright (c) 1992-2005 The FreeBSD Project.
Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
The Regents of the University of California. All rights reserved.

foo@genesis>

This also works for “su”, note that you must enroll the user “root” for this

foo@genesis> su
Verification start
Put finger
[SWIPE FINGER]
Image processing
Scanned good image
Operation succeeded
root@genesis>

If you want the ability to create new records with passwd you must configure the “password” service for PAM.

Note that both BSP UUID and the backend alias must match the login service.

password        sufficient    /usr/local/lib/pam_bsdbioapi.so {5550454b-2054-464d-2f45-535320425350} filedb

Example of the user “foo” creating a new record for himself.
Old records are not removed by this, an administrator has to explicitly remove them from the backend database or by using the bbdm tool.

> passwd
Changing local password for foo
Verification start
Put finger
[SWIPE FINGER]
Image processing
Scanned good image
GUI finished
Enrollment  start
Put finger
[SWIPE FINGER]
Image processing
Put finger 2nd time
[SWIPE FINGER]
Image processing
Put finger 3rd time
[SWIPE FINGER]
Image processing
Scanned good image
Operation succeeded
Please verify record...
Verification start
Put finger
[SWIPE FINGER]
Image processing
Scanned good image
GUI finished
Record created successfully

GDM login

pam_bsdbioapi works quite well together with GDM because it supports BioAPI GUI callback messages which are sent to PAM by pam_info and displayed by GDM during the login sequence.

A message file for the UPEK TouchChip included in the distribution and can be found in /usr/local/share/pam_bsdbioapi/upek_touchchip.cmsg

This is how you should configure /etc/pam.d/gdm if you want message feedback during login

auth        sufficient  /usr/local/lib/pam_bsdbioapi.so {5550454b-2054-464d-2f45-535320425350} filedb
-m /usr/local/share/pam_bsdbioapi/upek_touchchip.cmsg

It should be noted that the selected GDM theme must display PAM info messages. Most themes do this, but not all.

Configuring the Touchchip BSP

The touchchip BSP creates a /etc/tfmessbsp.cfg file, unfortunately you can not change this location.

This file contains two settings, hide-capture-success which hides the “Operation succeeded” messages. And security-level which can be used to raise and lower the the security level. The default value is medium security. If you want more information on the security level see TFMESS_BSP_FreeBSD.pdf.

Further information

Download the package from UPEKs site and read the included TFMESS_BSP_FreeBSD.pdf, it contains more detailed information.

See also

Comments are closed.