Getting the integrated fingerprint reader on my laptop to work in Linux

My Compal NBLB2 laptop has a built-in Upek TCS5B fingerprint scanner:

$ lsusb | grep -i upek
Bus 002 Device 003: ID 147e:1001 Upek

I’m running 64-bit multilib Gentoo Linux with KDE 4.8.1 on this laptop. I decided it was about time I got the built-in fingerprint scanner/sensor working.

The FOSS application Fingerprint GUI caters for this model of fingerprint reader, as well as several other models: see the application’s Home Page (Ref. 1 at the end of this post) for a list of the models supported.

The Gentoo Bugzilla has a bug report (Ref. 2) that I found very helpful (my thanks, in particular, go to Jan Buecken), but the ebuilds in it were not for the latest version of Fingerprint GUI, which is 1.04 as I write this. The required packages are sys-auth/fingerprint-gui and sys-auth/upekbsapi-bin. So I had to modify a little the ebuilds from the Gentoo Bugzilla, and I installed the packages using a Portage local overlay as explained below (/etc/make.conf had already been edited accordingly and /usr/local/portage/profiles/repo_name had already been created).

1. First I created the local overlay directories for the two packages:

# mkdir -p /usr/local/portage/sys-auth/fingerprint-gui
# mkdir -p /usr/local/portage/sys-auth/upekbsapi-bin

2. Then I edited the fingerprint-gui-1.03 ebuild from Ref. 2 to create the file /usr/local/portage/sys-auth/fingerprint-gui/fingerprint-gui-1.04.ebuild containing:

# Copyright 1999-2011 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

EAPI=3

inherit qt4-r2 versionator

MAKEOPTS="$MAKEOPTS -j1"

MY_PV=$(replace_version_separator 2 -)
DESCRIPTION="Use Fingerprint Devices with Linux"
HOMEPAGE="http://www.n-view.net/Appliance/fingerprint/"
SRC_URI="http://www.n-view.net/Appliance/fingerprint/download/${PN}-${MY_PV}.tar.gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~amd64"
IUSE="upekbsapi"

DEPEND=">=sys-auth/libfprint-0.1.0_pre2
|| ( ( x11-libs/qt-core:4 x11-libs/qt-gui ) x11-libs/qt:4 )
>=app-crypt/qca-2.0.0
>=app-crypt/qca-ossl-2.0.0_beta3
x11-libs/libfakekey
>=dev-libs/libusb-1.0.0
sys-auth/polkit-qt
sys-libs/pam
!sys-auth/pam_fprint
!sys-auth/fprintd
!sys-auth/thinkfinger
"
RDEPEND="${DEPEND}
upekbsapi? ( sys-auth/upekbsapi-bin[headers] )"

S=${WORKDIR}/${PN}-${MY_PV}

src_configure() {
if has_version '>=sys-auth/polkit-qt-0.99.0'; then
eqmake4 LIBPOLKIT_QT=LIBPOLKIT_QT_1_1 || die "qmake4 failed"
else
eqmake4 || die "qmake4 failed"
fi
}

src_install() {
emake INSTALL_ROOT="${D}" DESTDIR="${D}" install || die "emake install failed"

domenu bin/fingerprint-gui/fingerprint-gui.desktop

dodoc CHANGELOG README COPYING\
doc/*.html\
doc/*.png
}

pkg_postinst() {
elog "1) Please see /usr/share/doc/${P}/Install-step-by-step.html to configure your device."
elog "   A fast (not recommended) way to use fingerprint-gui with your pam based application"
elog "   you can add the following line to the first off /etc/pam.d/system-auth"
elog "   auth        sufficient  pam_fingerprint-gui.so"
elog "   For more security we recommend that you don't enable fingerprint-gui authentication for all pam services."
elog "   See Install-step-by-step.html again."
elog "2) You must be in the plugdev group to use fingerprint"
if use upekbsapi; then
elog "3) You select to install upeks bsapi library, it's not open-sourced. Use it on your own risk."
fi
}

3. I edited the upekbsapi-bin-3.5.2.ebuild from Ref. 2 to create the file /usr/local/portage/sys-auth/upekbsapi-bin/upekbsapi-bin-3.5.2.ebuild containing:

# Copyright 1999-2010 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

EAPI=3

FP_GUI=fingerprint-gui-1.04
MY_PN=${PN/bsapi-bin/}
DESCRIPTION="UPEK Biometric Services SDK for PC"
HOMEPAGE="http://www.upek.com/solutions/eikon/default.asp"
SRC_URI="http://www.n-view.net/Appliance/fingerprint/download/${FP_GUI}.tar.gz"

LICENSE="EULA"
SLOT="0"
KEYWORDS="~x86 ~amd64"
IUSE="-headers"

DEPEND=""
RDEPEND="${DEPEND}"

S=${FP_GUI}/${MY_PN}

src_unpack() {
unpack ${FP_GUI}.tar.gz
}

src_install() {
cd "${S}"/
dodoc Readme.pdf releasenotes.txt UPEK_EULA.pdf
if use headers; then
dodoc doc/BSAPI.pdf  doc/BSAPIUsageonLinux.pdf
insinto /usr/include
doins include/bsapi.h
doins include/bserror.h
doins include/bstypes.h
fi
if use x86; then
dolib lib/libbsapi.so
elif use amd64; then
dolib lib64/libbsapi.so
fi
insinto /etc/udev/rules.d
doins 91-fingerprint-gui-upek.rules
dodir /var/${MY_PN}_data
fperms 777 /var/${MY_PN}_data
echo "nvmprefix=\"/var/${MY_PN}_data/.NVM\" dualswipe=0" > ${MY_PN}.cfg
insinto /etc
doins ${MY_PN}.cfg
}

4. Then I entered the following commands to create manifests for the two packages and to merge (install) them:

# cd /usr/local/portage/sys-auth/upekbsapi-bin
# ebuild upekbsapi-bin-3.5.2.ebuild manifest
# cd /usr/local/portage/sys-auth/fingerprint-gui
# ebuild fingerprint-gui-1.04.ebuild manifest
# USE="headers" emerge -1v upekbsapi-bin
# USE="upekbsapi" emerge -1v fingerprint-gui

5. The file /etc/pam.d/system-auth on my laptop contained the following lines:

auth            required        pam_env.so
auth            required        pam_unix.so try_first_pass likeauth nullok
auth            optional        pam_permit.so

account         required        pam_unix.so
account         optional        pam_permit.so

password        required        pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3
password        required        pam_unix.so try_first_pass use_authtok nullok sha512 shadow
password        optional        pam_permit.so

session         required        pam_limits.so
session         required        pam_env.so
session         required        pam_unix.so
session         optional        pam_permit.so

and I edited it to be as follows:

auth            required        pam_env.so
auth            sufficient      pam_fingerprint-gui.so -d try_first_identified
auth            required        pam_unix.so try_first_pass likeauth nullok
auth            optional        pam_permit.so

account         required        pam_unix.so
account         optional        pam_permit.so

password        required        pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3
password        required        pam_unix.so try_first_pass use_authtok nullok sha512 shadow
password        optional        pam_permit.so

session         required        pam_limits.so
session         required        pam_env.so
session         required        pam_unix.so
session         optional        pam_permit.so

6. The UPEK fingerprint scanner on my laptop is Device 003 on USB Bus 002:

# lsusb | grep -i upek
Bus 002 Device 003: ID 147e:1001 Upek

As you can see below, the device is correctly a member of the plugdev group:

# ls -la /dev/bus/usb/002
total 0
drwxr-xr-x 2 root root 120 Mar 20 15:31 .
drwxr-xr-x 4 root root 80 Mar 20 15:31 ..
crw-rw-r-- 1 root usb 189, 128 Mar 20 15:31 001
crw-rw-r-- 1 root usb 189, 129 Mar 20 15:31 002
crw-rw-r-- 1 root plugdev 189, 130 Mar 20 17:37 003
crw-rw-r-- 1 root usb 189, 131 Mar 20 15:31 004

and my user account is a member of the plugdev group too:

$ groups
disk lp wheel floppy uucp cron audio cdrom dialout video games cdrw usb users kismet clamav haldaemon plugdev scanner pulse-access pulse-rt pulse kvm crontab vboxusers polkituser

7. I don’t think it was necessary to do, but I changed the file permissions to make sure all the devices on Bus 002 were completely accessible:

# chmod 777 /dev/bus/usb/002 -R
# ls -la /dev/bus/usb/002
total 0
drwxrwxrwx 2 root root 120 Mar 20 15:31 .
drwxr-xr-x 4 root root 80 Mar 20 15:31 ..
crwxrwxrwx 1 root usb 189, 128 Mar 20 15:31 001
crwxrwxrwx 1 root usb 189, 129 Mar 20 15:31 002
crwxrwxrwx 1 root plugdev 189, 130 Mar 20 17:37 003
crwxrwxrwx 1 root usb 189, 131 Mar 20 15:31 004

When I reboot, the file permissions revert to those shown in Step 6 above anyway.

8. Two udev rules files were created when I installed the packages:

# locate fingerprint | grep rule
/etc/udev/rules.d/91-fingerprint-gui-upek.rules
/lib64/udev/rules.d/91-fingerprint-gui-upek.rules

The file /etc/udev/rules.d/91-fingerprint-gui-upek.rules contained the following:

# udev rules for fingerprint-gui (libbsapi)

# set permissions
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="201[56]",   SYMLINK+="input/touchchip-%k", MODE="0664", GROUP="plugdev"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="201[56]",   SYMLINK+="input/touchchip-%k", MODE="0664", GROUP="plugdev"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="100[0123]", SYMLINK+="input/touchchip-%k", MODE="0664", GROUP="plugdev"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="300[01]",   SYMLINK+="input/touchchip-%k", MODE="0664", GROUP="plugdev"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="500[23]",   SYMLINK+="input/touchchip-%k", MODE="0664", GROUP="plugdev"

# enable power saving
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="201[56]",   ATTR{power/control}=="*", ATTR{power/control}="auto"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="201[56]",   ATTR{power/control}=="*", ATTR{power/control}="auto"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="100[0123]", ATTR{power/control}=="*", ATTR{power/control}="auto"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="300[01]",   ATTR{power/control}=="*", ATTR{power/control}="auto"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="500[23]",   ATTR{power/control}=="*", ATTR{power/control}="auto"

The file /lib64/udev/rules.d/91-fingerprint-gui-upek.rules contained the following:

# udev rules for fingerprint-gui (libbsapi)

# set permissions
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="201[56]", SYMLINK+="input/touchchip-%k", MODE="0664", GROUP="plugdev"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="201[56]", SYMLINK+="input/touchchip-%k", MODE="0664", GROUP="plugdev"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="100[01]", SYMLINK+="input/touchchip-%k", MODE="0664", GROUP="plugdev"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="3000",    SYMLINK+="input/touchchip-%k", MODE="0664", GROUP="plugdev"

# enable power saving
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="201[56]", ATTR{power/level}=="*", ATTR{power/level}="auto"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="201[56]", ATTR{power/level}=="*", ATTR{power/level}="auto"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="100[01]", ATTR{power/level}=="*", ATTR{power/level}="auto"
ATTRS{idVendor}=="147e", ATTRS{idProduct}=="3000",    ATTR{power/level}=="*", ATTR{power/level}="auto"

9. After reading a post in the Fingerprint GUI Forum (see quote further on) I decided to delete a file in /var/upek_data/ but, in retrospect, I’m not sure it was necessary, and, in any case, the file was subsequently recreated (perhaps when I reinstalled the packages?) and apparently has no adverse effect at present:

# ls -la /var/upek_data/
# rm /var/upek_data/.NVMe3031dcc911668f65aaeb5209f4db5ad5be21fbdbc810ac101963da0bf952f9a.bin

I had decided to delete the file because I was seeing the error message “ABSOpen() failed -1057 (Fingerprint sensor device communication error.)” in the log file /var/log/messages, and a post in the Fingerprint GUI Forum suggested deleting the file:

> Setting up the NVM emulation caused fingerprintGUI not to directly display the error, but after a second or two. Auth.log now shows a different error.

Yes. This one:

ABSOpen() failed -1057 (Fingerprint sensor device communication error.)

In some cases I’ve seen that removing all *.bin files in /var/upek/ did help. Try it.

In other cases there was some other process which had held open the device (e.g. a virtual machine running Windows on that host).

W.U.

Wolfgang Ullrich
March 18th, 2010 10:06am

(The Fingerprint GUI Forum refers to error messages being in a log file /var/log/auth.log, but, in my case, they were in the log file /var/log/messages.)

10. Anyway, now when I press e.g. Ctrl-Alt-F2 to open a VT, as usual I see a login prompt:

meshedgedx login:

However, when I enter my username and press Enter, not only is the usual Password prompt displayed but some additional text is displayed below it:

meshedgedx login: fitzcarraldo
Password:
Fingerprint Login 1.04
Authenticating fitzcarraldo
Swipe your finger or type your password:

If I enter my password, I am logged in as usual. But if I instead swipe my finger on the fingerprint scanner, I am also logged in. Nice. :-)

11. If I open a Konsole window and enter any command using sudo, let’s say sudo whoami for example, I am prompted as usual for my user password but now a GUI widget (see image below) also pops up prompting me to swipe my finger over the fingerprint scanner. Either entering my password or swiping my finger will allow me to launch the command. Nice. :-)

Fingerprint GUI widget

12. The instructions in Ref. 3 say to launch fingerprint-gui using sudo to register a fingerprint for the root user (i.e. to enable you to use the fingerprint scanner in order to log in as root user from e.g. a Konsole/Terminal window). In fact I had to use the command kdesu fingerprint-gui to launch Fingerprint GUI and register a fingerprint to enable me to log-in as the root user either by entering the root user’s password as usual or by swiping my finger. Having done that, now when I enter the su command in a Konsole window I am prompted to enter the root user’s password as usual but am also prompted to swipe my finger instead if I want:

$ su
Password:
Fingerprint Login 1.04
Authenticating root
Swipe your finger or type your password:
OK
No protocol specified
No protocol specified
#
# whoami
root
#

Nice. :-)

By the way, this also means I can swipe my finger to log-in as root user via a VT.

According to the Fingerprint GUI Forum, the error messages “No protocol specified” shown above are confined to KDE. It is possible to avoid them by using an export command first:

$ export XAUTHORITY=~/.Xauthority
$ su
Password:
Fingerprint Login 1.04
Authenticating root
Swipe your finger or type your password:
OK
#
#

I simply added the export command to my ~/.bashrc file, and the problem is fixed.

13. My only problem now is with the kdesu command: I have to enter both the root user's password and swipe my finger to launch an application using kdesu. For example, if I enter the command kdesu kwrite in a Konsole window, I am first prompted by a KDE pop-up window to enter the root user's password as usual, and, once I have entered the password in that window, I am then prompted in the Konsole window to swipe my finger. I have to do both in order for the kdesu command to execute.

14. According to Ref. 1, a limitation in KDM means that it is not possible to use the fingerprint scanner to log-in to KDE (although no such limitation exists in the case of GDM: see Ref. 3 for details). However, I'm using KDM and KDE 4.8.1 and, as soon as I enter my user name on the KDM login page, the Fingerprint GUI window pops up prompting me to swipe a finger or type my login/password. If I do either then I am logged in to KDE. Nice. :-)

So, there you have it: Fingerprint GUI 1.04 + UPEK BSAPI SDK for Linux 3.5.2 + KDE 4.8.1 + Gentoo Linux + Upek TCS5B (147e:1001) fingerprint scanner are a working combination. Kudos to Wolfgang Ullrich for creating Fingerprint GUI (and the Web site to accompany it).

REFERENCES

1. Fingerprint GUI

2. Gentoo's Bugzilla – Bug Report No. 341105 – fingerprint-gui (new package)

3. Fingerprint GUI Step-by-Step Manual

4. Fingerprint GUI User's Manual

EDIT (May 23, 2012): An ebuild for Fingerprint GUI was added to the Portage main tree on May 21, 2012. It is not identical to the ebuild I posted here a couple of months ago but also installs version 1.04 of the utility, so try merging the package from the main Portage tree as that is an easier way to install it.

Follow

Get every new post delivered to your Inbox.

Join 49 other followers