The FingerPrint Reader

    The fingerprint reader is a UPEK Touchchip. UPEK provides a binary driver for FreeBSD and there is some documentation here on how to install it and get it going. 

    I am running FreeBSD 7-Stable (as of August 04, 2008) and the above documentation did not quite work for me.  The bsp_upekmess port would compile but gave me an error when running it.  The error was due to a bump in the gettext version.  I have a modified version of the port here that can be used to install the new driver available from UPEK that fixes this problem.  I’m sure this update will be included in the FreeBSD ports tree soon.

    Here is the procedure I used to install the UPEK driver and get my fingerprint reader working (most of this information is also included in the documentation on

Install the bsp_upekfmess port (the UPEK driver).

# cd /var/tmp
# fetch
# tar -xvzf bsp_upekfmess.tgz
# cd bsp_upekfmess
# make install
# make clean
# cd /var/tmp
# rm -r bsp_upekfmess

Install the pam_bsdbioapi port (the Biometric PAM module).

# cd /usr/ports/security/pam_bsdbioapi
# make install
# make clean

Setting up the configuration

    The pam_bsdbioapi port installs the libbirdb library.  This lib controls access to the different database backends possable for storing the biometric information.  In my setup, I just used the recomended file system database (filedb).  The default sample configuration is fine for most setups so just copy it into /usr/local/etc.

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

    Now you can check to make sure the backends are available.

# bbdm -l birdb

Installed BIRDB modules
filedb    Filebacked database (b-tree)
plain     Plain text file

Creating the fingerprint record

    You can check to see if the BSP driver was installed correctly and working with the following command. Look for the UPEK TouchChip record (the last one shown here).

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

    Start enrolling users. You can create more than one record for each user (if you are usin the filedb backend) so that if one finger is damaged or cut, you can then use your other finger that is registered.  The finger print reader can also identify the user but only if the records are unique. If you register the same finger for more that one account, then you will have to manually identify the user (not really a problem with the PAM module). 

    The following command creates a new record for the user kirk

# bbdm -b "{5550454b-2054-464d-2f45-535320425350}" -m filedb -c kirk

Enrollment start Put finger
Image processing
Put finger 2nd time
Image processing
Put finger 3rd time
Image processing
Scanned good image
Operation succeeded
Please verify record
Verification start Put finger
Image processing
Scanned good image
Operation succeeded
Record for ``kirk'' created successfully

You can view the created records with the command

# bbdm -b "{5550454b-2054-464d-2f45-535320425350}" -m filedb -r kirk

Records for user ``kirk''
1 Tue Aug 05 08:10:09 2008
2 Tue Aug 05 07:35:24 2008

To verify a record for the user kirk

# bbdm -b "{5550454b-2054-464d-2f45-535320425350}" -m filedb -v kirk

Verification start
Put finger
[SWIPE FINGER] Image processing
Scanned good image
Operation succeeded
Verification sucessful
User record verified (creation time Tue Aug 05 08:10:09 2008)

Configuring PAM for fingerprint logins

    This setup will configure PAM to allow both fingerprint and password login. After the username is entered, it will prompt for you to swipe your finger print. If you don’t have one registered for that user, it will then prompt for the password.

    The configuration is done in the /etc/pam.d/system file.  Edit the file to look like the following:

# auth
auth      sufficient     no_warn no_fake_prompts
auth      requisite   no_warn allow_local
#auth      sufficient     no_warn try_first_pass
#auth      sufficient      no_warn try_first_pass
auth      sufficient  /usr/local/lib/ {5550454b-2054-464d-2f45-535320425350} filedb
auth      required     no_warn try_first_pass nullok

    This sets up PAM so that it will take the fingerprint as the password but if the fingerprint is wrong or there is no password, it will still accept the password.  If you want to change PAM so that it must have a valid fingerprint, then change the “sufficient” keyword to “required”, but be carefull, you could lock your self out if you do not have a fingerprint registered.

Some minor Patches

    After setting up the PAM authentication I was able to login as a user but was not able to login at the console as root.  I know… “shouldn’t login as root!” but it was causing the login process to core dump. Not good! I was able ot track it down to the dynamic library libutil that login was compiled against.  The quickest way to fix that was to recompile login with a static libutil.a.  Here is a patched version of the login Makefile that will fix this problem. It’s still not the best fix as you will have to apply this patch every time you upgrade your system. If anyone comes up with a better solution, please let me know.

    Applying the patch…

# cd /usr/src/usr.bin/login
# fetch
# patch < login.patch
# make
# make install

    NOTE: Flip to another virtual terminal and make sure you are able to login before you logout. You wouldn’t want to find out that you have locked yourself out of the system!

Leave a Comment

Your email address will not be published. Required fields are marked *