ThinkWiki - User contributions [en]

How to enable integrated fingerprint reader with BioAPI

2009-01-10T07:17:01Z

Dpward: /* Installing from source */

{| width="100%"
|style="vertical-align:top;padding-right:20px;width:10px;white-space:nowrap;" | __TOC__
|style="vertical-align:top" |
This page describes the process of getting the [[Integrated Fingerprint Reader|integrated fingerprint reader]] to work under Linux, using bioapi and binary-only drivers. It is based on experiences in {{Ubuntu}} on a T43. The same works on {{Fedora}} 4 and 5, RHEL4, SuSE 9.3, SuSE 10, and {{Gentoo}}. Note that experimental open-source driver is available, see [[How to enable the fingerprint reader with ThinkFinger|the apropriate page]] for details.
|}

==Basic installation==
===Installing the bioapi framework===
====Automated installation script====
The [[Script for enabling the fingerprint reader]] automates the installation of most components (bioapi framework, driver, pam_bioapi, pam setup, device permissions, pamtester and enrolling), for some Linux distributions.

====Binary packages====

Note that these packages only take care of this one section. If you can use one, you should do so and then proceed to the section entitled, Installing and Configuring the Driver.

=====Debian/ Ubuntu Dapper=====
*If you're using {{Debian}} Sid (the unstable branch) or {{Ubuntu}} Dapper Drake 6.06 LTS you can try the packages from Michael R. Crusoe's site, either [http://www.qrivy.net/~michael/temp/ version 1.2.3] (recommended) or [http://www.qrivy.net/~michael/debs/unstable/ older versions] which might not work with the steps in this howto.

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

=====Gentoo=====
Gentoo now includes needed ebuilds. Just run

''ACCEPT_KEYWORDS=~x86 emerge pam_bioapi''

You can also grab the [http://www.qrivy.net/~michael/blua/bioapi/bioapi-1.2.2.ebuild.tar.bz2 ebuild], or use the source-install procedure below.

Also see [http://toe.ch/~tsa/ibm-fingerprint/ http://toe.ch/~tsa/ibm-fingerprint/] for alternative documentation on installing on Gentoo including ebuilds for all the packages used.

=====Fedora Core=====
RPM packages for Fedora Core and installation instructions are available [[Installing Fedora Core 5 on a ThinkPad X41 Tablet#Fingerprint_Reader|here]]

====Installing from source====
{{HINT|
For Ubuntu you'll need at least these packages, or building will fail:
* build-essential
* automake
* libqt3-headers
}}
* Get the bioapi source:
:{{cmduser|wget http://bioapi-linux.googlecode.com/files/bioapi_1.2.3.tar.gz}}
* Edit the configure file to patch a bug. At line 25975, change
:<code>bnv_qt_LIBS="-l$bnv_qt_lib_dir $LIBS"</code>
:to
:<code>bnv_qt_LIBS="-L$bnv_qt_lib_dir $LIBS"</code>
* Compile bioapi:
:{{cmduser|tar xzf bioapi_1.2.3.tar.gz}}
:{{cmduser|cd bioapi-1.2.3}}
:{{cmduser|1=./configure}}
:{{cmduser|make}}
:and then as root
:{{cmdroot|make install}}
* If configure fails when checking the Qt installation, you may need to manually specify the Qt lib directory and Qt lib name. For example:
:{{cmduser|1=./configure --with-Qt-lib-dir=/usr/lib/qt3 --with-Qt-lib=qt-mt}}
:or you can compile without the graphical Qt tools:
:{{cmduser|1=./configure --with-Qt-dir=no}}
* If make install fails, be sure you're root and then:
:{{cmdroot|1=export LD_LIBRARY_PATH=/usr/local/lib}}
:{{cmdroot|make install}}
:and if you want to compile [http://code.google.com/p/pam-bioapi/ pam_bioapi] for auth later
:{{cmdroot|cp include/bioapi_util.h include/installdefs.h imports/cdsa/v2_0/inc/cssmtype.h /usr/include}}
:Be aware that checkinstall will not work!
* By default, bioapi will install several files in {{path|/usr/local/bin}}, including files with "self-explanatory" names such as {{path|/usr/local/bin/Sample}}. To prevent this pollution:
:Create a dedicated directory, for example {{path|/opt/bioapi}} .
:Append <tt>--prefix=/opt/bioapi</tt> to the above <tt>./configure</tt> command.
:Append {{path|/opt/bioapi/bin}} to <tt>$PATH</tt> and {{path|/opt/bioapi/lib}} to <tt>$LD_LIBRARY_PATH</tt>.
:When installing the driver (below), tell it the new install path: {{cmdroot|sh install.sh /opt/bioapi/lib}}

====Adjusting ldconfigs library search path====
At least on {{Fedora}} or {{Aurox}} 11, you may need to add {{path|/usr/local/lib}} to the library path so that the libraries referenced from <tt>pam_bioapi.so</tt> get picked up properly. The usual way to do this is adding it to the ldconfig configuration:
:{{cmdroot|echo '/usr/local/lib' > /etc/ld.so.conf.d/bioapi.conf}}
:{{cmdroot|ldconfig}}
Alternatively you can add it to the LD_LIBRARY variable.

If you see bioapi libs in the output of
:{{cmdroot|ldconfig -p | grep bioapi}}
then it should work.

===Installing and configuring the driver===
====Installing the driver====
*Download {{path|TFMESS_BSP_LIN_1.0.zip}} from the [http://www.upek.com/support/dl_linux_bsp.asp UPEK support site] and unzip it into a seperate folder, as it will not create one.
*Change to that folder and do as root:
:{{cmdroot|sh install.sh}}
:If you're running Gentoo, Debian or Ubuntu Dapper, use
:{{cmdroot|sh install.sh /usr/lib}}
{{HINT|
For me it didn't work this way, but following did:
:sh install.sh /usr/local/lib
greetings, tec}}
{{HINT|On my debian install I had to "cp libtfmessbsp.so /usr/lib" to avoid a errormessage during "sh install.sh /usr/lib": "Could not find file:/usr/lib/libtfmessbsp.so"}}
:If that fails, it may be that make install failed up above -- try setting LD_LIBRARY_PATH, do the make install again, and come back here and try this again. You also need {{cmd|mod_install|}} from bioapi in your PATH.
:May there still occures and error, which means mod_install: command not found.
:Then login as root - not su!
:Do this:
:{{cmdroot|sh install.sh}}
:again. It should work. SU to root does not work since then the /usr/local/bin directory is not used per default.

====Configuring permissions for non-root use====
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), you may need to do all or at least some of the things in this section. More details on what is necessary on which distributions would be greately appreciated.
*Create two groups, one for access to BioAPI files and the other for access to the usb files. (This is done for full generality; i.e., you may have other USB devices which you want accessable to other users, without exposing your BioAPI configuration to them). Add your normal user (the one you wish to use PAM-aware applications with) to both of these groups.
On {{Debian}} this is done with
:{{cmdroot|addgroup --system bioapi}}
:{{cmdroot|addgroup --system usbfs}}
:{{cmdroot|adduser yournormaluser bioapi}}
:{{cmdroot|adduser yournormaluser usbfs}}
On {{SUSE}} this is done with
:{{cmdroot|groupadd --system bioapi}}
:{{cmdroot|groupadd --system usbfs}}
:{{cmdroot|groupmod -A yournormaluser bioapi}}
:{{cmdroot|groupmod -A yournormaluser usbfs}}
On {{Mandriva}} this is done with
:{{cmdroot|groupadd -r bioapi}}
:{{cmdroot|groupadd -r usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}
On {{Fedora}} this is done with
:{{cmdroot|groupadd bioapi}}
:{{cmdroot|groupadd usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}

:(where {{cmd|yournormaluser|}} is your normal user name). You will need to log out and log back in for this to take effect.
*Set permissions on the BioAPI config/registry directory:
:{{cmdroot|chown -R root:bioapi /usr/local/var/bioapi/}}
:{{cmdroot|chmod -R 770 /usr/local/var/bioapi/}}
:(change this path if you used an alternate BioAPI install directory above)
*Set permissions on the files in {{path|/proc/bus/usb}}:
:{{cmdroot|chown -R root:usbfs /proc/bus/usb}}
:{{cmdroot|chmod -R g+X /proc/bus/usb}}
:{{cmdroot|chown root:usbfs /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:{{cmdroot|chmod 660 /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:You may need to replace {{cmd|lsusb|}} with its full path, which is something like {{cmd|/sbin/lsusb|}} or {{cmd|/usr/bin/lsusb|}} depending on your distro. It might be necessary to put these lines into a script which is run at startup and resume from suspend/hibernate.
In {{Fedora}} {{cmd|lsusb|}} is not installed by default. To intall it just type:
:{{cmdroot|yum install usbutils}}

*As an alternative to the {{cmd|chown|}}/{{cmd|chmod|}} commands above, you can set mount options for usbfs with a line in {{path|/etc/fstab|}}; an example would be
none /proc/bus/usb usbfs defaults,devgid=108,devmode=0660,busgid=108,busmode=0770,listgid=108,listmode=0660 0 0
:where 108 is replaced with the numerical group ID of the usbfs group (you can determine this with something like {{cmd|cat /etc/group <nowiki>|</nowiki> grep usbfs <nowiki>|</nowiki> cut -d':' -f 3|}}). Make sure you only have one {{path|/proc/bus/usb}} entry in {{path|/etc/fstab}}. See the {{cmd|mount(8)|}} manpage for more information on these options. This is "cleaner" but seems to have a few weird issues -- see the talk page for details.
*You may also have files in {{path|/dev/bus/usb}}, which the driver will try before {{path|/proc/bus/usb}}. If this is another usbfs mount point ({{cmd|mount|}} shows a line containing {{cmdresult|/dev/bus/usb type usbfs}}), then simply follow the above instructions with {{path|/dev/bus/usb}} rather than {{path|/proc/bus/usb}}. Otherwise, you may be running a new kernel (i.e. 2.6.15) that makes usbfs-like files available through {{path|/dev/bus/usb}}.
*On systems running udev these files are dynamically created; you can configure their permissions by editing a udev config file. On Debian this is done by changing the <tt>usb_device</tt> line of {{path|/etc/udev/permissions.rules}} to read
SUBSYSTEM=="usb_device", MODE="0660", GROUP="usbfs"
*For the beta versions only, there is a logfile, which needs to exist with the proper permissions:
:{{cmdroot|touch /var/log/BSP.log && chown root:bioapi /var/log/BSP.log && chmod 660 /var/log/BSP.log}}

====Miscellaneous configuration====
* To increase the security level (minimize false accept rate), set this in {{path|/etc/tfmessbsp.cfg}}:
security-level="5"
{{WARN|Please see discussion section Security Level!}}

===Testing the driver and enrolling a fingerprint===
To test the driver and generate the file containing your fingerprint information, you need a sample program included with the driver. The compilation steps below were discovered by trial and error; if they don't work for you, try the binary {{cmd|Sample|}} utility that came with the beta versions of the driver (i.e., {{path|TFMESS_BSP_LIN_1.0beta2.zip}} as mentioned above).
Go to the folder where you extracted {{path|TFMESS_BSP_LIN_1.0.zip}} and do:
:{{cmdroot|cd NonGUI_Sample}}
:Edit {{path|main.c|}} and remove (or comment out) the line
#include "port/bioapi_port.h"
:then add the line
#include <stdlib.h>
:{{cmdroot|gcc -o Sample main.c -L/usr/local/lib -lbioapi100 -DUNIX -DLITTLE_ENDIAN}}
:{{cmdroot|./Sample}}
:Note that Sample may only run as root, unless you've already configured the usbfs file permissions.
:You can try to "e"nroll (to record a fingerprint for an account) and then "v"erify (to test a fingerprint against the one it expects for an account).
:You'll save a step later if you use your own login username as the username to enroll here.
:If running {{cmd |./Sample|}} produces the error message 'BioAPI_ModuleLoad failed, BioAPI Error Code: 6477 (0x194d)'
:then uncommenting the line
://BioAPI_SetGUICallbacks(gModuleHandle, NULL, NULL,TextGuiCallback, NULL);
:in {{path|main.c|}} can help.

==Login via pam_bioapi==

The following explains how to add fingerprint authentiation to programs that use the PAM (Pluggable Authentication Modules) framework, such as Gnome's GDM and KDE's KDM and screensaver.

===Getting required libs & tools===
====Installing pam_bioapi====
*Prerequisites
:On SuSE 10, I needed to install the pam-devel RPM
:In general, you will need pam itself (standard for most distros) as well as the pam development files (probably an optional package for your distro).
*Get and compile the pam_bioapi module.
{{HINT|A new version, pam_bioapi 0.3.0, with multi-finger and identification support can be found [http://www.nax.cz/pub/bioapi/pam_bioapi/pam-bioapi_0.3.0.tar.gz here].
There's work in progress. pam_bioapi and biometrics-manager can be downloaded [http://download.savannah.gnu.org/releases/pam-bioapi/ here].}}
:{{cmduser|wget http://www.qrivy.net/~michael/blua/pam_bioapi/pam_bioapi-latest.tar.bz2}}
:{{cmduser|tar xjf pam_bioapi-latest.tar.bz2}}
:{{cmduser|cd pam_bioapi-0.2.1}}
:{{cmduser|wget http://badcode.de/downloads/fingerprint.patch}}
:{{cmduser|patch -p0 < fingerprint.patch}}
:If you want to, review the patch. In general you should review all code you download and compile, if possible.
:{{cmduser|<nowiki>./configure --libdir=/lib && make </nowiki>}}
:and as root
:{{cmdroot| make install}}
{{NOTE|If you get a 'rpl_malloc' error in /var/log/auth.log when trying to use the fingerprint reader, redo these steps and remove the related term from Makefile after running ./configure. (FC3, Debian etch)}}
*If you get 'configure: error: cannot find required header: security/_pam_macros.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again. If you are using a Mandriva distribution, do "urpmi libpam0-devel" instead.
*If you get 'configure: error: cannot find required header: security/pam_modules.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again.
*If you get 'configure: error: cannot find required header: sqlite3.h' and are on a Debian-like system, do "apt-get install libsqlite3-dev" and try again.
*If you get 'make: msgfmt: command not found' and are on a Debian-like system, do "apt-get install gettext" and try again.
*If you get 'PAM [dlerror: /lib/security/pam_bioapi.so: undefined symbol: BioAPIMemoryFuncs]' error in your syslog, replace 'LIBS = ' line in {{path|libpam_bioapi/makefile}} with the following (of course, replace {{path|/opt/bioapi/}} with the path where you installed bioapi):
LIBS = -L/opt/bioapi/lib -lbioapi100 -lbioapi_mds300 -lmds_util
*Use the sample tool from the fingerprint reader to create {{path|<username>.bir}} (<tt><username></tt> '''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:
:{{cmdroot|SERIAL<nowiki>=`BioAPITest | sed -ne "/Fingerprint/{n;n;s/^.*: $.\{9\}$$.\{4\}$$.\{4\}$$.\{4\}$$.*$/\1-\2-\3-\4-\5/gp}"` </nowiki>}}
:{{cmdroot|echo $SERIAL}} should print something like {{cmdresult|<nowiki>{5550454b-2054-464d-2f45-535320425350}</nowiki>}} now.
:If it does, do:
:{{cmdroot|mkdir -p /etc/bioapi/pam/$SERIAL}}
:{{cmdroot|cp <username>.bir /etc/bioapi/pam/$SERIAL}}
:If not, you might just try
:{{cmdroot|SERIAL<nowiki>={5550454b-2054-464d-2f45-535320425350}</nowiki>}}
:as this value is hardcoded into the UPEK docs.

===Configuring pam===
The following part is distribution specific. On {{Ubuntu}} or {{SUSE}} you can modify {{path|/etc/pam.d/common-auth}} (on {{Gentoo}} and {{Fedora}} it is {{path|/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/bioapi/pam/
password sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_unix.so nullok_secure

----
For '''Gentoo'''-Users - this allows you to attempt a password first. If you simply press enter, it then prompts for a fingerprints. Create a file named {{path|/etc/pam.d/bioapi}}. This also means that remote services, such as SSH keep working:

auth required pam_env.so
auth sufficient pam_unix.so likeauth nullok
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_deny.so

account required pam_unix.so

session required pam_limits.so
session required pam_unix.so

----

Now, simply replace "auth include system-auth" in all services that you wish to use fingerprint for with "auth include bioapi". For example, {{path|/etc/pam.d/kde}} by default contains

auth include system-auth
auth required pam_nologin.so

account include system-auth

password include system-auth

session include system-auth

Simply replace the first "system-auth" with bioapi and you can also get rid of KDE desktop lock with a fingerprint. If you do not wish to allow for "password fallback" then remove

auth sufficient pam_unix.so likeauth nullok

from {{path|/etc/pam.d/bioapi}}.

{{WARN|If su/sudo expects to receive the root password (SuSE 10), you need to have fingerprint settings for root (that is, copy in a root.bir as well as a your-username.bir). Otherwise, they get a segmentation fault. Which is a little unfortunate, given that you need to su or sudo to change your settings... }}
{{WARN|Not only SuSE 10 requires root.bir to be available for su to work. Just make sure you have root.bir when su is not working with your fingerprint reader but other applications are...}}
Note that sshd may pick up the fingerprint settings from {{path|/etc/pam.d/common-auth}}. I didn't want that, so I removed the "auth include common-auth" line from {{path|/etc/pam.d/sshd}} and replaced it with the lines that were originally in my {{path|/etc/pam.d/common-auth}}. That way most local services use the fingerprint reader, but sshd does not.

{{NOTE|su/sudo will call for your fingerprint even if you are remote via ssh. Pressing *CTLR-c* (or closing graphic window) will allow you the desired password option.}}

Another way to do this is to create a file ({{path|/etc/pam.d/bioapi|}} for example) which contains the {{cmd|pam_bioapi.so|}} lines, and explicitly {{cmd|@include|}} this '''before''' {{path|/etc/pam.d/common-auth|}} in the files for services which should use the fingerprint reader. In this case you should leave {{path|/etc/pam.d/common-auth|}} alone.

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

In {{Fedora}} the original 'session' terms in {{path|/etc/pam.d/system-auth}} need to be kept.

{{HINT|The setup described above will/could affect remote ssh logins to also use biometric logins, which is a bit silly (who wants to remote ssh to the laptop, and then have to walk over to it and swipe your finger) To avoid that you can copy the default <tt>/etc/pam.d/system-auth</tt> to <tt>/etc/pam.d/sshd</tt> which will allow the sshd service to use the standard authentication procedure.}}

----

To enable normal password authorization to work with remote SSH in {{SUSE}} 10.3, edit the <tt>/etc/pam.d/sshd</tt> file. Remove all entries and replace them with:

auth required pam_env.so
auth required pam_unix2.so
auth required pam_nologin.so
account required pam_unix2.so
password required pam_pwcheck.so nullok
password required pam_unix2.so nullok use_first_pass use_authtok
session required pam_limits.so
session required pam_unix2.so

{{NOTE|These entries are what common-auth normally does. Since we've changed common-auth around for bioapi, these need to be specified manually. -Ransak}}

----

You can do some useful testing with [http://pamtester.sourceforge.net/ {{cmd|pamtester|}}], which calls the pam modules as if it were a program of your choice. Examples:
:{{cmdroot|pamtester xdm yourusername authenticate}}
:{{cmduser|pamtester xscreensaver yourusername authenticate}}
where {{cmd|yourusername|}} is your username. Note that {{cmd|pamtester|}} should run as root if and only if the program in question does.

===Application support===
The implementation of fingerprint scanning support in the relevant applications varies.

Here is the behaviour of the most common ones:
* In gdm enter your username and there should pop up an (ugly) image to swipe your finger and... magic - you can login without a password.
* kdm doesn't give any visual indication, other than that the cursor stops blinking. Just swipe your finger and hope it lets you log in.
* In xdm, enter your username and a blank password, then swipe (there is no popup as well). Identification support for xdm can be achieved with [http://www.nax.cz/pub/bioapi/2005/xdm/xdm_bio.patch this patch].
* The KDE screen saver in SUSE 10 requires you to enter an empty password (or select the correct user and then enter an empty password) in order to get the fingerprint prompt.
* For Fedora users, the redhat-config tools will crash if no root.bir presents. Also, there won't be any visual idication unless X server is properly configured for root to access. Just swipe your finger when the HDD stopped blinking or issue the following command in advance:
:{{cmduser|xhost +local:}}
* For RHEL4 users gdm, console (virtual terminal) logins and the xscreensaver all work

===kdm support===
To add graphical popup to kdm, you need following:
* Patch for pam_bioapi. This patch adds third parameter to {{path|pam_bioapi.so}} module, which is a name of file with additional environment variables that will be supplied to the UPEK driver.
:{{cmdroot|wget http://upir.cz/linux/patches/pam_bioapi-0.2.1-alter-environ.patch}}
:{{cmdroot|patch -p1 < pam_bioapi-0.2.1-alter-environ.patch}}
* Edit your {{path|Xsetup}} file (on SUSE 10 it's {{path|/etc/X11/xdm/Xsetup}}) and add these lines:
echo "XAUTHORITY=$XAUTHORITY" > /var/lib/xdm/kdm_env
echo "DISPLAY=$DISPLAY" >> /var/lib/xdm/kdm_env
* In {{path|/etc/pam.d/xdm}} file, add {{path|/var/lib/xdm/kdm_env}} as a third parameter for {{path|pam_bioapi.so}} module:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/xdm/kdm_env
* On Ubuntu simply do:
echo "DISPLAY=$DISPLAY" >> /var/lib/kdm/kdm_env
* If you have created /etc/pam.d/bioapi then modify:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/kdm/kdm_env

Please note, that this won't work if you have more than one Xserver.

==Make xscreensaver use the scanner==
If you are using Gentoo, you can get a portage overlay with the necessary patches here: http://www.zzamboni.org/brt/files/xscreensaver-fingerprint-overlay.tar.gz
*Get the needed xscreensaver sources:
:{{cmduser|wget http://www.jwz.org/xscreensaver/xscreensaver-4.23.tar.gz}}
:{{cmduser|tar xzf xscreensaver-4.23.tar.gz}}
:{{cmduser|cd xscreensaver-4.23}}
:{{cmduser|wget http://www.nax.cz/pub/bioapi/2005/xscreensaver/xscreensaver-4.22_alternativeAuth.diff mirror: http://zepan.org/files/xscreensaver-4.22_alternativeAuth.diff For xscreensaver 5.00, you can get a patch here: http://www.zzamboni.org/brt/files/xscreensaver-5.00-alternativeauth.patch}}
*After reviewing the patch (it's small and straightforward), do
:{{cmduser|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 <tt>pam</tt> and <tt>pam_bioapi</tt>. It should apply with some offset, don't mind that. If it says something about rejected though, then there's a problem.
*Compile with
:{{cmduser|./configure --with-pam && make}} 
*If you receive an error like "Couldn't find X11 headers/libs" and are running a Debian-like system, try "apt-get install xlibs-dev"
*If you receive an error like "undefined reference to `XmuPrintDefaultErrorMessage'" then install the libxmu-dev package and run the previous line again and then install as root with
:{{cmduser|su -c make install}} .
*Make sure that the newly compiled xscreensaver is used:
:{{cmduser|which xscreensaver}} should return
:{{cmdresult|/usr/local/bin/xscreensaver}} .
*In case it doesn't, try adjusting your PATH.

==Common problems==
===Bioapi error #3===
This is sometimes caused by improper permissions. The full error message is "BioAPI Error Code: 3 (0x3)".

However, at least on Gentoo, recent upgrades to glibc and gcc 4.1.1 caused Bioapi to break down due to some sort of incompatibility with bioapi registry. Reinstalling does '''not''' repair the issue automatically. However, you can still fix the issue manually, by removing /var/bioapi. You need to reinstall tfm-fingerprint driver after reinstalling bioapi so that the driver is properly re-registered. As root, type

:{{cmdroot|emerge -C bioapi}}
:{{cmdroot|rm -rf /var/bioapi}}
:{{cmdroot|emerge -av1 bioapi tfm-fingerprint}}

How to enable integrated fingerprint reader with BioAPI

2009-01-10T07:11:05Z

Dpward: /* Installing from source */

{| width="100%"
|style="vertical-align:top;padding-right:20px;width:10px;white-space:nowrap;" | __TOC__
|style="vertical-align:top" |
This page describes the process of getting the [[Integrated Fingerprint Reader|integrated fingerprint reader]] to work under Linux, using bioapi and binary-only drivers. It is based on experiences in {{Ubuntu}} on a T43. The same works on {{Fedora}} 4 and 5, RHEL4, SuSE 9.3, SuSE 10, and {{Gentoo}}. Note that experimental open-source driver is available, see [[How to enable the fingerprint reader with ThinkFinger|the apropriate page]] for details.
|}

==Basic installation==
===Installing the bioapi framework===
====Automated installation script====
The [[Script for enabling the fingerprint reader]] automates the installation of most components (bioapi framework, driver, pam_bioapi, pam setup, device permissions, pamtester and enrolling), for some Linux distributions.

====Binary packages====

Note that these packages only take care of this one section. If you can use one, you should do so and then proceed to the section entitled, Installing and Configuring the Driver.

=====Debian/ Ubuntu Dapper=====
*If you're using {{Debian}} Sid (the unstable branch) or {{Ubuntu}} Dapper Drake 6.06 LTS you can try the packages from Michael R. Crusoe's site, either [http://www.qrivy.net/~michael/temp/ version 1.2.3] (recommended) or [http://www.qrivy.net/~michael/debs/unstable/ older versions] which might not work with the steps in this howto.

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

=====Gentoo=====
Gentoo now includes needed ebuilds. Just run

''ACCEPT_KEYWORDS=~x86 emerge pam_bioapi''

You can also grab the [http://www.qrivy.net/~michael/blua/bioapi/bioapi-1.2.2.ebuild.tar.bz2 ebuild], or use the source-install procedure below.

Also see [http://toe.ch/~tsa/ibm-fingerprint/ http://toe.ch/~tsa/ibm-fingerprint/] for alternative documentation on installing on Gentoo including ebuilds for all the packages used.

=====Fedora Core=====
RPM packages for Fedora Core and installation instructions are available [[Installing Fedora Core 5 on a ThinkPad X41 Tablet#Fingerprint_Reader|here]]

====Installing from source====
{{HINT|
For Ubuntu you'll need at least these packages, or building will fail:
* build-essential
* automake
* libqt3-headers
}}
* Get the bioapi source:
:{{cmduser|wget http://bioapi-linux.googlecode.com/files/bioapi_1.2.3.tar.gz}}
* Edit the configure file to patch a bug. At line 25975, change
:<code>bnv_qt_LIBS="-l$bnv_qt_lib_dir $LIBS"</code>
:to
:<code>bnv_qt_LIBS="-L$bnv_qt_lib_dir $LIBS"</code>
* Compile bioapi:
:{{cmduser|tar xzf bioapi_1.2.3.tar.gz}}
:{{cmduser|cd bioapi-1.2.3}}
:{{cmduser|1=./configure}}
:{{cmduser|make}}
:and then as root
:{{cmdroot|make install}}
* If configure fails when checking the Qt installation, you may need to manually specify the Qt lib directory and Qt lib name. For example:
:{{cmduser|1=./configure --with-Qt-lib-dir=/usr/lib/qt3 --with-Qt-lib=qt-mt}}
:or you can compile without the graphical Qt tools:
:{{cmduser|1=./configure --with-Qt-dir=no}}
* If make install fails, be sure you're root and then:
:{{cmdroot|1=export LD_LIBRARY_PATH=/usr/local/lib}}
:{{cmdroot|make install}}
:and if you want to compile [http://code.google.com/p/pam-bioapi/ pam_bioapi] for auth later
:{{cmdroot|cp include/bioapi_util.h include/installdefs.h imports/cdsa/v2_0/inc/cssmtype.h /usr/include}}
:Be aware that checkinstall will not work!
* By default, bioapi will install several files in {{path|/usr/local/bin}}, including files with "self-explanatory" names such as {{path|/usr/local/bin/Sample}}. You may wish to just manually delete the files ({{path|BioAPITest}}, {{path|MdsEdit}}, {{path|mds_install}}, {{path|mod_install}}, {{path|QSample}}, {{path|Sample}}) from {{path|/usr/local/bin}} after make install completes. Or, here is a different way to prevent this pollution:
:Create a dedicated directory, for example {{path|/opt/bioapi}} .
:Append <tt>--prefix=/opt/bioapi</tt> to the above <tt>./configure</tt> command.
:Append {{path|/opt/bioapi/bin}} to <tt>$PATH</tt> and {{path|/opt/bioapi/lib}} to <tt>$LD_LIBRARY_PATH</tt>.
:When installing the driver (below), tell it the new install path: {{cmdroot|sh install.sh /opt/bioapi/lib}}

====Adjusting ldconfigs library search path====
At least on {{Fedora}} or {{Aurox}} 11, you may need to add {{path|/usr/local/lib}} to the library path so that the libraries referenced from <tt>pam_bioapi.so</tt> get picked up properly. The usual way to do this is adding it to the ldconfig configuration:
:{{cmdroot|echo '/usr/local/lib' > /etc/ld.so.conf.d/bioapi.conf}}
:{{cmdroot|ldconfig}}
Alternatively you can add it to the LD_LIBRARY variable.

If you see bioapi libs in the output of
:{{cmdroot|ldconfig -p | grep bioapi}}
then it should work.

===Installing and configuring the driver===
====Installing the driver====
*Download {{path|TFMESS_BSP_LIN_1.0.zip}} from the [http://www.upek.com/support/dl_linux_bsp.asp UPEK support site] and unzip it into a seperate folder, as it will not create one.
*Change to that folder and do as root:
:{{cmdroot|sh install.sh}}
:If you're running Gentoo, Debian or Ubuntu Dapper, use
:{{cmdroot|sh install.sh /usr/lib}}
{{HINT|
For me it didn't work this way, but following did:
:sh install.sh /usr/local/lib
greetings, tec}}
{{HINT|On my debian install I had to "cp libtfmessbsp.so /usr/lib" to avoid a errormessage during "sh install.sh /usr/lib": "Could not find file:/usr/lib/libtfmessbsp.so"}}
:If that fails, it may be that make install failed up above -- try setting LD_LIBRARY_PATH, do the make install again, and come back here and try this again. You also need {{cmd|mod_install|}} from bioapi in your PATH.
:May there still occures and error, which means mod_install: command not found.
:Then login as root - not su!
:Do this:
:{{cmdroot|sh install.sh}}
:again. It should work. SU to root does not work since then the /usr/local/bin directory is not used per default.

====Configuring permissions for non-root use====
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), you may need to do all or at least some of the things in this section. More details on what is necessary on which distributions would be greately appreciated.
*Create two groups, one for access to BioAPI files and the other for access to the usb files. (This is done for full generality; i.e., you may have other USB devices which you want accessable to other users, without exposing your BioAPI configuration to them). Add your normal user (the one you wish to use PAM-aware applications with) to both of these groups.
On {{Debian}} this is done with
:{{cmdroot|addgroup --system bioapi}}
:{{cmdroot|addgroup --system usbfs}}
:{{cmdroot|adduser yournormaluser bioapi}}
:{{cmdroot|adduser yournormaluser usbfs}}
On {{SUSE}} this is done with
:{{cmdroot|groupadd --system bioapi}}
:{{cmdroot|groupadd --system usbfs}}
:{{cmdroot|groupmod -A yournormaluser bioapi}}
:{{cmdroot|groupmod -A yournormaluser usbfs}}
On {{Mandriva}} this is done with
:{{cmdroot|groupadd -r bioapi}}
:{{cmdroot|groupadd -r usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}
On {{Fedora}} this is done with
:{{cmdroot|groupadd bioapi}}
:{{cmdroot|groupadd usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}

:(where {{cmd|yournormaluser|}} is your normal user name). You will need to log out and log back in for this to take effect.
*Set permissions on the BioAPI config/registry directory:
:{{cmdroot|chown -R root:bioapi /usr/local/var/bioapi/}}
:{{cmdroot|chmod -R 770 /usr/local/var/bioapi/}}
:(change this path if you used an alternate BioAPI install directory above)
*Set permissions on the files in {{path|/proc/bus/usb}}:
:{{cmdroot|chown -R root:usbfs /proc/bus/usb}}
:{{cmdroot|chmod -R g+X /proc/bus/usb}}
:{{cmdroot|chown root:usbfs /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:{{cmdroot|chmod 660 /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:You may need to replace {{cmd|lsusb|}} with its full path, which is something like {{cmd|/sbin/lsusb|}} or {{cmd|/usr/bin/lsusb|}} depending on your distro. It might be necessary to put these lines into a script which is run at startup and resume from suspend/hibernate.
In {{Fedora}} {{cmd|lsusb|}} is not installed by default. To intall it just type:
:{{cmdroot|yum install usbutils}}

*As an alternative to the {{cmd|chown|}}/{{cmd|chmod|}} commands above, you can set mount options for usbfs with a line in {{path|/etc/fstab|}}; an example would be
none /proc/bus/usb usbfs defaults,devgid=108,devmode=0660,busgid=108,busmode=0770,listgid=108,listmode=0660 0 0
:where 108 is replaced with the numerical group ID of the usbfs group (you can determine this with something like {{cmd|cat /etc/group <nowiki>|</nowiki> grep usbfs <nowiki>|</nowiki> cut -d':' -f 3|}}). Make sure you only have one {{path|/proc/bus/usb}} entry in {{path|/etc/fstab}}. See the {{cmd|mount(8)|}} manpage for more information on these options. This is "cleaner" but seems to have a few weird issues -- see the talk page for details.
*You may also have files in {{path|/dev/bus/usb}}, which the driver will try before {{path|/proc/bus/usb}}. If this is another usbfs mount point ({{cmd|mount|}} shows a line containing {{cmdresult|/dev/bus/usb type usbfs}}), then simply follow the above instructions with {{path|/dev/bus/usb}} rather than {{path|/proc/bus/usb}}. Otherwise, you may be running a new kernel (i.e. 2.6.15) that makes usbfs-like files available through {{path|/dev/bus/usb}}.
*On systems running udev these files are dynamically created; you can configure their permissions by editing a udev config file. On Debian this is done by changing the <tt>usb_device</tt> line of {{path|/etc/udev/permissions.rules}} to read
SUBSYSTEM=="usb_device", MODE="0660", GROUP="usbfs"
*For the beta versions only, there is a logfile, which needs to exist with the proper permissions:
:{{cmdroot|touch /var/log/BSP.log && chown root:bioapi /var/log/BSP.log && chmod 660 /var/log/BSP.log}}

====Miscellaneous configuration====
* To increase the security level (minimize false accept rate), set this in {{path|/etc/tfmessbsp.cfg}}:
security-level="5"
{{WARN|Please see discussion section Security Level!}}

===Testing the driver and enrolling a fingerprint===
To test the driver and generate the file containing your fingerprint information, you need a sample program included with the driver. The compilation steps below were discovered by trial and error; if they don't work for you, try the binary {{cmd|Sample|}} utility that came with the beta versions of the driver (i.e., {{path|TFMESS_BSP_LIN_1.0beta2.zip}} as mentioned above).
Go to the folder where you extracted {{path|TFMESS_BSP_LIN_1.0.zip}} and do:
:{{cmdroot|cd NonGUI_Sample}}
:Edit {{path|main.c|}} and remove (or comment out) the line
#include "port/bioapi_port.h"
:then add the line
#include <stdlib.h>
:{{cmdroot|gcc -o Sample main.c -L/usr/local/lib -lbioapi100 -DUNIX -DLITTLE_ENDIAN}}
:{{cmdroot|./Sample}}
:Note that Sample may only run as root, unless you've already configured the usbfs file permissions.
:You can try to "e"nroll (to record a fingerprint for an account) and then "v"erify (to test a fingerprint against the one it expects for an account).
:You'll save a step later if you use your own login username as the username to enroll here.
:If running {{cmd |./Sample|}} produces the error message 'BioAPI_ModuleLoad failed, BioAPI Error Code: 6477 (0x194d)'
:then uncommenting the line
://BioAPI_SetGUICallbacks(gModuleHandle, NULL, NULL,TextGuiCallback, NULL);
:in {{path|main.c|}} can help.

==Login via pam_bioapi==

The following explains how to add fingerprint authentiation to programs that use the PAM (Pluggable Authentication Modules) framework, such as Gnome's GDM and KDE's KDM and screensaver.

===Getting required libs & tools===
====Installing pam_bioapi====
*Prerequisites
:On SuSE 10, I needed to install the pam-devel RPM
:In general, you will need pam itself (standard for most distros) as well as the pam development files (probably an optional package for your distro).
*Get and compile the pam_bioapi module.
{{HINT|A new version, pam_bioapi 0.3.0, with multi-finger and identification support can be found [http://www.nax.cz/pub/bioapi/pam_bioapi/pam-bioapi_0.3.0.tar.gz here].
There's work in progress. pam_bioapi and biometrics-manager can be downloaded [http://download.savannah.gnu.org/releases/pam-bioapi/ here].}}
:{{cmduser|wget http://www.qrivy.net/~michael/blua/pam_bioapi/pam_bioapi-latest.tar.bz2}}
:{{cmduser|tar xjf pam_bioapi-latest.tar.bz2}}
:{{cmduser|cd pam_bioapi-0.2.1}}
:{{cmduser|wget http://badcode.de/downloads/fingerprint.patch}}
:{{cmduser|patch -p0 < fingerprint.patch}}
:If you want to, review the patch. In general you should review all code you download and compile, if possible.
:{{cmduser|<nowiki>./configure --libdir=/lib && make </nowiki>}}
:and as root
:{{cmdroot| make install}}
{{NOTE|If you get a 'rpl_malloc' error in /var/log/auth.log when trying to use the fingerprint reader, redo these steps and remove the related term from Makefile after running ./configure. (FC3, Debian etch)}}
*If you get 'configure: error: cannot find required header: security/_pam_macros.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again. If you are using a Mandriva distribution, do "urpmi libpam0-devel" instead.
*If you get 'configure: error: cannot find required header: security/pam_modules.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again.
*If you get 'configure: error: cannot find required header: sqlite3.h' and are on a Debian-like system, do "apt-get install libsqlite3-dev" and try again.
*If you get 'make: msgfmt: command not found' and are on a Debian-like system, do "apt-get install gettext" and try again.
*If you get 'PAM [dlerror: /lib/security/pam_bioapi.so: undefined symbol: BioAPIMemoryFuncs]' error in your syslog, replace 'LIBS = ' line in {{path|libpam_bioapi/makefile}} with the following (of course, replace {{path|/opt/bioapi/}} with the path where you installed bioapi):
LIBS = -L/opt/bioapi/lib -lbioapi100 -lbioapi_mds300 -lmds_util
*Use the sample tool from the fingerprint reader to create {{path|<username>.bir}} (<tt><username></tt> '''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:
:{{cmdroot|SERIAL<nowiki>=`BioAPITest | sed -ne "/Fingerprint/{n;n;s/^.*: $.\{9\}$$.\{4\}$$.\{4\}$$.\{4\}$$.*$/\1-\2-\3-\4-\5/gp}"` </nowiki>}}
:{{cmdroot|echo $SERIAL}} should print something like {{cmdresult|<nowiki>{5550454b-2054-464d-2f45-535320425350}</nowiki>}} now.
:If it does, do:
:{{cmdroot|mkdir -p /etc/bioapi/pam/$SERIAL}}
:{{cmdroot|cp <username>.bir /etc/bioapi/pam/$SERIAL}}
:If not, you might just try
:{{cmdroot|SERIAL<nowiki>={5550454b-2054-464d-2f45-535320425350}</nowiki>}}
:as this value is hardcoded into the UPEK docs.

===Configuring pam===
The following part is distribution specific. On {{Ubuntu}} or {{SUSE}} you can modify {{path|/etc/pam.d/common-auth}} (on {{Gentoo}} and {{Fedora}} it is {{path|/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/bioapi/pam/
password sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_unix.so nullok_secure

----
For '''Gentoo'''-Users - this allows you to attempt a password first. If you simply press enter, it then prompts for a fingerprints. Create a file named {{path|/etc/pam.d/bioapi}}. This also means that remote services, such as SSH keep working:

auth required pam_env.so
auth sufficient pam_unix.so likeauth nullok
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_deny.so

account required pam_unix.so

session required pam_limits.so
session required pam_unix.so

----

Now, simply replace "auth include system-auth" in all services that you wish to use fingerprint for with "auth include bioapi". For example, {{path|/etc/pam.d/kde}} by default contains

auth include system-auth
auth required pam_nologin.so

account include system-auth

password include system-auth

session include system-auth

Simply replace the first "system-auth" with bioapi and you can also get rid of KDE desktop lock with a fingerprint. If you do not wish to allow for "password fallback" then remove

auth sufficient pam_unix.so likeauth nullok

from {{path|/etc/pam.d/bioapi}}.

{{WARN|If su/sudo expects to receive the root password (SuSE 10), you need to have fingerprint settings for root (that is, copy in a root.bir as well as a your-username.bir). Otherwise, they get a segmentation fault. Which is a little unfortunate, given that you need to su or sudo to change your settings... }}
{{WARN|Not only SuSE 10 requires root.bir to be available for su to work. Just make sure you have root.bir when su is not working with your fingerprint reader but other applications are...}}
Note that sshd may pick up the fingerprint settings from {{path|/etc/pam.d/common-auth}}. I didn't want that, so I removed the "auth include common-auth" line from {{path|/etc/pam.d/sshd}} and replaced it with the lines that were originally in my {{path|/etc/pam.d/common-auth}}. That way most local services use the fingerprint reader, but sshd does not.

{{NOTE|su/sudo will call for your fingerprint even if you are remote via ssh. Pressing *CTLR-c* (or closing graphic window) will allow you the desired password option.}}

Another way to do this is to create a file ({{path|/etc/pam.d/bioapi|}} for example) which contains the {{cmd|pam_bioapi.so|}} lines, and explicitly {{cmd|@include|}} this '''before''' {{path|/etc/pam.d/common-auth|}} in the files for services which should use the fingerprint reader. In this case you should leave {{path|/etc/pam.d/common-auth|}} alone.

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

In {{Fedora}} the original 'session' terms in {{path|/etc/pam.d/system-auth}} need to be kept.

{{HINT|The setup described above will/could affect remote ssh logins to also use biometric logins, which is a bit silly (who wants to remote ssh to the laptop, and then have to walk over to it and swipe your finger) To avoid that you can copy the default <tt>/etc/pam.d/system-auth</tt> to <tt>/etc/pam.d/sshd</tt> which will allow the sshd service to use the standard authentication procedure.}}

----

To enable normal password authorization to work with remote SSH in {{SUSE}} 10.3, edit the <tt>/etc/pam.d/sshd</tt> file. Remove all entries and replace them with:

auth required pam_env.so
auth required pam_unix2.so
auth required pam_nologin.so
account required pam_unix2.so
password required pam_pwcheck.so nullok
password required pam_unix2.so nullok use_first_pass use_authtok
session required pam_limits.so
session required pam_unix2.so

{{NOTE|These entries are what common-auth normally does. Since we've changed common-auth around for bioapi, these need to be specified manually. -Ransak}}

----

You can do some useful testing with [http://pamtester.sourceforge.net/ {{cmd|pamtester|}}], which calls the pam modules as if it were a program of your choice. Examples:
:{{cmdroot|pamtester xdm yourusername authenticate}}
:{{cmduser|pamtester xscreensaver yourusername authenticate}}
where {{cmd|yourusername|}} is your username. Note that {{cmd|pamtester|}} should run as root if and only if the program in question does.

===Application support===
The implementation of fingerprint scanning support in the relevant applications varies.

Here is the behaviour of the most common ones:
* In gdm enter your username and there should pop up an (ugly) image to swipe your finger and... magic - you can login without a password.
* kdm doesn't give any visual indication, other than that the cursor stops blinking. Just swipe your finger and hope it lets you log in.
* In xdm, enter your username and a blank password, then swipe (there is no popup as well). Identification support for xdm can be achieved with [http://www.nax.cz/pub/bioapi/2005/xdm/xdm_bio.patch this patch].
* The KDE screen saver in SUSE 10 requires you to enter an empty password (or select the correct user and then enter an empty password) in order to get the fingerprint prompt.
* For Fedora users, the redhat-config tools will crash if no root.bir presents. Also, there won't be any visual idication unless X server is properly configured for root to access. Just swipe your finger when the HDD stopped blinking or issue the following command in advance:
:{{cmduser|xhost +local:}}
* For RHEL4 users gdm, console (virtual terminal) logins and the xscreensaver all work

===kdm support===
To add graphical popup to kdm, you need following:
* Patch for pam_bioapi. This patch adds third parameter to {{path|pam_bioapi.so}} module, which is a name of file with additional environment variables that will be supplied to the UPEK driver.
:{{cmdroot|wget http://upir.cz/linux/patches/pam_bioapi-0.2.1-alter-environ.patch}}
:{{cmdroot|patch -p1 < pam_bioapi-0.2.1-alter-environ.patch}}
* Edit your {{path|Xsetup}} file (on SUSE 10 it's {{path|/etc/X11/xdm/Xsetup}}) and add these lines:
echo "XAUTHORITY=$XAUTHORITY" > /var/lib/xdm/kdm_env
echo "DISPLAY=$DISPLAY" >> /var/lib/xdm/kdm_env
* In {{path|/etc/pam.d/xdm}} file, add {{path|/var/lib/xdm/kdm_env}} as a third parameter for {{path|pam_bioapi.so}} module:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/xdm/kdm_env
* On Ubuntu simply do:
echo "DISPLAY=$DISPLAY" >> /var/lib/kdm/kdm_env
* If you have created /etc/pam.d/bioapi then modify:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/kdm/kdm_env

Please note, that this won't work if you have more than one Xserver.

==Make xscreensaver use the scanner==
If you are using Gentoo, you can get a portage overlay with the necessary patches here: http://www.zzamboni.org/brt/files/xscreensaver-fingerprint-overlay.tar.gz
*Get the needed xscreensaver sources:
:{{cmduser|wget http://www.jwz.org/xscreensaver/xscreensaver-4.23.tar.gz}}
:{{cmduser|tar xzf xscreensaver-4.23.tar.gz}}
:{{cmduser|cd xscreensaver-4.23}}
:{{cmduser|wget http://www.nax.cz/pub/bioapi/2005/xscreensaver/xscreensaver-4.22_alternativeAuth.diff mirror: http://zepan.org/files/xscreensaver-4.22_alternativeAuth.diff For xscreensaver 5.00, you can get a patch here: http://www.zzamboni.org/brt/files/xscreensaver-5.00-alternativeauth.patch}}
*After reviewing the patch (it's small and straightforward), do
:{{cmduser|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 <tt>pam</tt> and <tt>pam_bioapi</tt>. It should apply with some offset, don't mind that. If it says something about rejected though, then there's a problem.
*Compile with
:{{cmduser|./configure --with-pam && make}} 
*If you receive an error like "Couldn't find X11 headers/libs" and are running a Debian-like system, try "apt-get install xlibs-dev"
*If you receive an error like "undefined reference to `XmuPrintDefaultErrorMessage'" then install the libxmu-dev package and run the previous line again and then install as root with
:{{cmduser|su -c make install}} .
*Make sure that the newly compiled xscreensaver is used:
:{{cmduser|which xscreensaver}} should return
:{{cmdresult|/usr/local/bin/xscreensaver}} .
*In case it doesn't, try adjusting your PATH.

==Common problems==
===Bioapi error #3===
This is sometimes caused by improper permissions. The full error message is "BioAPI Error Code: 3 (0x3)".

However, at least on Gentoo, recent upgrades to glibc and gcc 4.1.1 caused Bioapi to break down due to some sort of incompatibility with bioapi registry. Reinstalling does '''not''' repair the issue automatically. However, you can still fix the issue manually, by removing /var/bioapi. You need to reinstall tfm-fingerprint driver after reinstalling bioapi so that the driver is properly re-registered. As root, type

:{{cmdroot|emerge -C bioapi}}
:{{cmdroot|rm -rf /var/bioapi}}
:{{cmdroot|emerge -av1 bioapi tfm-fingerprint}}

How to enable integrated fingerprint reader with BioAPI

2009-01-10T06:57:32Z

Dpward: /* Installing from source */

{| width="100%"
|style="vertical-align:top;padding-right:20px;width:10px;white-space:nowrap;" | __TOC__
|style="vertical-align:top" |
This page describes the process of getting the [[Integrated Fingerprint Reader|integrated fingerprint reader]] to work under Linux, using bioapi and binary-only drivers. It is based on experiences in {{Ubuntu}} on a T43. The same works on {{Fedora}} 4 and 5, RHEL4, SuSE 9.3, SuSE 10, and {{Gentoo}}. Note that experimental open-source driver is available, see [[How to enable the fingerprint reader with ThinkFinger|the apropriate page]] for details.
|}

==Basic installation==
===Installing the bioapi framework===
====Automated installation script====
The [[Script for enabling the fingerprint reader]] automates the installation of most components (bioapi framework, driver, pam_bioapi, pam setup, device permissions, pamtester and enrolling), for some Linux distributions.

====Binary packages====

Note that these packages only take care of this one section. If you can use one, you should do so and then proceed to the section entitled, Installing and Configuring the Driver.

=====Debian/ Ubuntu Dapper=====
*If you're using {{Debian}} Sid (the unstable branch) or {{Ubuntu}} Dapper Drake 6.06 LTS you can try the packages from Michael R. Crusoe's site, either [http://www.qrivy.net/~michael/temp/ version 1.2.3] (recommended) or [http://www.qrivy.net/~michael/debs/unstable/ older versions] which might not work with the steps in this howto.

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

=====Gentoo=====
Gentoo now includes needed ebuilds. Just run

''ACCEPT_KEYWORDS=~x86 emerge pam_bioapi''

You can also grab the [http://www.qrivy.net/~michael/blua/bioapi/bioapi-1.2.2.ebuild.tar.bz2 ebuild], or use the source-install procedure below.

Also see [http://toe.ch/~tsa/ibm-fingerprint/ http://toe.ch/~tsa/ibm-fingerprint/] for alternative documentation on installing on Gentoo including ebuilds for all the packages used.

=====Fedora Core=====
RPM packages for Fedora Core and installation instructions are available [[Installing Fedora Core 5 on a ThinkPad X41 Tablet#Fingerprint_Reader|here]]

====Installing from source====
{{HINT|
For Ubuntu you'll need at least these packages, or building will fail:
* build-essential
* automake
* libqt3-headers
}}
* Get the bioapi source:
:{{cmduser|wget http://bioapi-linux.googlecode.com/files/bioapi_1.2.3.tar.gz}}
* Edit the configure file to patch a bug. At line 25975, change
:<code>bnv_qt_LIBS="-l$bnv_qt_lib_dir $LIBS"</code>
:to
:<code>bnv_qt_LIBS="-L$bnv_qt_lib_dir $LIBS"</code>
* Compile bioapi:
:{{cmduser|tar xzf bioapi_1.2.3.tar.gz}}
:{{cmduser|cd bioapi-1.2.3}}
:{{cmduser|1=./configure}}
:{{cmduser|make}}
:and then as root
:{{cmdroot|make install}}
* If configure fails when checking the Qt installation, you may need to manually specify the Qt lib directory and Qt lib name. For example:
:{{cmduser|1=./configure --with-Qt-lib-dir=/usr/lib/qt3 --with-Qt-lib=qt-mt}}
:or you can compile without the graphical Qt tools:
:{{cmduser|1=./configure --with-Qt-dir=no}}
* If make install fails, be sure you're root and then:
:{{cmdroot|1=export LD_LIBRARY_PATH=/usr/local/lib}}
:{{cmdroot|make install}}
:and if you want to compile [http://code.google.com/p/pam-bioapi/ pam_bioapi] for auth later
:{{cmdroot|cp include/bioapi_util.h include/installdefs.h imports/cdsa/v2_0/inc/cssmtype.h /usr/include}}
:Be aware that checkinstall will not work!
* By default, bioapi will install numerous files in {{path|/usr/local/<nowiki>{</nowiki>bin,lib,include<nowiki>}</nowiki>}}, including files with "self-explanatory" names such as {{path|/usr/local/bin/Sample}}. To prevent this pollution:
:Create a dedicated directory, for example {{path|/opt/bioapi}} .
:Append <tt>--prefix=/opt/bioapi</tt> to the above <tt>./configure</tt> command.
:Append {{path|/opt/bioapi/bin}} to <tt>$PATH</tt> and {{path|/opt/bioapi/lib}} to <tt>$LD_LIBRARY_PATH</tt>.
:When installing the driver (below), tell it the new install path: {{cmdroot|sh install.sh /opt/bioapi/lib}}

====Adjusting ldconfigs library search path====
At least on {{Fedora}} or {{Aurox}} 11, you may need to add {{path|/usr/local/lib}} to the library path so that the libraries referenced from <tt>pam_bioapi.so</tt> get picked up properly. The usual way to do this is adding it to the ldconfig configuration:
:{{cmdroot|echo '/usr/local/lib' > /etc/ld.so.conf.d/bioapi.conf}}
:{{cmdroot|ldconfig}}
Alternatively you can add it to the LD_LIBRARY variable.

If you see bioapi libs in the output of
:{{cmdroot|ldconfig -p | grep bioapi}}
then it should work.

===Installing and configuring the driver===
====Installing the driver====
*Download {{path|TFMESS_BSP_LIN_1.0.zip}} from the [http://www.upek.com/support/dl_linux_bsp.asp UPEK support site] and unzip it into a seperate folder, as it will not create one.
*Change to that folder and do as root:
:{{cmdroot|sh install.sh}}
:If you're running Gentoo, Debian or Ubuntu Dapper, use
:{{cmdroot|sh install.sh /usr/lib}}
{{HINT|
For me it didn't work this way, but following did:
:sh install.sh /usr/local/lib
greetings, tec}}
{{HINT|On my debian install I had to "cp libtfmessbsp.so /usr/lib" to avoid a errormessage during "sh install.sh /usr/lib": "Could not find file:/usr/lib/libtfmessbsp.so"}}
:If that fails, it may be that make install failed up above -- try setting LD_LIBRARY_PATH, do the make install again, and come back here and try this again. You also need {{cmd|mod_install|}} from bioapi in your PATH.
:May there still occures and error, which means mod_install: command not found.
:Then login as root - not su!
:Do this:
:{{cmdroot|sh install.sh}}
:again. It should work. SU to root does not work since then the /usr/local/bin directory is not used per default.

====Configuring permissions for non-root use====
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), you may need to do all or at least some of the things in this section. More details on what is necessary on which distributions would be greately appreciated.
*Create two groups, one for access to BioAPI files and the other for access to the usb files. (This is done for full generality; i.e., you may have other USB devices which you want accessable to other users, without exposing your BioAPI configuration to them). Add your normal user (the one you wish to use PAM-aware applications with) to both of these groups.
On {{Debian}} this is done with
:{{cmdroot|addgroup --system bioapi}}
:{{cmdroot|addgroup --system usbfs}}
:{{cmdroot|adduser yournormaluser bioapi}}
:{{cmdroot|adduser yournormaluser usbfs}}
On {{SUSE}} this is done with
:{{cmdroot|groupadd --system bioapi}}
:{{cmdroot|groupadd --system usbfs}}
:{{cmdroot|groupmod -A yournormaluser bioapi}}
:{{cmdroot|groupmod -A yournormaluser usbfs}}
On {{Mandriva}} this is done with
:{{cmdroot|groupadd -r bioapi}}
:{{cmdroot|groupadd -r usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}
On {{Fedora}} this is done with
:{{cmdroot|groupadd bioapi}}
:{{cmdroot|groupadd usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}

:(where {{cmd|yournormaluser|}} is your normal user name). You will need to log out and log back in for this to take effect.
*Set permissions on the BioAPI config/registry directory:
:{{cmdroot|chown -R root:bioapi /usr/local/var/bioapi/}}
:{{cmdroot|chmod -R 770 /usr/local/var/bioapi/}}
:(change this path if you used an alternate BioAPI install directory above)
*Set permissions on the files in {{path|/proc/bus/usb}}:
:{{cmdroot|chown -R root:usbfs /proc/bus/usb}}
:{{cmdroot|chmod -R g+X /proc/bus/usb}}
:{{cmdroot|chown root:usbfs /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:{{cmdroot|chmod 660 /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:You may need to replace {{cmd|lsusb|}} with its full path, which is something like {{cmd|/sbin/lsusb|}} or {{cmd|/usr/bin/lsusb|}} depending on your distro. It might be necessary to put these lines into a script which is run at startup and resume from suspend/hibernate.
In {{Fedora}} {{cmd|lsusb|}} is not installed by default. To intall it just type:
:{{cmdroot|yum install usbutils}}

*As an alternative to the {{cmd|chown|}}/{{cmd|chmod|}} commands above, you can set mount options for usbfs with a line in {{path|/etc/fstab|}}; an example would be
none /proc/bus/usb usbfs defaults,devgid=108,devmode=0660,busgid=108,busmode=0770,listgid=108,listmode=0660 0 0
:where 108 is replaced with the numerical group ID of the usbfs group (you can determine this with something like {{cmd|cat /etc/group <nowiki>|</nowiki> grep usbfs <nowiki>|</nowiki> cut -d':' -f 3|}}). Make sure you only have one {{path|/proc/bus/usb}} entry in {{path|/etc/fstab}}. See the {{cmd|mount(8)|}} manpage for more information on these options. This is "cleaner" but seems to have a few weird issues -- see the talk page for details.
*You may also have files in {{path|/dev/bus/usb}}, which the driver will try before {{path|/proc/bus/usb}}. If this is another usbfs mount point ({{cmd|mount|}} shows a line containing {{cmdresult|/dev/bus/usb type usbfs}}), then simply follow the above instructions with {{path|/dev/bus/usb}} rather than {{path|/proc/bus/usb}}. Otherwise, you may be running a new kernel (i.e. 2.6.15) that makes usbfs-like files available through {{path|/dev/bus/usb}}.
*On systems running udev these files are dynamically created; you can configure their permissions by editing a udev config file. On Debian this is done by changing the <tt>usb_device</tt> line of {{path|/etc/udev/permissions.rules}} to read
SUBSYSTEM=="usb_device", MODE="0660", GROUP="usbfs"
*For the beta versions only, there is a logfile, which needs to exist with the proper permissions:
:{{cmdroot|touch /var/log/BSP.log && chown root:bioapi /var/log/BSP.log && chmod 660 /var/log/BSP.log}}

====Miscellaneous configuration====
* To increase the security level (minimize false accept rate), set this in {{path|/etc/tfmessbsp.cfg}}:
security-level="5"
{{WARN|Please see discussion section Security Level!}}

===Testing the driver and enrolling a fingerprint===
To test the driver and generate the file containing your fingerprint information, you need a sample program included with the driver. The compilation steps below were discovered by trial and error; if they don't work for you, try the binary {{cmd|Sample|}} utility that came with the beta versions of the driver (i.e., {{path|TFMESS_BSP_LIN_1.0beta2.zip}} as mentioned above).
Go to the folder where you extracted {{path|TFMESS_BSP_LIN_1.0.zip}} and do:
:{{cmdroot|cd NonGUI_Sample}}
:Edit {{path|main.c|}} and remove (or comment out) the line
#include "port/bioapi_port.h"
:then add the line
#include <stdlib.h>
:{{cmdroot|gcc -o Sample main.c -L/usr/local/lib -lbioapi100 -DUNIX -DLITTLE_ENDIAN}}
:{{cmdroot|./Sample}}
:Note that Sample may only run as root, unless you've already configured the usbfs file permissions.
:You can try to "e"nroll (to record a fingerprint for an account) and then "v"erify (to test a fingerprint against the one it expects for an account).
:You'll save a step later if you use your own login username as the username to enroll here.
:If running {{cmd |./Sample|}} produces the error message 'BioAPI_ModuleLoad failed, BioAPI Error Code: 6477 (0x194d)'
:then uncommenting the line
://BioAPI_SetGUICallbacks(gModuleHandle, NULL, NULL,TextGuiCallback, NULL);
:in {{path|main.c|}} can help.

==Login via pam_bioapi==

The following explains how to add fingerprint authentiation to programs that use the PAM (Pluggable Authentication Modules) framework, such as Gnome's GDM and KDE's KDM and screensaver.

===Getting required libs & tools===
====Installing pam_bioapi====
*Prerequisites
:On SuSE 10, I needed to install the pam-devel RPM
:In general, you will need pam itself (standard for most distros) as well as the pam development files (probably an optional package for your distro).
*Get and compile the pam_bioapi module.
{{HINT|A new version, pam_bioapi 0.3.0, with multi-finger and identification support can be found [http://www.nax.cz/pub/bioapi/pam_bioapi/pam-bioapi_0.3.0.tar.gz here].
There's work in progress. pam_bioapi and biometrics-manager can be downloaded [http://download.savannah.gnu.org/releases/pam-bioapi/ here].}}
:{{cmduser|wget http://www.qrivy.net/~michael/blua/pam_bioapi/pam_bioapi-latest.tar.bz2}}
:{{cmduser|tar xjf pam_bioapi-latest.tar.bz2}}
:{{cmduser|cd pam_bioapi-0.2.1}}
:{{cmduser|wget http://badcode.de/downloads/fingerprint.patch}}
:{{cmduser|patch -p0 < fingerprint.patch}}
:If you want to, review the patch. In general you should review all code you download and compile, if possible.
:{{cmduser|<nowiki>./configure --libdir=/lib && make </nowiki>}}
:and as root
:{{cmdroot| make install}}
{{NOTE|If you get a 'rpl_malloc' error in /var/log/auth.log when trying to use the fingerprint reader, redo these steps and remove the related term from Makefile after running ./configure. (FC3, Debian etch)}}
*If you get 'configure: error: cannot find required header: security/_pam_macros.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again. If you are using a Mandriva distribution, do "urpmi libpam0-devel" instead.
*If you get 'configure: error: cannot find required header: security/pam_modules.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again.
*If you get 'configure: error: cannot find required header: sqlite3.h' and are on a Debian-like system, do "apt-get install libsqlite3-dev" and try again.
*If you get 'make: msgfmt: command not found' and are on a Debian-like system, do "apt-get install gettext" and try again.
*If you get 'PAM [dlerror: /lib/security/pam_bioapi.so: undefined symbol: BioAPIMemoryFuncs]' error in your syslog, replace 'LIBS = ' line in {{path|libpam_bioapi/makefile}} with the following (of course, replace {{path|/opt/bioapi/}} with the path where you installed bioapi):
LIBS = -L/opt/bioapi/lib -lbioapi100 -lbioapi_mds300 -lmds_util
*Use the sample tool from the fingerprint reader to create {{path|<username>.bir}} (<tt><username></tt> '''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:
:{{cmdroot|SERIAL<nowiki>=`BioAPITest | sed -ne "/Fingerprint/{n;n;s/^.*: $.\{9\}$$.\{4\}$$.\{4\}$$.\{4\}$$.*$/\1-\2-\3-\4-\5/gp}"` </nowiki>}}
:{{cmdroot|echo $SERIAL}} should print something like {{cmdresult|<nowiki>{5550454b-2054-464d-2f45-535320425350}</nowiki>}} now.
:If it does, do:
:{{cmdroot|mkdir -p /etc/bioapi/pam/$SERIAL}}
:{{cmdroot|cp <username>.bir /etc/bioapi/pam/$SERIAL}}
:If not, you might just try
:{{cmdroot|SERIAL<nowiki>={5550454b-2054-464d-2f45-535320425350}</nowiki>}}
:as this value is hardcoded into the UPEK docs.

===Configuring pam===
The following part is distribution specific. On {{Ubuntu}} or {{SUSE}} you can modify {{path|/etc/pam.d/common-auth}} (on {{Gentoo}} and {{Fedora}} it is {{path|/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/bioapi/pam/
password sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_unix.so nullok_secure

----
For '''Gentoo'''-Users - this allows you to attempt a password first. If you simply press enter, it then prompts for a fingerprints. Create a file named {{path|/etc/pam.d/bioapi}}. This also means that remote services, such as SSH keep working:

auth required pam_env.so
auth sufficient pam_unix.so likeauth nullok
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_deny.so

account required pam_unix.so

session required pam_limits.so
session required pam_unix.so

----

Now, simply replace "auth include system-auth" in all services that you wish to use fingerprint for with "auth include bioapi". For example, {{path|/etc/pam.d/kde}} by default contains

auth include system-auth
auth required pam_nologin.so

account include system-auth

password include system-auth

session include system-auth

Simply replace the first "system-auth" with bioapi and you can also get rid of KDE desktop lock with a fingerprint. If you do not wish to allow for "password fallback" then remove

auth sufficient pam_unix.so likeauth nullok

from {{path|/etc/pam.d/bioapi}}.

{{WARN|If su/sudo expects to receive the root password (SuSE 10), you need to have fingerprint settings for root (that is, copy in a root.bir as well as a your-username.bir). Otherwise, they get a segmentation fault. Which is a little unfortunate, given that you need to su or sudo to change your settings... }}
{{WARN|Not only SuSE 10 requires root.bir to be available for su to work. Just make sure you have root.bir when su is not working with your fingerprint reader but other applications are...}}
Note that sshd may pick up the fingerprint settings from {{path|/etc/pam.d/common-auth}}. I didn't want that, so I removed the "auth include common-auth" line from {{path|/etc/pam.d/sshd}} and replaced it with the lines that were originally in my {{path|/etc/pam.d/common-auth}}. That way most local services use the fingerprint reader, but sshd does not.

{{NOTE|su/sudo will call for your fingerprint even if you are remote via ssh. Pressing *CTLR-c* (or closing graphic window) will allow you the desired password option.}}

Another way to do this is to create a file ({{path|/etc/pam.d/bioapi|}} for example) which contains the {{cmd|pam_bioapi.so|}} lines, and explicitly {{cmd|@include|}} this '''before''' {{path|/etc/pam.d/common-auth|}} in the files for services which should use the fingerprint reader. In this case you should leave {{path|/etc/pam.d/common-auth|}} alone.

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

In {{Fedora}} the original 'session' terms in {{path|/etc/pam.d/system-auth}} need to be kept.

{{HINT|The setup described above will/could affect remote ssh logins to also use biometric logins, which is a bit silly (who wants to remote ssh to the laptop, and then have to walk over to it and swipe your finger) To avoid that you can copy the default <tt>/etc/pam.d/system-auth</tt> to <tt>/etc/pam.d/sshd</tt> which will allow the sshd service to use the standard authentication procedure.}}

----

To enable normal password authorization to work with remote SSH in {{SUSE}} 10.3, edit the <tt>/etc/pam.d/sshd</tt> file. Remove all entries and replace them with:

auth required pam_env.so
auth required pam_unix2.so
auth required pam_nologin.so
account required pam_unix2.so
password required pam_pwcheck.so nullok
password required pam_unix2.so nullok use_first_pass use_authtok
session required pam_limits.so
session required pam_unix2.so

{{NOTE|These entries are what common-auth normally does. Since we've changed common-auth around for bioapi, these need to be specified manually. -Ransak}}

----

You can do some useful testing with [http://pamtester.sourceforge.net/ {{cmd|pamtester|}}], which calls the pam modules as if it were a program of your choice. Examples:
:{{cmdroot|pamtester xdm yourusername authenticate}}
:{{cmduser|pamtester xscreensaver yourusername authenticate}}
where {{cmd|yourusername|}} is your username. Note that {{cmd|pamtester|}} should run as root if and only if the program in question does.

===Application support===
The implementation of fingerprint scanning support in the relevant applications varies.

Here is the behaviour of the most common ones:
* In gdm enter your username and there should pop up an (ugly) image to swipe your finger and... magic - you can login without a password.
* kdm doesn't give any visual indication, other than that the cursor stops blinking. Just swipe your finger and hope it lets you log in.
* In xdm, enter your username and a blank password, then swipe (there is no popup as well). Identification support for xdm can be achieved with [http://www.nax.cz/pub/bioapi/2005/xdm/xdm_bio.patch this patch].
* The KDE screen saver in SUSE 10 requires you to enter an empty password (or select the correct user and then enter an empty password) in order to get the fingerprint prompt.
* For Fedora users, the redhat-config tools will crash if no root.bir presents. Also, there won't be any visual idication unless X server is properly configured for root to access. Just swipe your finger when the HDD stopped blinking or issue the following command in advance:
:{{cmduser|xhost +local:}}
* For RHEL4 users gdm, console (virtual terminal) logins and the xscreensaver all work

===kdm support===
To add graphical popup to kdm, you need following:
* Patch for pam_bioapi. This patch adds third parameter to {{path|pam_bioapi.so}} module, which is a name of file with additional environment variables that will be supplied to the UPEK driver.
:{{cmdroot|wget http://upir.cz/linux/patches/pam_bioapi-0.2.1-alter-environ.patch}}
:{{cmdroot|patch -p1 < pam_bioapi-0.2.1-alter-environ.patch}}
* Edit your {{path|Xsetup}} file (on SUSE 10 it's {{path|/etc/X11/xdm/Xsetup}}) and add these lines:
echo "XAUTHORITY=$XAUTHORITY" > /var/lib/xdm/kdm_env
echo "DISPLAY=$DISPLAY" >> /var/lib/xdm/kdm_env
* In {{path|/etc/pam.d/xdm}} file, add {{path|/var/lib/xdm/kdm_env}} as a third parameter for {{path|pam_bioapi.so}} module:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/xdm/kdm_env
* On Ubuntu simply do:
echo "DISPLAY=$DISPLAY" >> /var/lib/kdm/kdm_env
* If you have created /etc/pam.d/bioapi then modify:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/kdm/kdm_env

Please note, that this won't work if you have more than one Xserver.

==Make xscreensaver use the scanner==
If you are using Gentoo, you can get a portage overlay with the necessary patches here: http://www.zzamboni.org/brt/files/xscreensaver-fingerprint-overlay.tar.gz
*Get the needed xscreensaver sources:
:{{cmduser|wget http://www.jwz.org/xscreensaver/xscreensaver-4.23.tar.gz}}
:{{cmduser|tar xzf xscreensaver-4.23.tar.gz}}
:{{cmduser|cd xscreensaver-4.23}}
:{{cmduser|wget http://www.nax.cz/pub/bioapi/2005/xscreensaver/xscreensaver-4.22_alternativeAuth.diff mirror: http://zepan.org/files/xscreensaver-4.22_alternativeAuth.diff For xscreensaver 5.00, you can get a patch here: http://www.zzamboni.org/brt/files/xscreensaver-5.00-alternativeauth.patch}}
*After reviewing the patch (it's small and straightforward), do
:{{cmduser|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 <tt>pam</tt> and <tt>pam_bioapi</tt>. It should apply with some offset, don't mind that. If it says something about rejected though, then there's a problem.
*Compile with
:{{cmduser|./configure --with-pam && make}} 
*If you receive an error like "Couldn't find X11 headers/libs" and are running a Debian-like system, try "apt-get install xlibs-dev"
*If you receive an error like "undefined reference to `XmuPrintDefaultErrorMessage'" then install the libxmu-dev package and run the previous line again and then install as root with
:{{cmduser|su -c make install}} .
*Make sure that the newly compiled xscreensaver is used:
:{{cmduser|which xscreensaver}} should return
:{{cmdresult|/usr/local/bin/xscreensaver}} .
*In case it doesn't, try adjusting your PATH.

==Common problems==
===Bioapi error #3===
This is sometimes caused by improper permissions. The full error message is "BioAPI Error Code: 3 (0x3)".

However, at least on Gentoo, recent upgrades to glibc and gcc 4.1.1 caused Bioapi to break down due to some sort of incompatibility with bioapi registry. Reinstalling does '''not''' repair the issue automatically. However, you can still fix the issue manually, by removing /var/bioapi. You need to reinstall tfm-fingerprint driver after reinstalling bioapi so that the driver is properly re-registered. As root, type

:{{cmdroot|emerge -C bioapi}}
:{{cmdroot|rm -rf /var/bioapi}}
:{{cmdroot|emerge -av1 bioapi tfm-fingerprint}}

How to enable integrated fingerprint reader with BioAPI

2009-01-10T06:55:55Z

Dpward: /* Installing from source */ A few more updates

{| width="100%"
|style="vertical-align:top;padding-right:20px;width:10px;white-space:nowrap;" | __TOC__
|style="vertical-align:top" |
This page describes the process of getting the [[Integrated Fingerprint Reader|integrated fingerprint reader]] to work under Linux, using bioapi and binary-only drivers. It is based on experiences in {{Ubuntu}} on a T43. The same works on {{Fedora}} 4 and 5, RHEL4, SuSE 9.3, SuSE 10, and {{Gentoo}}. Note that experimental open-source driver is available, see [[How to enable the fingerprint reader with ThinkFinger|the apropriate page]] for details.
|}

==Basic installation==
===Installing the bioapi framework===
====Automated installation script====
The [[Script for enabling the fingerprint reader]] automates the installation of most components (bioapi framework, driver, pam_bioapi, pam setup, device permissions, pamtester and enrolling), for some Linux distributions.

====Binary packages====

Note that these packages only take care of this one section. If you can use one, you should do so and then proceed to the section entitled, Installing and Configuring the Driver.

=====Debian/ Ubuntu Dapper=====
*If you're using {{Debian}} Sid (the unstable branch) or {{Ubuntu}} Dapper Drake 6.06 LTS you can try the packages from Michael R. Crusoe's site, either [http://www.qrivy.net/~michael/temp/ version 1.2.3] (recommended) or [http://www.qrivy.net/~michael/debs/unstable/ older versions] which might not work with the steps in this howto.

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

=====Gentoo=====
Gentoo now includes needed ebuilds. Just run

''ACCEPT_KEYWORDS=~x86 emerge pam_bioapi''

You can also grab the [http://www.qrivy.net/~michael/blua/bioapi/bioapi-1.2.2.ebuild.tar.bz2 ebuild], or use the source-install procedure below.

Also see [http://toe.ch/~tsa/ibm-fingerprint/ http://toe.ch/~tsa/ibm-fingerprint/] for alternative documentation on installing on Gentoo including ebuilds for all the packages used.

=====Fedora Core=====
RPM packages for Fedora Core and installation instructions are available [[Installing Fedora Core 5 on a ThinkPad X41 Tablet#Fingerprint_Reader|here]]

====Installing from source====
{{HINT|
For Ubuntu you'll need at least these packages, or building will fail:
* build-essential
* automake
* libqt3-headers
}}
* Get the bioapi source:
:{{cmduser|wget http://bioapi-linux.googlecode.com/files/bioapi_1.2.3.tar.gz}}
* Edit the configure file to patch a bug. At line 25975, change
:<code>bnv_qt_LIBS="-l$bnv_qt_lib_dir $LIBS"</code>
:to
:<code>bnv_qt_LIBS="-L$bnv_qt_lib_dir $LIBS"</code>
* Compile bioapi:
:{{cmduser|tar xzf bioapi_1.2.3.tar.gz}}
:{{cmduser|cd bioapi-1.2.3}}
:{{cmduser|1=./configure --with-Qt-dir=no}}
:{{cmduser|make}}
:and then as root
:{{cmdroot|make install}}
* If configure fails when checking the Qt installation, you may need to manually specify the Qt lib directory and Qt lib name. For example:
:{{cmduser|1=./configure --with-Qt-lib-dir=/usr/lib/qt3 --with-Qt-lib=qt-mt}}
:or you can compile without the graphical Qt tools:
:{{cmduser|1=./configure --with-Qt-dir=no}}
* If make install fails, be sure you're root and then:
:{{cmdroot|1=export LD_LIBRARY_PATH=/usr/local/lib}}
:{{cmdroot|make install}}
:and if you want to compile [http://code.google.com/p/pam-bioapi/ pam_bioapi] for auth later
:{{cmdroot|cp include/bioapi_util.h include/installdefs.h imports/cdsa/v2_0/inc/cssmtype.h /usr/include}}
:Be aware that checkinstall will not work!
* By default, bioapi will install numerous files in {{path|/usr/local/<nowiki>{</nowiki>bin,lib,include<nowiki>}</nowiki>}}, including files with "self-explanatory" names such as {{path|/usr/local/bin/Sample}}. To prevent this pollution:
:Create a dedicated directory, for example {{path|/opt/bioapi}} .
:Append <tt>--prefix=/opt/bioapi</tt> to the above <tt>./configure</tt> command.
:Append {{path|/opt/bioapi/bin}} to <tt>$PATH</tt> and {{path|/opt/bioapi/lib}} to <tt>$LD_LIBRARY_PATH</tt>.
:When installing the driver (below), tell it the new install path: {{cmdroot|sh install.sh /opt/bioapi/lib}}

====Adjusting ldconfigs library search path====
At least on {{Fedora}} or {{Aurox}} 11, you may need to add {{path|/usr/local/lib}} to the library path so that the libraries referenced from <tt>pam_bioapi.so</tt> get picked up properly. The usual way to do this is adding it to the ldconfig configuration:
:{{cmdroot|echo '/usr/local/lib' > /etc/ld.so.conf.d/bioapi.conf}}
:{{cmdroot|ldconfig}}
Alternatively you can add it to the LD_LIBRARY variable.

If you see bioapi libs in the output of
:{{cmdroot|ldconfig -p | grep bioapi}}
then it should work.

===Installing and configuring the driver===
====Installing the driver====
*Download {{path|TFMESS_BSP_LIN_1.0.zip}} from the [http://www.upek.com/support/dl_linux_bsp.asp UPEK support site] and unzip it into a seperate folder, as it will not create one.
*Change to that folder and do as root:
:{{cmdroot|sh install.sh}}
:If you're running Gentoo, Debian or Ubuntu Dapper, use
:{{cmdroot|sh install.sh /usr/lib}}
{{HINT|
For me it didn't work this way, but following did:
:sh install.sh /usr/local/lib
greetings, tec}}
{{HINT|On my debian install I had to "cp libtfmessbsp.so /usr/lib" to avoid a errormessage during "sh install.sh /usr/lib": "Could not find file:/usr/lib/libtfmessbsp.so"}}
:If that fails, it may be that make install failed up above -- try setting LD_LIBRARY_PATH, do the make install again, and come back here and try this again. You also need {{cmd|mod_install|}} from bioapi in your PATH.
:May there still occures and error, which means mod_install: command not found.
:Then login as root - not su!
:Do this:
:{{cmdroot|sh install.sh}}
:again. It should work. SU to root does not work since then the /usr/local/bin directory is not used per default.

====Configuring permissions for non-root use====
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), you may need to do all or at least some of the things in this section. More details on what is necessary on which distributions would be greately appreciated.
*Create two groups, one for access to BioAPI files and the other for access to the usb files. (This is done for full generality; i.e., you may have other USB devices which you want accessable to other users, without exposing your BioAPI configuration to them). Add your normal user (the one you wish to use PAM-aware applications with) to both of these groups.
On {{Debian}} this is done with
:{{cmdroot|addgroup --system bioapi}}
:{{cmdroot|addgroup --system usbfs}}
:{{cmdroot|adduser yournormaluser bioapi}}
:{{cmdroot|adduser yournormaluser usbfs}}
On {{SUSE}} this is done with
:{{cmdroot|groupadd --system bioapi}}
:{{cmdroot|groupadd --system usbfs}}
:{{cmdroot|groupmod -A yournormaluser bioapi}}
:{{cmdroot|groupmod -A yournormaluser usbfs}}
On {{Mandriva}} this is done with
:{{cmdroot|groupadd -r bioapi}}
:{{cmdroot|groupadd -r usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}
On {{Fedora}} this is done with
:{{cmdroot|groupadd bioapi}}
:{{cmdroot|groupadd usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}

:(where {{cmd|yournormaluser|}} is your normal user name). You will need to log out and log back in for this to take effect.
*Set permissions on the BioAPI config/registry directory:
:{{cmdroot|chown -R root:bioapi /usr/local/var/bioapi/}}
:{{cmdroot|chmod -R 770 /usr/local/var/bioapi/}}
:(change this path if you used an alternate BioAPI install directory above)
*Set permissions on the files in {{path|/proc/bus/usb}}:
:{{cmdroot|chown -R root:usbfs /proc/bus/usb}}
:{{cmdroot|chmod -R g+X /proc/bus/usb}}
:{{cmdroot|chown root:usbfs /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:{{cmdroot|chmod 660 /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:You may need to replace {{cmd|lsusb|}} with its full path, which is something like {{cmd|/sbin/lsusb|}} or {{cmd|/usr/bin/lsusb|}} depending on your distro. It might be necessary to put these lines into a script which is run at startup and resume from suspend/hibernate.
In {{Fedora}} {{cmd|lsusb|}} is not installed by default. To intall it just type:
:{{cmdroot|yum install usbutils}}

*As an alternative to the {{cmd|chown|}}/{{cmd|chmod|}} commands above, you can set mount options for usbfs with a line in {{path|/etc/fstab|}}; an example would be
none /proc/bus/usb usbfs defaults,devgid=108,devmode=0660,busgid=108,busmode=0770,listgid=108,listmode=0660 0 0
:where 108 is replaced with the numerical group ID of the usbfs group (you can determine this with something like {{cmd|cat /etc/group <nowiki>|</nowiki> grep usbfs <nowiki>|</nowiki> cut -d':' -f 3|}}). Make sure you only have one {{path|/proc/bus/usb}} entry in {{path|/etc/fstab}}. See the {{cmd|mount(8)|}} manpage for more information on these options. This is "cleaner" but seems to have a few weird issues -- see the talk page for details.
*You may also have files in {{path|/dev/bus/usb}}, which the driver will try before {{path|/proc/bus/usb}}. If this is another usbfs mount point ({{cmd|mount|}} shows a line containing {{cmdresult|/dev/bus/usb type usbfs}}), then simply follow the above instructions with {{path|/dev/bus/usb}} rather than {{path|/proc/bus/usb}}. Otherwise, you may be running a new kernel (i.e. 2.6.15) that makes usbfs-like files available through {{path|/dev/bus/usb}}.
*On systems running udev these files are dynamically created; you can configure their permissions by editing a udev config file. On Debian this is done by changing the <tt>usb_device</tt> line of {{path|/etc/udev/permissions.rules}} to read
SUBSYSTEM=="usb_device", MODE="0660", GROUP="usbfs"
*For the beta versions only, there is a logfile, which needs to exist with the proper permissions:
:{{cmdroot|touch /var/log/BSP.log && chown root:bioapi /var/log/BSP.log && chmod 660 /var/log/BSP.log}}

====Miscellaneous configuration====
* To increase the security level (minimize false accept rate), set this in {{path|/etc/tfmessbsp.cfg}}:
security-level="5"
{{WARN|Please see discussion section Security Level!}}

===Testing the driver and enrolling a fingerprint===
To test the driver and generate the file containing your fingerprint information, you need a sample program included with the driver. The compilation steps below were discovered by trial and error; if they don't work for you, try the binary {{cmd|Sample|}} utility that came with the beta versions of the driver (i.e., {{path|TFMESS_BSP_LIN_1.0beta2.zip}} as mentioned above).
Go to the folder where you extracted {{path|TFMESS_BSP_LIN_1.0.zip}} and do:
:{{cmdroot|cd NonGUI_Sample}}
:Edit {{path|main.c|}} and remove (or comment out) the line
#include "port/bioapi_port.h"
:then add the line
#include <stdlib.h>
:{{cmdroot|gcc -o Sample main.c -L/usr/local/lib -lbioapi100 -DUNIX -DLITTLE_ENDIAN}}
:{{cmdroot|./Sample}}
:Note that Sample may only run as root, unless you've already configured the usbfs file permissions.
:You can try to "e"nroll (to record a fingerprint for an account) and then "v"erify (to test a fingerprint against the one it expects for an account).
:You'll save a step later if you use your own login username as the username to enroll here.
:If running {{cmd |./Sample|}} produces the error message 'BioAPI_ModuleLoad failed, BioAPI Error Code: 6477 (0x194d)'
:then uncommenting the line
://BioAPI_SetGUICallbacks(gModuleHandle, NULL, NULL,TextGuiCallback, NULL);
:in {{path|main.c|}} can help.

==Login via pam_bioapi==

The following explains how to add fingerprint authentiation to programs that use the PAM (Pluggable Authentication Modules) framework, such as Gnome's GDM and KDE's KDM and screensaver.

===Getting required libs & tools===
====Installing pam_bioapi====
*Prerequisites
:On SuSE 10, I needed to install the pam-devel RPM
:In general, you will need pam itself (standard for most distros) as well as the pam development files (probably an optional package for your distro).
*Get and compile the pam_bioapi module.
{{HINT|A new version, pam_bioapi 0.3.0, with multi-finger and identification support can be found [http://www.nax.cz/pub/bioapi/pam_bioapi/pam-bioapi_0.3.0.tar.gz here].
There's work in progress. pam_bioapi and biometrics-manager can be downloaded [http://download.savannah.gnu.org/releases/pam-bioapi/ here].}}
:{{cmduser|wget http://www.qrivy.net/~michael/blua/pam_bioapi/pam_bioapi-latest.tar.bz2}}
:{{cmduser|tar xjf pam_bioapi-latest.tar.bz2}}
:{{cmduser|cd pam_bioapi-0.2.1}}
:{{cmduser|wget http://badcode.de/downloads/fingerprint.patch}}
:{{cmduser|patch -p0 < fingerprint.patch}}
:If you want to, review the patch. In general you should review all code you download and compile, if possible.
:{{cmduser|<nowiki>./configure --libdir=/lib && make </nowiki>}}
:and as root
:{{cmdroot| make install}}
{{NOTE|If you get a 'rpl_malloc' error in /var/log/auth.log when trying to use the fingerprint reader, redo these steps and remove the related term from Makefile after running ./configure. (FC3, Debian etch)}}
*If you get 'configure: error: cannot find required header: security/_pam_macros.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again. If you are using a Mandriva distribution, do "urpmi libpam0-devel" instead.
*If you get 'configure: error: cannot find required header: security/pam_modules.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again.
*If you get 'configure: error: cannot find required header: sqlite3.h' and are on a Debian-like system, do "apt-get install libsqlite3-dev" and try again.
*If you get 'make: msgfmt: command not found' and are on a Debian-like system, do "apt-get install gettext" and try again.
*If you get 'PAM [dlerror: /lib/security/pam_bioapi.so: undefined symbol: BioAPIMemoryFuncs]' error in your syslog, replace 'LIBS = ' line in {{path|libpam_bioapi/makefile}} with the following (of course, replace {{path|/opt/bioapi/}} with the path where you installed bioapi):
LIBS = -L/opt/bioapi/lib -lbioapi100 -lbioapi_mds300 -lmds_util
*Use the sample tool from the fingerprint reader to create {{path|<username>.bir}} (<tt><username></tt> '''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:
:{{cmdroot|SERIAL<nowiki>=`BioAPITest | sed -ne "/Fingerprint/{n;n;s/^.*: $.\{9\}$$.\{4\}$$.\{4\}$$.\{4\}$$.*$/\1-\2-\3-\4-\5/gp}"` </nowiki>}}
:{{cmdroot|echo $SERIAL}} should print something like {{cmdresult|<nowiki>{5550454b-2054-464d-2f45-535320425350}</nowiki>}} now.
:If it does, do:
:{{cmdroot|mkdir -p /etc/bioapi/pam/$SERIAL}}
:{{cmdroot|cp <username>.bir /etc/bioapi/pam/$SERIAL}}
:If not, you might just try
:{{cmdroot|SERIAL<nowiki>={5550454b-2054-464d-2f45-535320425350}</nowiki>}}
:as this value is hardcoded into the UPEK docs.

===Configuring pam===
The following part is distribution specific. On {{Ubuntu}} or {{SUSE}} you can modify {{path|/etc/pam.d/common-auth}} (on {{Gentoo}} and {{Fedora}} it is {{path|/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/bioapi/pam/
password sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_unix.so nullok_secure

----
For '''Gentoo'''-Users - this allows you to attempt a password first. If you simply press enter, it then prompts for a fingerprints. Create a file named {{path|/etc/pam.d/bioapi}}. This also means that remote services, such as SSH keep working:

auth required pam_env.so
auth sufficient pam_unix.so likeauth nullok
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_deny.so

account required pam_unix.so

session required pam_limits.so
session required pam_unix.so

----

Now, simply replace "auth include system-auth" in all services that you wish to use fingerprint for with "auth include bioapi". For example, {{path|/etc/pam.d/kde}} by default contains

auth include system-auth
auth required pam_nologin.so

account include system-auth

password include system-auth

session include system-auth

Simply replace the first "system-auth" with bioapi and you can also get rid of KDE desktop lock with a fingerprint. If you do not wish to allow for "password fallback" then remove

auth sufficient pam_unix.so likeauth nullok

from {{path|/etc/pam.d/bioapi}}.

{{WARN|If su/sudo expects to receive the root password (SuSE 10), you need to have fingerprint settings for root (that is, copy in a root.bir as well as a your-username.bir). Otherwise, they get a segmentation fault. Which is a little unfortunate, given that you need to su or sudo to change your settings... }}
{{WARN|Not only SuSE 10 requires root.bir to be available for su to work. Just make sure you have root.bir when su is not working with your fingerprint reader but other applications are...}}
Note that sshd may pick up the fingerprint settings from {{path|/etc/pam.d/common-auth}}. I didn't want that, so I removed the "auth include common-auth" line from {{path|/etc/pam.d/sshd}} and replaced it with the lines that were originally in my {{path|/etc/pam.d/common-auth}}. That way most local services use the fingerprint reader, but sshd does not.

{{NOTE|su/sudo will call for your fingerprint even if you are remote via ssh. Pressing *CTLR-c* (or closing graphic window) will allow you the desired password option.}}

Another way to do this is to create a file ({{path|/etc/pam.d/bioapi|}} for example) which contains the {{cmd|pam_bioapi.so|}} lines, and explicitly {{cmd|@include|}} this '''before''' {{path|/etc/pam.d/common-auth|}} in the files for services which should use the fingerprint reader. In this case you should leave {{path|/etc/pam.d/common-auth|}} alone.

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

In {{Fedora}} the original 'session' terms in {{path|/etc/pam.d/system-auth}} need to be kept.

{{HINT|The setup described above will/could affect remote ssh logins to also use biometric logins, which is a bit silly (who wants to remote ssh to the laptop, and then have to walk over to it and swipe your finger) To avoid that you can copy the default <tt>/etc/pam.d/system-auth</tt> to <tt>/etc/pam.d/sshd</tt> which will allow the sshd service to use the standard authentication procedure.}}

----

To enable normal password authorization to work with remote SSH in {{SUSE}} 10.3, edit the <tt>/etc/pam.d/sshd</tt> file. Remove all entries and replace them with:

auth required pam_env.so
auth required pam_unix2.so
auth required pam_nologin.so
account required pam_unix2.so
password required pam_pwcheck.so nullok
password required pam_unix2.so nullok use_first_pass use_authtok
session required pam_limits.so
session required pam_unix2.so

{{NOTE|These entries are what common-auth normally does. Since we've changed common-auth around for bioapi, these need to be specified manually. -Ransak}}

----

You can do some useful testing with [http://pamtester.sourceforge.net/ {{cmd|pamtester|}}], which calls the pam modules as if it were a program of your choice. Examples:
:{{cmdroot|pamtester xdm yourusername authenticate}}
:{{cmduser|pamtester xscreensaver yourusername authenticate}}
where {{cmd|yourusername|}} is your username. Note that {{cmd|pamtester|}} should run as root if and only if the program in question does.

===Application support===
The implementation of fingerprint scanning support in the relevant applications varies.

Here is the behaviour of the most common ones:
* In gdm enter your username and there should pop up an (ugly) image to swipe your finger and... magic - you can login without a password.
* kdm doesn't give any visual indication, other than that the cursor stops blinking. Just swipe your finger and hope it lets you log in.
* In xdm, enter your username and a blank password, then swipe (there is no popup as well). Identification support for xdm can be achieved with [http://www.nax.cz/pub/bioapi/2005/xdm/xdm_bio.patch this patch].
* The KDE screen saver in SUSE 10 requires you to enter an empty password (or select the correct user and then enter an empty password) in order to get the fingerprint prompt.
* For Fedora users, the redhat-config tools will crash if no root.bir presents. Also, there won't be any visual idication unless X server is properly configured for root to access. Just swipe your finger when the HDD stopped blinking or issue the following command in advance:
:{{cmduser|xhost +local:}}
* For RHEL4 users gdm, console (virtual terminal) logins and the xscreensaver all work

===kdm support===
To add graphical popup to kdm, you need following:
* Patch for pam_bioapi. This patch adds third parameter to {{path|pam_bioapi.so}} module, which is a name of file with additional environment variables that will be supplied to the UPEK driver.
:{{cmdroot|wget http://upir.cz/linux/patches/pam_bioapi-0.2.1-alter-environ.patch}}
:{{cmdroot|patch -p1 < pam_bioapi-0.2.1-alter-environ.patch}}
* Edit your {{path|Xsetup}} file (on SUSE 10 it's {{path|/etc/X11/xdm/Xsetup}}) and add these lines:
echo "XAUTHORITY=$XAUTHORITY" > /var/lib/xdm/kdm_env
echo "DISPLAY=$DISPLAY" >> /var/lib/xdm/kdm_env
* In {{path|/etc/pam.d/xdm}} file, add {{path|/var/lib/xdm/kdm_env}} as a third parameter for {{path|pam_bioapi.so}} module:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/xdm/kdm_env
* On Ubuntu simply do:
echo "DISPLAY=$DISPLAY" >> /var/lib/kdm/kdm_env
* If you have created /etc/pam.d/bioapi then modify:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/kdm/kdm_env

Please note, that this won't work if you have more than one Xserver.

==Make xscreensaver use the scanner==
If you are using Gentoo, you can get a portage overlay with the necessary patches here: http://www.zzamboni.org/brt/files/xscreensaver-fingerprint-overlay.tar.gz
*Get the needed xscreensaver sources:
:{{cmduser|wget http://www.jwz.org/xscreensaver/xscreensaver-4.23.tar.gz}}
:{{cmduser|tar xzf xscreensaver-4.23.tar.gz}}
:{{cmduser|cd xscreensaver-4.23}}
:{{cmduser|wget http://www.nax.cz/pub/bioapi/2005/xscreensaver/xscreensaver-4.22_alternativeAuth.diff mirror: http://zepan.org/files/xscreensaver-4.22_alternativeAuth.diff For xscreensaver 5.00, you can get a patch here: http://www.zzamboni.org/brt/files/xscreensaver-5.00-alternativeauth.patch}}
*After reviewing the patch (it's small and straightforward), do
:{{cmduser|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 <tt>pam</tt> and <tt>pam_bioapi</tt>. It should apply with some offset, don't mind that. If it says something about rejected though, then there's a problem.
*Compile with
:{{cmduser|./configure --with-pam && make}} 
*If you receive an error like "Couldn't find X11 headers/libs" and are running a Debian-like system, try "apt-get install xlibs-dev"
*If you receive an error like "undefined reference to `XmuPrintDefaultErrorMessage'" then install the libxmu-dev package and run the previous line again and then install as root with
:{{cmduser|su -c make install}} .
*Make sure that the newly compiled xscreensaver is used:
:{{cmduser|which xscreensaver}} should return
:{{cmdresult|/usr/local/bin/xscreensaver}} .
*In case it doesn't, try adjusting your PATH.

==Common problems==
===Bioapi error #3===
This is sometimes caused by improper permissions. The full error message is "BioAPI Error Code: 3 (0x3)".

However, at least on Gentoo, recent upgrades to glibc and gcc 4.1.1 caused Bioapi to break down due to some sort of incompatibility with bioapi registry. Reinstalling does '''not''' repair the issue automatically. However, you can still fix the issue manually, by removing /var/bioapi. You need to reinstall tfm-fingerprint driver after reinstalling bioapi so that the driver is properly re-registered. As root, type

:{{cmdroot|emerge -C bioapi}}
:{{cmdroot|rm -rf /var/bioapi}}
:{{cmdroot|emerge -av1 bioapi tfm-fingerprint}}

How to enable integrated fingerprint reader with BioAPI

2009-01-10T06:51:10Z

Dpward: /* Installing from source */ More updates

{| width="100%"
|style="vertical-align:top;padding-right:20px;width:10px;white-space:nowrap;" | __TOC__
|style="vertical-align:top" |
This page describes the process of getting the [[Integrated Fingerprint Reader|integrated fingerprint reader]] to work under Linux, using bioapi and binary-only drivers. It is based on experiences in {{Ubuntu}} on a T43. The same works on {{Fedora}} 4 and 5, RHEL4, SuSE 9.3, SuSE 10, and {{Gentoo}}. Note that experimental open-source driver is available, see [[How to enable the fingerprint reader with ThinkFinger|the apropriate page]] for details.
|}

==Basic installation==
===Installing the bioapi framework===
====Automated installation script====
The [[Script for enabling the fingerprint reader]] automates the installation of most components (bioapi framework, driver, pam_bioapi, pam setup, device permissions, pamtester and enrolling), for some Linux distributions.

====Binary packages====

Note that these packages only take care of this one section. If you can use one, you should do so and then proceed to the section entitled, Installing and Configuring the Driver.

=====Debian/ Ubuntu Dapper=====
*If you're using {{Debian}} Sid (the unstable branch) or {{Ubuntu}} Dapper Drake 6.06 LTS you can try the packages from Michael R. Crusoe's site, either [http://www.qrivy.net/~michael/temp/ version 1.2.3] (recommended) or [http://www.qrivy.net/~michael/debs/unstable/ older versions] which might not work with the steps in this howto.

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

=====Gentoo=====
Gentoo now includes needed ebuilds. Just run

''ACCEPT_KEYWORDS=~x86 emerge pam_bioapi''

You can also grab the [http://www.qrivy.net/~michael/blua/bioapi/bioapi-1.2.2.ebuild.tar.bz2 ebuild], or use the source-install procedure below.

Also see [http://toe.ch/~tsa/ibm-fingerprint/ http://toe.ch/~tsa/ibm-fingerprint/] for alternative documentation on installing on Gentoo including ebuilds for all the packages used.

=====Fedora Core=====
RPM packages for Fedora Core and installation instructions are available [[Installing Fedora Core 5 on a ThinkPad X41 Tablet#Fingerprint_Reader|here]]

====Installing from source====
{{HINT|
For Ubuntu you'll need at least the:
* build-essential
* automake
* libqt3-headers
:packages, or building will fail.
}}
*Get the bioapi source:
:{{cmduser|wget http://bioapi-linux.googlecode.com/files/bioapi_1.2.3.tar.gz}}
*Edit the configure file to patch a bug. At line 25975, change
:<code>bnv_qt_LIBS="-l$bnv_qt_lib_dir $LIBS"</code>
:to
:<code>bnv_qt_LIBS="-L$bnv_qt_lib_dir $LIBS"</code>
:Then at line
* I could not compile bioapi with the graphical Qt tools. To do it manually, do the following:
:{{cmduser|tar xzf bioapi_1.2.3.tar.gz}}
:{{cmduser|cd bioapi-1.2.3}}
:{{cmduser|1=./configure --with-Qt-dir=no}}
:{{cmduser|make}}
:and then as root
:{{cmdroot|make install}}
:If make install fails, be sure you're root and then:
:{{cmdroot|1=export LD_LIBRARY_PATH=/usr/local/lib}}
:{{cmdroot|make install}}
:and if you want to compile [http://code.google.com/p/pam-bioapi/ pam_bioapi] for auth later
:{{cmdroot|cp include/bioapi_util.h include/installdefs.h imports/cdsa/v2_0/inc/cssmtype.h /usr/include}}
:Be aware that checkinstall will not work!
* If configure fails when checking the Qt installation, you may need to manually specify the Qt lib directory and Qt lib name. For example:
:{{cmduser|1=./configure --with-Qt-lib-dir=/usr/lib/qt3 --with-Qt-lib=qt-mt}}
* By default, bioapi will install numerous files in {{path|/usr/local/<nowiki>{</nowiki>bin,lib,include<nowiki>}</nowiki>}}, including files with "self-explanatory" names such as {{path|/usr/local/bin/Sample}}. To prevent this pollution:
:Create a dedicated directory, for example {{path|/opt/bioapi}} .
:Append <tt>--prefix=/opt/bioapi</tt> to the above <tt>./configure</tt> command.
:Append {{path|/opt/bioapi/bin}} to <tt>$PATH</tt> and {{path|/opt/bioapi/lib}} to <tt>$LD_LIBRARY_PATH</tt>.
:When installing the driver (below), tell it the new install path: {{cmdroot|sh install.sh /opt/bioapi/lib}}

====Adjusting ldconfigs library search path====
At least on {{Fedora}} or {{Aurox}} 11, you may need to add {{path|/usr/local/lib}} to the library path so that the libraries referenced from <tt>pam_bioapi.so</tt> get picked up properly. The usual way to do this is adding it to the ldconfig configuration:
:{{cmdroot|echo '/usr/local/lib' > /etc/ld.so.conf.d/bioapi.conf}}
:{{cmdroot|ldconfig}}
Alternatively you can add it to the LD_LIBRARY variable.

If you see bioapi libs in the output of
:{{cmdroot|ldconfig -p | grep bioapi}}
then it should work.

===Installing and configuring the driver===
====Installing the driver====
*Download {{path|TFMESS_BSP_LIN_1.0.zip}} from the [http://www.upek.com/support/dl_linux_bsp.asp UPEK support site] and unzip it into a seperate folder, as it will not create one.
*Change to that folder and do as root:
:{{cmdroot|sh install.sh}}
:If you're running Gentoo, Debian or Ubuntu Dapper, use
:{{cmdroot|sh install.sh /usr/lib}}
{{HINT|
For me it didn't work this way, but following did:
:sh install.sh /usr/local/lib
greetings, tec}}
{{HINT|On my debian install I had to "cp libtfmessbsp.so /usr/lib" to avoid a errormessage during "sh install.sh /usr/lib": "Could not find file:/usr/lib/libtfmessbsp.so"}}
:If that fails, it may be that make install failed up above -- try setting LD_LIBRARY_PATH, do the make install again, and come back here and try this again. You also need {{cmd|mod_install|}} from bioapi in your PATH.
:May there still occures and error, which means mod_install: command not found.
:Then login as root - not su!
:Do this:
:{{cmdroot|sh install.sh}}
:again. It should work. SU to root does not work since then the /usr/local/bin directory is not used per default.

====Configuring permissions for non-root use====
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), you may need to do all or at least some of the things in this section. More details on what is necessary on which distributions would be greately appreciated.
*Create two groups, one for access to BioAPI files and the other for access to the usb files. (This is done for full generality; i.e., you may have other USB devices which you want accessable to other users, without exposing your BioAPI configuration to them). Add your normal user (the one you wish to use PAM-aware applications with) to both of these groups.
On {{Debian}} this is done with
:{{cmdroot|addgroup --system bioapi}}
:{{cmdroot|addgroup --system usbfs}}
:{{cmdroot|adduser yournormaluser bioapi}}
:{{cmdroot|adduser yournormaluser usbfs}}
On {{SUSE}} this is done with
:{{cmdroot|groupadd --system bioapi}}
:{{cmdroot|groupadd --system usbfs}}
:{{cmdroot|groupmod -A yournormaluser bioapi}}
:{{cmdroot|groupmod -A yournormaluser usbfs}}
On {{Mandriva}} this is done with
:{{cmdroot|groupadd -r bioapi}}
:{{cmdroot|groupadd -r usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}
On {{Fedora}} this is done with
:{{cmdroot|groupadd bioapi}}
:{{cmdroot|groupadd usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}

:(where {{cmd|yournormaluser|}} is your normal user name). You will need to log out and log back in for this to take effect.
*Set permissions on the BioAPI config/registry directory:
:{{cmdroot|chown -R root:bioapi /usr/local/var/bioapi/}}
:{{cmdroot|chmod -R 770 /usr/local/var/bioapi/}}
:(change this path if you used an alternate BioAPI install directory above)
*Set permissions on the files in {{path|/proc/bus/usb}}:
:{{cmdroot|chown -R root:usbfs /proc/bus/usb}}
:{{cmdroot|chmod -R g+X /proc/bus/usb}}
:{{cmdroot|chown root:usbfs /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:{{cmdroot|chmod 660 /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:You may need to replace {{cmd|lsusb|}} with its full path, which is something like {{cmd|/sbin/lsusb|}} or {{cmd|/usr/bin/lsusb|}} depending on your distro. It might be necessary to put these lines into a script which is run at startup and resume from suspend/hibernate.
In {{Fedora}} {{cmd|lsusb|}} is not installed by default. To intall it just type:
:{{cmdroot|yum install usbutils}}

*As an alternative to the {{cmd|chown|}}/{{cmd|chmod|}} commands above, you can set mount options for usbfs with a line in {{path|/etc/fstab|}}; an example would be
none /proc/bus/usb usbfs defaults,devgid=108,devmode=0660,busgid=108,busmode=0770,listgid=108,listmode=0660 0 0
:where 108 is replaced with the numerical group ID of the usbfs group (you can determine this with something like {{cmd|cat /etc/group <nowiki>|</nowiki> grep usbfs <nowiki>|</nowiki> cut -d':' -f 3|}}). Make sure you only have one {{path|/proc/bus/usb}} entry in {{path|/etc/fstab}}. See the {{cmd|mount(8)|}} manpage for more information on these options. This is "cleaner" but seems to have a few weird issues -- see the talk page for details.
*You may also have files in {{path|/dev/bus/usb}}, which the driver will try before {{path|/proc/bus/usb}}. If this is another usbfs mount point ({{cmd|mount|}} shows a line containing {{cmdresult|/dev/bus/usb type usbfs}}), then simply follow the above instructions with {{path|/dev/bus/usb}} rather than {{path|/proc/bus/usb}}. Otherwise, you may be running a new kernel (i.e. 2.6.15) that makes usbfs-like files available through {{path|/dev/bus/usb}}.
*On systems running udev these files are dynamically created; you can configure their permissions by editing a udev config file. On Debian this is done by changing the <tt>usb_device</tt> line of {{path|/etc/udev/permissions.rules}} to read
SUBSYSTEM=="usb_device", MODE="0660", GROUP="usbfs"
*For the beta versions only, there is a logfile, which needs to exist with the proper permissions:
:{{cmdroot|touch /var/log/BSP.log && chown root:bioapi /var/log/BSP.log && chmod 660 /var/log/BSP.log}}

====Miscellaneous configuration====
* To increase the security level (minimize false accept rate), set this in {{path|/etc/tfmessbsp.cfg}}:
security-level="5"
{{WARN|Please see discussion section Security Level!}}

===Testing the driver and enrolling a fingerprint===
To test the driver and generate the file containing your fingerprint information, you need a sample program included with the driver. The compilation steps below were discovered by trial and error; if they don't work for you, try the binary {{cmd|Sample|}} utility that came with the beta versions of the driver (i.e., {{path|TFMESS_BSP_LIN_1.0beta2.zip}} as mentioned above).
Go to the folder where you extracted {{path|TFMESS_BSP_LIN_1.0.zip}} and do:
:{{cmdroot|cd NonGUI_Sample}}
:Edit {{path|main.c|}} and remove (or comment out) the line
#include "port/bioapi_port.h"
:then add the line
#include <stdlib.h>
:{{cmdroot|gcc -o Sample main.c -L/usr/local/lib -lbioapi100 -DUNIX -DLITTLE_ENDIAN}}
:{{cmdroot|./Sample}}
:Note that Sample may only run as root, unless you've already configured the usbfs file permissions.
:You can try to "e"nroll (to record a fingerprint for an account) and then "v"erify (to test a fingerprint against the one it expects for an account).
:You'll save a step later if you use your own login username as the username to enroll here.
:If running {{cmd |./Sample|}} produces the error message 'BioAPI_ModuleLoad failed, BioAPI Error Code: 6477 (0x194d)'
:then uncommenting the line
://BioAPI_SetGUICallbacks(gModuleHandle, NULL, NULL,TextGuiCallback, NULL);
:in {{path|main.c|}} can help.

==Login via pam_bioapi==

The following explains how to add fingerprint authentiation to programs that use the PAM (Pluggable Authentication Modules) framework, such as Gnome's GDM and KDE's KDM and screensaver.

===Getting required libs & tools===
====Installing pam_bioapi====
*Prerequisites
:On SuSE 10, I needed to install the pam-devel RPM
:In general, you will need pam itself (standard for most distros) as well as the pam development files (probably an optional package for your distro).
*Get and compile the pam_bioapi module.
{{HINT|A new version, pam_bioapi 0.3.0, with multi-finger and identification support can be found [http://www.nax.cz/pub/bioapi/pam_bioapi/pam-bioapi_0.3.0.tar.gz here].
There's work in progress. pam_bioapi and biometrics-manager can be downloaded [http://download.savannah.gnu.org/releases/pam-bioapi/ here].}}
:{{cmduser|wget http://www.qrivy.net/~michael/blua/pam_bioapi/pam_bioapi-latest.tar.bz2}}
:{{cmduser|tar xjf pam_bioapi-latest.tar.bz2}}
:{{cmduser|cd pam_bioapi-0.2.1}}
:{{cmduser|wget http://badcode.de/downloads/fingerprint.patch}}
:{{cmduser|patch -p0 < fingerprint.patch}}
:If you want to, review the patch. In general you should review all code you download and compile, if possible.
:{{cmduser|<nowiki>./configure --libdir=/lib && make </nowiki>}}
:and as root
:{{cmdroot| make install}}
{{NOTE|If you get a 'rpl_malloc' error in /var/log/auth.log when trying to use the fingerprint reader, redo these steps and remove the related term from Makefile after running ./configure. (FC3, Debian etch)}}
*If you get 'configure: error: cannot find required header: security/_pam_macros.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again. If you are using a Mandriva distribution, do "urpmi libpam0-devel" instead.
*If you get 'configure: error: cannot find required header: security/pam_modules.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again.
*If you get 'configure: error: cannot find required header: sqlite3.h' and are on a Debian-like system, do "apt-get install libsqlite3-dev" and try again.
*If you get 'make: msgfmt: command not found' and are on a Debian-like system, do "apt-get install gettext" and try again.
*If you get 'PAM [dlerror: /lib/security/pam_bioapi.so: undefined symbol: BioAPIMemoryFuncs]' error in your syslog, replace 'LIBS = ' line in {{path|libpam_bioapi/makefile}} with the following (of course, replace {{path|/opt/bioapi/}} with the path where you installed bioapi):
LIBS = -L/opt/bioapi/lib -lbioapi100 -lbioapi_mds300 -lmds_util
*Use the sample tool from the fingerprint reader to create {{path|<username>.bir}} (<tt><username></tt> '''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:
:{{cmdroot|SERIAL<nowiki>=`BioAPITest | sed -ne "/Fingerprint/{n;n;s/^.*: $.\{9\}$$.\{4\}$$.\{4\}$$.\{4\}$$.*$/\1-\2-\3-\4-\5/gp}"` </nowiki>}}
:{{cmdroot|echo $SERIAL}} should print something like {{cmdresult|<nowiki>{5550454b-2054-464d-2f45-535320425350}</nowiki>}} now.
:If it does, do:
:{{cmdroot|mkdir -p /etc/bioapi/pam/$SERIAL}}
:{{cmdroot|cp <username>.bir /etc/bioapi/pam/$SERIAL}}
:If not, you might just try
:{{cmdroot|SERIAL<nowiki>={5550454b-2054-464d-2f45-535320425350}</nowiki>}}
:as this value is hardcoded into the UPEK docs.

===Configuring pam===
The following part is distribution specific. On {{Ubuntu}} or {{SUSE}} you can modify {{path|/etc/pam.d/common-auth}} (on {{Gentoo}} and {{Fedora}} it is {{path|/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/bioapi/pam/
password sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_unix.so nullok_secure

----
For '''Gentoo'''-Users - this allows you to attempt a password first. If you simply press enter, it then prompts for a fingerprints. Create a file named {{path|/etc/pam.d/bioapi}}. This also means that remote services, such as SSH keep working:

auth required pam_env.so
auth sufficient pam_unix.so likeauth nullok
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_deny.so

account required pam_unix.so

session required pam_limits.so
session required pam_unix.so

----

Now, simply replace "auth include system-auth" in all services that you wish to use fingerprint for with "auth include bioapi". For example, {{path|/etc/pam.d/kde}} by default contains

auth include system-auth
auth required pam_nologin.so

account include system-auth

password include system-auth

session include system-auth

Simply replace the first "system-auth" with bioapi and you can also get rid of KDE desktop lock with a fingerprint. If you do not wish to allow for "password fallback" then remove

auth sufficient pam_unix.so likeauth nullok

from {{path|/etc/pam.d/bioapi}}.

{{WARN|If su/sudo expects to receive the root password (SuSE 10), you need to have fingerprint settings for root (that is, copy in a root.bir as well as a your-username.bir). Otherwise, they get a segmentation fault. Which is a little unfortunate, given that you need to su or sudo to change your settings... }}
{{WARN|Not only SuSE 10 requires root.bir to be available for su to work. Just make sure you have root.bir when su is not working with your fingerprint reader but other applications are...}}
Note that sshd may pick up the fingerprint settings from {{path|/etc/pam.d/common-auth}}. I didn't want that, so I removed the "auth include common-auth" line from {{path|/etc/pam.d/sshd}} and replaced it with the lines that were originally in my {{path|/etc/pam.d/common-auth}}. That way most local services use the fingerprint reader, but sshd does not.

{{NOTE|su/sudo will call for your fingerprint even if you are remote via ssh. Pressing *CTLR-c* (or closing graphic window) will allow you the desired password option.}}

Another way to do this is to create a file ({{path|/etc/pam.d/bioapi|}} for example) which contains the {{cmd|pam_bioapi.so|}} lines, and explicitly {{cmd|@include|}} this '''before''' {{path|/etc/pam.d/common-auth|}} in the files for services which should use the fingerprint reader. In this case you should leave {{path|/etc/pam.d/common-auth|}} alone.

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

In {{Fedora}} the original 'session' terms in {{path|/etc/pam.d/system-auth}} need to be kept.

{{HINT|The setup described above will/could affect remote ssh logins to also use biometric logins, which is a bit silly (who wants to remote ssh to the laptop, and then have to walk over to it and swipe your finger) To avoid that you can copy the default <tt>/etc/pam.d/system-auth</tt> to <tt>/etc/pam.d/sshd</tt> which will allow the sshd service to use the standard authentication procedure.}}

----

To enable normal password authorization to work with remote SSH in {{SUSE}} 10.3, edit the <tt>/etc/pam.d/sshd</tt> file. Remove all entries and replace them with:

auth required pam_env.so
auth required pam_unix2.so
auth required pam_nologin.so
account required pam_unix2.so
password required pam_pwcheck.so nullok
password required pam_unix2.so nullok use_first_pass use_authtok
session required pam_limits.so
session required pam_unix2.so

{{NOTE|These entries are what common-auth normally does. Since we've changed common-auth around for bioapi, these need to be specified manually. -Ransak}}

----

You can do some useful testing with [http://pamtester.sourceforge.net/ {{cmd|pamtester|}}], which calls the pam modules as if it were a program of your choice. Examples:
:{{cmdroot|pamtester xdm yourusername authenticate}}
:{{cmduser|pamtester xscreensaver yourusername authenticate}}
where {{cmd|yourusername|}} is your username. Note that {{cmd|pamtester|}} should run as root if and only if the program in question does.

===Application support===
The implementation of fingerprint scanning support in the relevant applications varies.

Here is the behaviour of the most common ones:
* In gdm enter your username and there should pop up an (ugly) image to swipe your finger and... magic - you can login without a password.
* kdm doesn't give any visual indication, other than that the cursor stops blinking. Just swipe your finger and hope it lets you log in.
* In xdm, enter your username and a blank password, then swipe (there is no popup as well). Identification support for xdm can be achieved with [http://www.nax.cz/pub/bioapi/2005/xdm/xdm_bio.patch this patch].
* The KDE screen saver in SUSE 10 requires you to enter an empty password (or select the correct user and then enter an empty password) in order to get the fingerprint prompt.
* For Fedora users, the redhat-config tools will crash if no root.bir presents. Also, there won't be any visual idication unless X server is properly configured for root to access. Just swipe your finger when the HDD stopped blinking or issue the following command in advance:
:{{cmduser|xhost +local:}}
* For RHEL4 users gdm, console (virtual terminal) logins and the xscreensaver all work

===kdm support===
To add graphical popup to kdm, you need following:
* Patch for pam_bioapi. This patch adds third parameter to {{path|pam_bioapi.so}} module, which is a name of file with additional environment variables that will be supplied to the UPEK driver.
:{{cmdroot|wget http://upir.cz/linux/patches/pam_bioapi-0.2.1-alter-environ.patch}}
:{{cmdroot|patch -p1 < pam_bioapi-0.2.1-alter-environ.patch}}
* Edit your {{path|Xsetup}} file (on SUSE 10 it's {{path|/etc/X11/xdm/Xsetup}}) and add these lines:
echo "XAUTHORITY=$XAUTHORITY" > /var/lib/xdm/kdm_env
echo "DISPLAY=$DISPLAY" >> /var/lib/xdm/kdm_env
* In {{path|/etc/pam.d/xdm}} file, add {{path|/var/lib/xdm/kdm_env}} as a third parameter for {{path|pam_bioapi.so}} module:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/xdm/kdm_env
* On Ubuntu simply do:
echo "DISPLAY=$DISPLAY" >> /var/lib/kdm/kdm_env
* If you have created /etc/pam.d/bioapi then modify:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/kdm/kdm_env

Please note, that this won't work if you have more than one Xserver.

==Make xscreensaver use the scanner==
If you are using Gentoo, you can get a portage overlay with the necessary patches here: http://www.zzamboni.org/brt/files/xscreensaver-fingerprint-overlay.tar.gz
*Get the needed xscreensaver sources:
:{{cmduser|wget http://www.jwz.org/xscreensaver/xscreensaver-4.23.tar.gz}}
:{{cmduser|tar xzf xscreensaver-4.23.tar.gz}}
:{{cmduser|cd xscreensaver-4.23}}
:{{cmduser|wget http://www.nax.cz/pub/bioapi/2005/xscreensaver/xscreensaver-4.22_alternativeAuth.diff mirror: http://zepan.org/files/xscreensaver-4.22_alternativeAuth.diff For xscreensaver 5.00, you can get a patch here: http://www.zzamboni.org/brt/files/xscreensaver-5.00-alternativeauth.patch}}
*After reviewing the patch (it's small and straightforward), do
:{{cmduser|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 <tt>pam</tt> and <tt>pam_bioapi</tt>. It should apply with some offset, don't mind that. If it says something about rejected though, then there's a problem.
*Compile with
:{{cmduser|./configure --with-pam && make}} 
*If you receive an error like "Couldn't find X11 headers/libs" and are running a Debian-like system, try "apt-get install xlibs-dev"
*If you receive an error like "undefined reference to `XmuPrintDefaultErrorMessage'" then install the libxmu-dev package and run the previous line again and then install as root with
:{{cmduser|su -c make install}} .
*Make sure that the newly compiled xscreensaver is used:
:{{cmduser|which xscreensaver}} should return
:{{cmdresult|/usr/local/bin/xscreensaver}} .
*In case it doesn't, try adjusting your PATH.

==Common problems==
===Bioapi error #3===
This is sometimes caused by improper permissions. The full error message is "BioAPI Error Code: 3 (0x3)".

However, at least on Gentoo, recent upgrades to glibc and gcc 4.1.1 caused Bioapi to break down due to some sort of incompatibility with bioapi registry. Reinstalling does '''not''' repair the issue automatically. However, you can still fix the issue manually, by removing /var/bioapi. You need to reinstall tfm-fingerprint driver after reinstalling bioapi so that the driver is properly re-registered. As root, type

:{{cmdroot|emerge -C bioapi}}
:{{cmdroot|rm -rf /var/bioapi}}
:{{cmdroot|emerge -av1 bioapi tfm-fingerprint}}

How to enable integrated fingerprint reader with BioAPI

2009-01-10T06:32:29Z

Dpward: /* Installing from source */ Cleaned up details about patching

{| width="100%"
|style="vertical-align:top;padding-right:20px;width:10px;white-space:nowrap;" | __TOC__
|style="vertical-align:top" |
This page describes the process of getting the [[Integrated Fingerprint Reader|integrated fingerprint reader]] to work under Linux, using bioapi and binary-only drivers. It is based on experiences in {{Ubuntu}} on a T43. The same works on {{Fedora}} 4 and 5, RHEL4, SuSE 9.3, SuSE 10, and {{Gentoo}}. Note that experimental open-source driver is available, see [[How to enable the fingerprint reader with ThinkFinger|the apropriate page]] for details.
|}

==Basic installation==
===Installing the bioapi framework===
====Automated installation script====
The [[Script for enabling the fingerprint reader]] automates the installation of most components (bioapi framework, driver, pam_bioapi, pam setup, device permissions, pamtester and enrolling), for some Linux distributions.

====Binary packages====

Note that these packages only take care of this one section. If you can use one, you should do so and then proceed to the section entitled, Installing and Configuring the Driver.

=====Debian/ Ubuntu Dapper=====
*If you're using {{Debian}} Sid (the unstable branch) or {{Ubuntu}} Dapper Drake 6.06 LTS you can try the packages from Michael R. Crusoe's site, either [http://www.qrivy.net/~michael/temp/ version 1.2.3] (recommended) or [http://www.qrivy.net/~michael/debs/unstable/ older versions] which might not work with the steps in this howto.

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

=====Gentoo=====
Gentoo now includes needed ebuilds. Just run

''ACCEPT_KEYWORDS=~x86 emerge pam_bioapi''

You can also grab the [http://www.qrivy.net/~michael/blua/bioapi/bioapi-1.2.2.ebuild.tar.bz2 ebuild], or use the source-install procedure below.

Also see [http://toe.ch/~tsa/ibm-fingerprint/ http://toe.ch/~tsa/ibm-fingerprint/] for alternative documentation on installing on Gentoo including ebuilds for all the packages used.

=====Fedora Core=====
RPM packages for Fedora Core and installation instructions are available [[Installing Fedora Core 5 on a ThinkPad X41 Tablet#Fingerprint_Reader|here]]

====Installing from source====
{{HINT|
For ubuntu (Gutsy) you'll need at least the:
build-essential
automake
packages, or building will fail.
}}
*Get the bioapi source:
:{{cmduser|wget http://bioapi-linux.googlecode.com/files/bioapi_1.2.3.tar.gz}}
*I could not compile bioapi with the graphical Qt tools. To do it manually, do the following:
:{{cmduser|tar xzf bioapi_1.2.3.tar.gz}}
:{{cmduser|cd bioapi-1.2.3}}
:{{cmduser|1=./configure --with-Qt-dir=no}}
:{{cmduser|make}}
:and then as root
:{{cmdroot|make install}}
:If make install fails, be sure you're root and then:
:{{cmdroot|1=export LD_LIBRARY_PATH=/usr/local/lib}}
:{{cmdroot|make install}}
:and if you want to compile [http://code.google.com/p/pam-bioapi/ pam_bioapi] for auth later
:{{cmdroot|cp include/bioapi_util.h include/installdefs.h imports/cdsa/v2_0/inc/cssmtype.h /usr/include}}
:Be aware that checkinstall will not work!
:(I got through configure with Qt, but got a cryptic build error. It all worked fine with Qt disabled as above)
:buzz: This is due to a wrong qt include path, set it manually in configure and everything should work.
:sbarre: I got it to work by doing the following quick hack :
:->in the configure script, line 25975, there is clearly a bug (specify a directory instead of a library), thus I replaced the
'-l$bnv_qt_lib_dir' with a '-L$bnv_qt_lib_dir'
:-> At the same lines, the $LIBS suffers from a misconstruction (I obtained a -l without anything after, which causes an error from gcc). I think the problems comes from the design of the script : if we do something like $LIBS=$LIBS -l$something. We MUST be sure that $something is defined. Since I have no time to fully debug it, I completely replaced the line 25975 with the libraries that worked for my system (probably quite current in fact) :
bnv_qt_LIBS="-L$bnv_qt_lib_dir -lqt-mt -lSM -lICE -lX11 -lXext -lXmu -lXt -lXi"
:-> This should make configure to work. Then, when typing 'make', the configure script is regenerated, thus you should also update the m4 script that is responsible for those problems : in file m4/bnv_have_qt.m4, change line 106 with :
:QT_LIBS="-lqt-mt -lSM -lICE -lX11 -lXext -lXmu -lXt -lXi"
* Bioapi version 1.2.2 needs to be patched to compile with GCC 4. See:
:http://upir.cz/linux/patches/bioapi-1.2.2-gcc4.patch
:http://cvs.pld-linux.org/cgi-bin/cvsweb/SOURCES/Attic/bioapi-c++.patch?rev=1.3

* By default, bioapi will install numerous files in {{path|/usr/local/<nowiki>{</nowiki>bin,lib,include<nowiki>}</nowiki>}}, including files with "self-explanatory" names such as {{path|/usr/local/bin/Sample}}. To prevent this pollution:
:Create a dedicated directory, for example {{path|/opt/bioapi}} .
:Append <tt>--prefix=/opt/bioapi</tt> to the above <tt>./configure</tt> command.
:Append {{path|/opt/bioapi/bin}} to <tt>$PATH</tt> and {{path|/opt/bioapi/lib}} to <tt>$LD_LIBRARY_PATH</tt>.
:When installing the driver (below), tell it the new install path: {{cmdroot|sh install.sh /opt/bioapi/lib}}

====Adjusting ldconfigs library search path====
At least on {{Fedora}} or {{Aurox}} 11, you may need to add {{path|/usr/local/lib}} to the library path so that the libraries referenced from <tt>pam_bioapi.so</tt> get picked up properly. The usual way to do this is adding it to the ldconfig configuration:
:{{cmdroot|echo '/usr/local/lib' > /etc/ld.so.conf.d/bioapi.conf}}
:{{cmdroot|ldconfig}}
Alternatively you can add it to the LD_LIBRARY variable.

If you see bioapi libs in the output of
:{{cmdroot|ldconfig -p | grep bioapi}}
then it should work.

===Installing and configuring the driver===
====Installing the driver====
*Download {{path|TFMESS_BSP_LIN_1.0.zip}} from the [http://www.upek.com/support/dl_linux_bsp.asp UPEK support site] and unzip it into a seperate folder, as it will not create one.
*Change to that folder and do as root:
:{{cmdroot|sh install.sh}}
:If you're running Gentoo, Debian or Ubuntu Dapper, use
:{{cmdroot|sh install.sh /usr/lib}}
{{HINT|
For me it didn't work this way, but following did:
:sh install.sh /usr/local/lib
greetings, tec}}
{{HINT|On my debian install I had to "cp libtfmessbsp.so /usr/lib" to avoid a errormessage during "sh install.sh /usr/lib": "Could not find file:/usr/lib/libtfmessbsp.so"}}
:If that fails, it may be that make install failed up above -- try setting LD_LIBRARY_PATH, do the make install again, and come back here and try this again. You also need {{cmd|mod_install|}} from bioapi in your PATH.
:May there still occures and error, which means mod_install: command not found.
:Then login as root - not su!
:Do this:
:{{cmdroot|sh install.sh}}
:again. It should work. SU to root does not work since then the /usr/local/bin directory is not used per default.

====Configuring permissions for non-root use====
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), you may need to do all or at least some of the things in this section. More details on what is necessary on which distributions would be greately appreciated.
*Create two groups, one for access to BioAPI files and the other for access to the usb files. (This is done for full generality; i.e., you may have other USB devices which you want accessable to other users, without exposing your BioAPI configuration to them). Add your normal user (the one you wish to use PAM-aware applications with) to both of these groups.
On {{Debian}} this is done with
:{{cmdroot|addgroup --system bioapi}}
:{{cmdroot|addgroup --system usbfs}}
:{{cmdroot|adduser yournormaluser bioapi}}
:{{cmdroot|adduser yournormaluser usbfs}}
On {{SUSE}} this is done with
:{{cmdroot|groupadd --system bioapi}}
:{{cmdroot|groupadd --system usbfs}}
:{{cmdroot|groupmod -A yournormaluser bioapi}}
:{{cmdroot|groupmod -A yournormaluser usbfs}}
On {{Mandriva}} this is done with
:{{cmdroot|groupadd -r bioapi}}
:{{cmdroot|groupadd -r usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}
On {{Fedora}} this is done with
:{{cmdroot|groupadd bioapi}}
:{{cmdroot|groupadd usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}

:(where {{cmd|yournormaluser|}} is your normal user name). You will need to log out and log back in for this to take effect.
*Set permissions on the BioAPI config/registry directory:
:{{cmdroot|chown -R root:bioapi /usr/local/var/bioapi/}}
:{{cmdroot|chmod -R 770 /usr/local/var/bioapi/}}
:(change this path if you used an alternate BioAPI install directory above)
*Set permissions on the files in {{path|/proc/bus/usb}}:
:{{cmdroot|chown -R root:usbfs /proc/bus/usb}}
:{{cmdroot|chmod -R g+X /proc/bus/usb}}
:{{cmdroot|chown root:usbfs /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:{{cmdroot|chmod 660 /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:You may need to replace {{cmd|lsusb|}} with its full path, which is something like {{cmd|/sbin/lsusb|}} or {{cmd|/usr/bin/lsusb|}} depending on your distro. It might be necessary to put these lines into a script which is run at startup and resume from suspend/hibernate.
In {{Fedora}} {{cmd|lsusb|}} is not installed by default. To intall it just type:
:{{cmdroot|yum install usbutils}}

*As an alternative to the {{cmd|chown|}}/{{cmd|chmod|}} commands above, you can set mount options for usbfs with a line in {{path|/etc/fstab|}}; an example would be
none /proc/bus/usb usbfs defaults,devgid=108,devmode=0660,busgid=108,busmode=0770,listgid=108,listmode=0660 0 0
:where 108 is replaced with the numerical group ID of the usbfs group (you can determine this with something like {{cmd|cat /etc/group <nowiki>|</nowiki> grep usbfs <nowiki>|</nowiki> cut -d':' -f 3|}}). Make sure you only have one {{path|/proc/bus/usb}} entry in {{path|/etc/fstab}}. See the {{cmd|mount(8)|}} manpage for more information on these options. This is "cleaner" but seems to have a few weird issues -- see the talk page for details.
*You may also have files in {{path|/dev/bus/usb}}, which the driver will try before {{path|/proc/bus/usb}}. If this is another usbfs mount point ({{cmd|mount|}} shows a line containing {{cmdresult|/dev/bus/usb type usbfs}}), then simply follow the above instructions with {{path|/dev/bus/usb}} rather than {{path|/proc/bus/usb}}. Otherwise, you may be running a new kernel (i.e. 2.6.15) that makes usbfs-like files available through {{path|/dev/bus/usb}}.
*On systems running udev these files are dynamically created; you can configure their permissions by editing a udev config file. On Debian this is done by changing the <tt>usb_device</tt> line of {{path|/etc/udev/permissions.rules}} to read
SUBSYSTEM=="usb_device", MODE="0660", GROUP="usbfs"
*For the beta versions only, there is a logfile, which needs to exist with the proper permissions:
:{{cmdroot|touch /var/log/BSP.log && chown root:bioapi /var/log/BSP.log && chmod 660 /var/log/BSP.log}}

====Miscellaneous configuration====
* To increase the security level (minimize false accept rate), set this in {{path|/etc/tfmessbsp.cfg}}:
security-level="5"
{{WARN|Please see discussion section Security Level!}}

===Testing the driver and enrolling a fingerprint===
To test the driver and generate the file containing your fingerprint information, you need a sample program included with the driver. The compilation steps below were discovered by trial and error; if they don't work for you, try the binary {{cmd|Sample|}} utility that came with the beta versions of the driver (i.e., {{path|TFMESS_BSP_LIN_1.0beta2.zip}} as mentioned above).
Go to the folder where you extracted {{path|TFMESS_BSP_LIN_1.0.zip}} and do:
:{{cmdroot|cd NonGUI_Sample}}
:Edit {{path|main.c|}} and remove (or comment out) the line
#include "port/bioapi_port.h"
:then add the line
#include <stdlib.h>
:{{cmdroot|gcc -o Sample main.c -L/usr/local/lib -lbioapi100 -DUNIX -DLITTLE_ENDIAN}}
:{{cmdroot|./Sample}}
:Note that Sample may only run as root, unless you've already configured the usbfs file permissions.
:You can try to "e"nroll (to record a fingerprint for an account) and then "v"erify (to test a fingerprint against the one it expects for an account).
:You'll save a step later if you use your own login username as the username to enroll here.
:If running {{cmd |./Sample|}} produces the error message 'BioAPI_ModuleLoad failed, BioAPI Error Code: 6477 (0x194d)'
:then uncommenting the line
://BioAPI_SetGUICallbacks(gModuleHandle, NULL, NULL,TextGuiCallback, NULL);
:in {{path|main.c|}} can help.

==Login via pam_bioapi==

The following explains how to add fingerprint authentiation to programs that use the PAM (Pluggable Authentication Modules) framework, such as Gnome's GDM and KDE's KDM and screensaver.

===Getting required libs & tools===
====Installing pam_bioapi====
*Prerequisites
:On SuSE 10, I needed to install the pam-devel RPM
:In general, you will need pam itself (standard for most distros) as well as the pam development files (probably an optional package for your distro).
*Get and compile the pam_bioapi module.
{{HINT|A new version, pam_bioapi 0.3.0, with multi-finger and identification support can be found [http://www.nax.cz/pub/bioapi/pam_bioapi/pam-bioapi_0.3.0.tar.gz here].
There's work in progress. pam_bioapi and biometrics-manager can be downloaded [http://download.savannah.gnu.org/releases/pam-bioapi/ here].}}
:{{cmduser|wget http://www.qrivy.net/~michael/blua/pam_bioapi/pam_bioapi-latest.tar.bz2}}
:{{cmduser|tar xjf pam_bioapi-latest.tar.bz2}}
:{{cmduser|cd pam_bioapi-0.2.1}}
:{{cmduser|wget http://badcode.de/downloads/fingerprint.patch}}
:{{cmduser|patch -p0 < fingerprint.patch}}
:If you want to, review the patch. In general you should review all code you download and compile, if possible.
:{{cmduser|<nowiki>./configure --libdir=/lib && make </nowiki>}}
:and as root
:{{cmdroot| make install}}
{{NOTE|If you get a 'rpl_malloc' error in /var/log/auth.log when trying to use the fingerprint reader, redo these steps and remove the related term from Makefile after running ./configure. (FC3, Debian etch)}}
*If you get 'configure: error: cannot find required header: security/_pam_macros.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again. If you are using a Mandriva distribution, do "urpmi libpam0-devel" instead.
*If you get 'configure: error: cannot find required header: security/pam_modules.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again.
*If you get 'configure: error: cannot find required header: sqlite3.h' and are on a Debian-like system, do "apt-get install libsqlite3-dev" and try again.
*If you get 'make: msgfmt: command not found' and are on a Debian-like system, do "apt-get install gettext" and try again.
*If you get 'PAM [dlerror: /lib/security/pam_bioapi.so: undefined symbol: BioAPIMemoryFuncs]' error in your syslog, replace 'LIBS = ' line in {{path|libpam_bioapi/makefile}} with the following (of course, replace {{path|/opt/bioapi/}} with the path where you installed bioapi):
LIBS = -L/opt/bioapi/lib -lbioapi100 -lbioapi_mds300 -lmds_util
*Use the sample tool from the fingerprint reader to create {{path|<username>.bir}} (<tt><username></tt> '''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:
:{{cmdroot|SERIAL<nowiki>=`BioAPITest | sed -ne "/Fingerprint/{n;n;s/^.*: $.\{9\}$$.\{4\}$$.\{4\}$$.\{4\}$$.*$/\1-\2-\3-\4-\5/gp}"` </nowiki>}}
:{{cmdroot|echo $SERIAL}} should print something like {{cmdresult|<nowiki>{5550454b-2054-464d-2f45-535320425350}</nowiki>}} now.
:If it does, do:
:{{cmdroot|mkdir -p /etc/bioapi/pam/$SERIAL}}
:{{cmdroot|cp <username>.bir /etc/bioapi/pam/$SERIAL}}
:If not, you might just try
:{{cmdroot|SERIAL<nowiki>={5550454b-2054-464d-2f45-535320425350}</nowiki>}}
:as this value is hardcoded into the UPEK docs.

===Configuring pam===
The following part is distribution specific. On {{Ubuntu}} or {{SUSE}} you can modify {{path|/etc/pam.d/common-auth}} (on {{Gentoo}} and {{Fedora}} it is {{path|/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/bioapi/pam/
password sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_unix.so nullok_secure

----
For '''Gentoo'''-Users - this allows you to attempt a password first. If you simply press enter, it then prompts for a fingerprints. Create a file named {{path|/etc/pam.d/bioapi}}. This also means that remote services, such as SSH keep working:

auth required pam_env.so
auth sufficient pam_unix.so likeauth nullok
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_deny.so

account required pam_unix.so

session required pam_limits.so
session required pam_unix.so

----

Now, simply replace "auth include system-auth" in all services that you wish to use fingerprint for with "auth include bioapi". For example, {{path|/etc/pam.d/kde}} by default contains

auth include system-auth
auth required pam_nologin.so

account include system-auth

password include system-auth

session include system-auth

Simply replace the first "system-auth" with bioapi and you can also get rid of KDE desktop lock with a fingerprint. If you do not wish to allow for "password fallback" then remove

auth sufficient pam_unix.so likeauth nullok

from {{path|/etc/pam.d/bioapi}}.

{{WARN|If su/sudo expects to receive the root password (SuSE 10), you need to have fingerprint settings for root (that is, copy in a root.bir as well as a your-username.bir). Otherwise, they get a segmentation fault. Which is a little unfortunate, given that you need to su or sudo to change your settings... }}
{{WARN|Not only SuSE 10 requires root.bir to be available for su to work. Just make sure you have root.bir when su is not working with your fingerprint reader but other applications are...}}
Note that sshd may pick up the fingerprint settings from {{path|/etc/pam.d/common-auth}}. I didn't want that, so I removed the "auth include common-auth" line from {{path|/etc/pam.d/sshd}} and replaced it with the lines that were originally in my {{path|/etc/pam.d/common-auth}}. That way most local services use the fingerprint reader, but sshd does not.

{{NOTE|su/sudo will call for your fingerprint even if you are remote via ssh. Pressing *CTLR-c* (or closing graphic window) will allow you the desired password option.}}

Another way to do this is to create a file ({{path|/etc/pam.d/bioapi|}} for example) which contains the {{cmd|pam_bioapi.so|}} lines, and explicitly {{cmd|@include|}} this '''before''' {{path|/etc/pam.d/common-auth|}} in the files for services which should use the fingerprint reader. In this case you should leave {{path|/etc/pam.d/common-auth|}} alone.

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

In {{Fedora}} the original 'session' terms in {{path|/etc/pam.d/system-auth}} need to be kept.

{{HINT|The setup described above will/could affect remote ssh logins to also use biometric logins, which is a bit silly (who wants to remote ssh to the laptop, and then have to walk over to it and swipe your finger) To avoid that you can copy the default <tt>/etc/pam.d/system-auth</tt> to <tt>/etc/pam.d/sshd</tt> which will allow the sshd service to use the standard authentication procedure.}}

----

To enable normal password authorization to work with remote SSH in {{SUSE}} 10.3, edit the <tt>/etc/pam.d/sshd</tt> file. Remove all entries and replace them with:

auth required pam_env.so
auth required pam_unix2.so
auth required pam_nologin.so
account required pam_unix2.so
password required pam_pwcheck.so nullok
password required pam_unix2.so nullok use_first_pass use_authtok
session required pam_limits.so
session required pam_unix2.so

{{NOTE|These entries are what common-auth normally does. Since we've changed common-auth around for bioapi, these need to be specified manually. -Ransak}}

----

You can do some useful testing with [http://pamtester.sourceforge.net/ {{cmd|pamtester|}}], which calls the pam modules as if it were a program of your choice. Examples:
:{{cmdroot|pamtester xdm yourusername authenticate}}
:{{cmduser|pamtester xscreensaver yourusername authenticate}}
where {{cmd|yourusername|}} is your username. Note that {{cmd|pamtester|}} should run as root if and only if the program in question does.

===Application support===
The implementation of fingerprint scanning support in the relevant applications varies.

Here is the behaviour of the most common ones:
* In gdm enter your username and there should pop up an (ugly) image to swipe your finger and... magic - you can login without a password.
* kdm doesn't give any visual indication, other than that the cursor stops blinking. Just swipe your finger and hope it lets you log in.
* In xdm, enter your username and a blank password, then swipe (there is no popup as well). Identification support for xdm can be achieved with [http://www.nax.cz/pub/bioapi/2005/xdm/xdm_bio.patch this patch].
* The KDE screen saver in SUSE 10 requires you to enter an empty password (or select the correct user and then enter an empty password) in order to get the fingerprint prompt.
* For Fedora users, the redhat-config tools will crash if no root.bir presents. Also, there won't be any visual idication unless X server is properly configured for root to access. Just swipe your finger when the HDD stopped blinking or issue the following command in advance:
:{{cmduser|xhost +local:}}
* For RHEL4 users gdm, console (virtual terminal) logins and the xscreensaver all work

===kdm support===
To add graphical popup to kdm, you need following:
* Patch for pam_bioapi. This patch adds third parameter to {{path|pam_bioapi.so}} module, which is a name of file with additional environment variables that will be supplied to the UPEK driver.
:{{cmdroot|wget http://upir.cz/linux/patches/pam_bioapi-0.2.1-alter-environ.patch}}
:{{cmdroot|patch -p1 < pam_bioapi-0.2.1-alter-environ.patch}}
* Edit your {{path|Xsetup}} file (on SUSE 10 it's {{path|/etc/X11/xdm/Xsetup}}) and add these lines:
echo "XAUTHORITY=$XAUTHORITY" > /var/lib/xdm/kdm_env
echo "DISPLAY=$DISPLAY" >> /var/lib/xdm/kdm_env
* In {{path|/etc/pam.d/xdm}} file, add {{path|/var/lib/xdm/kdm_env}} as a third parameter for {{path|pam_bioapi.so}} module:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/xdm/kdm_env
* On Ubuntu simply do:
echo "DISPLAY=$DISPLAY" >> /var/lib/kdm/kdm_env
* If you have created /etc/pam.d/bioapi then modify:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/kdm/kdm_env

Please note, that this won't work if you have more than one Xserver.

==Make xscreensaver use the scanner==
If you are using Gentoo, you can get a portage overlay with the necessary patches here: http://www.zzamboni.org/brt/files/xscreensaver-fingerprint-overlay.tar.gz
*Get the needed xscreensaver sources:
:{{cmduser|wget http://www.jwz.org/xscreensaver/xscreensaver-4.23.tar.gz}}
:{{cmduser|tar xzf xscreensaver-4.23.tar.gz}}
:{{cmduser|cd xscreensaver-4.23}}
:{{cmduser|wget http://www.nax.cz/pub/bioapi/2005/xscreensaver/xscreensaver-4.22_alternativeAuth.diff mirror: http://zepan.org/files/xscreensaver-4.22_alternativeAuth.diff For xscreensaver 5.00, you can get a patch here: http://www.zzamboni.org/brt/files/xscreensaver-5.00-alternativeauth.patch}}
*After reviewing the patch (it's small and straightforward), do
:{{cmduser|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 <tt>pam</tt> and <tt>pam_bioapi</tt>. It should apply with some offset, don't mind that. If it says something about rejected though, then there's a problem.
*Compile with
:{{cmduser|./configure --with-pam && make}} 
*If you receive an error like "Couldn't find X11 headers/libs" and are running a Debian-like system, try "apt-get install xlibs-dev"
*If you receive an error like "undefined reference to `XmuPrintDefaultErrorMessage'" then install the libxmu-dev package and run the previous line again and then install as root with
:{{cmduser|su -c make install}} .
*Make sure that the newly compiled xscreensaver is used:
:{{cmduser|which xscreensaver}} should return
:{{cmdresult|/usr/local/bin/xscreensaver}} .
*In case it doesn't, try adjusting your PATH.

==Common problems==
===Bioapi error #3===
This is sometimes caused by improper permissions. The full error message is "BioAPI Error Code: 3 (0x3)".

However, at least on Gentoo, recent upgrades to glibc and gcc 4.1.1 caused Bioapi to break down due to some sort of incompatibility with bioapi registry. Reinstalling does '''not''' repair the issue automatically. However, you can still fix the issue manually, by removing /var/bioapi. You need to reinstall tfm-fingerprint driver after reinstalling bioapi so that the driver is properly re-registered. As root, type

:{{cmdroot|emerge -C bioapi}}
:{{cmdroot|rm -rf /var/bioapi}}
:{{cmdroot|emerge -av1 bioapi tfm-fingerprint}}

How to enable integrated fingerprint reader with BioAPI

2009-01-10T04:43:21Z

Dpward: /* Installing from source */ Updated link to bioapi-c++.patch

{| width="100%"
|style="vertical-align:top;padding-right:20px;width:10px;white-space:nowrap;" | __TOC__
|style="vertical-align:top" |
This page describes the process of getting the [[Integrated Fingerprint Reader|integrated fingerprint reader]] to work under Linux, using bioapi and binary-only drivers. It is based on experiences in {{Ubuntu}} on a T43. The same works on {{Fedora}} 4 and 5, RHEL4, SuSE 9.3, SuSE 10, and {{Gentoo}}. Note that experimental open-source driver is available, see [[How to enable the fingerprint reader with ThinkFinger|the apropriate page]] for details.
|}

==Basic installation==
===Installing the bioapi framework===
====Automated installation script====
The [[Script for enabling the fingerprint reader]] automates the installation of most components (bioapi framework, driver, pam_bioapi, pam setup, device permissions, pamtester and enrolling), for some Linux distributions.

====Binary packages====

Note that these packages only take care of this one section. If you can use one, you should do so and then proceed to the section entitled, Installing and Configuring the Driver.

=====Debian/ Ubuntu Dapper=====
*If you're using {{Debian}} Sid (the unstable branch) or {{Ubuntu}} Dapper Drake 6.06 LTS you can try the packages from Michael R. Crusoe's site, either [http://www.qrivy.net/~michael/temp/ version 1.2.3] (recommended) or [http://www.qrivy.net/~michael/debs/unstable/ older versions] which might not work with the steps in this howto.

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

=====Gentoo=====
Gentoo now includes needed ebuilds. Just run

''ACCEPT_KEYWORDS=~x86 emerge pam_bioapi''

You can also grab the [http://www.qrivy.net/~michael/blua/bioapi/bioapi-1.2.2.ebuild.tar.bz2 ebuild], or use the source-install procedure below.

Also see [http://toe.ch/~tsa/ibm-fingerprint/ http://toe.ch/~tsa/ibm-fingerprint/] for alternative documentation on installing on Gentoo including ebuilds for all the packages used.

=====Fedora Core=====
RPM packages for Fedora Core and installation instructions are available [[Installing Fedora Core 5 on a ThinkPad X41 Tablet#Fingerprint_Reader|here]]

====Installing from source====
{{HINT|
For ubuntu (Gutsy) you'll need at least the:
build-essential
automake
packages, or building will fail.
}}
*Get the bioapi source:
:{{cmduser|wget http://bioapi-linux.googlecode.com/files/bioapi_1.2.3.tar.gz}}
*I could not compile bioapi with the graphical Qt tools. To do it manually, do the following:
:{{cmduser|tar xzf bioapi_1.2.3.tar.gz}}
:{{cmduser|cd bioapi-1.2.3}}
:{{cmduser|1=./configure --with-Qt-dir=no}}
:{{cmduser|make}}
:and then as root
:{{cmdroot|make install}}
:If make install fails, be sure you're root and then:
:{{cmdroot|1=export LD_LIBRARY_PATH=/usr/local/lib}}
:{{cmdroot|make install}}
:and if you want to compile [http://code.google.com/p/pam-bioapi/ pam_bioapi] for auth later
:{{cmdroot|cp include/bioapi_util.h include/installdefs.h imports/cdsa/v2_0/inc/cssmtype.h /usr/include}}
:Be aware that checkinstall will not work!
:(I got through configure with Qt, but got a cryptic build error. It all worked fine with Qt disabled as above)
:buzz: This is due to a wrong qt include path, set it manually in configure and everything should work.
:sbarre: I got it to work by doing the following quick hack :
:->in the configure script, line 25975, there is clearly a bug (specify a directory instead of a library), thus I replaced the
'-l$bnv_qt_lib_dir' with a '-L$bnv_qt_lib_dir'
:-> At the same lines, the $LIBS suffers from a misconstruction (I obtained a -l without anything after, which causes an error from gcc). I think the problems comes from the design of the script : if we do something like $LIBS=$LIBS -l$something. We MUST be sure that $something is defined. Since I have no time to fully debug it, I completely replaced the line 25975 with the libraries that worked for my system (probably quite current in fact) :
bnv_qt_LIBS="-L$bnv_qt_lib_dir -lqt-mt -lSM -lICE -lX11 -lXext -lXmu -lXt -lXi"
:-> This should make configure to work. Then, when typing 'make', the configure script is regenerated, thus you should also update the m4 script that is responsible for those problems : in file m4/bnv_have_qt.m4, change line 106 with :
:QT_LIBS="-lqt-mt -lSM -lICE -lX11 -lXext -lXmu -lXt -lXi"
*Bioapi (at least version 1.2.2) doesn't compile with GCC4. You need to patch it:
*This is neccessary to compile on SUSE 10.1 which it using gcc version 4.1.0.
:{{cmduser|wget http://upir.cz/linux/patches/bioapi-1.2.2-gcc4.patch}}
:{{cmduser|patch -p1 < bioapi-1.2.2-gcc4.patch}}
*Patch for gcc 4.1 is available here (but has been marked obsolete) - http://cvs.pld-linux.org/cgi-bin/cvsweb/SOURCES/Attic/bioapi-c++.patch?rev=1.3
* By default, bioapi will install numerous files in {{path|/usr/local/<nowiki>{</nowiki>bin,lib,include<nowiki>}</nowiki>}}, including files with "self-explanatory" names such as {{path|/usr/local/bin/Sample}}. To prevent this pollution:
:Create a dedicated directory, for example {{path|/opt/bioapi}} .
:Append <tt>--prefix=/opt/bioapi</tt> to the above <tt>./configure</tt> command.
:Append {{path|/opt/bioapi/bin}} to <tt>$PATH</tt> and {{path|/opt/bioapi/lib}} to <tt>$LD_LIBRARY_PATH</tt>.
:When installing the driver (below), tell it the new install path: {{cmdroot|sh install.sh /opt/bioapi/lib}}

====Adjusting ldconfigs library search path====
At least on {{Fedora}} or {{Aurox}} 11, you may need to add {{path|/usr/local/lib}} to the library path so that the libraries referenced from <tt>pam_bioapi.so</tt> get picked up properly. The usual way to do this is adding it to the ldconfig configuration:
:{{cmdroot|echo '/usr/local/lib' > /etc/ld.so.conf.d/bioapi.conf}}
:{{cmdroot|ldconfig}}
Alternatively you can add it to the LD_LIBRARY variable.

If you see bioapi libs in the output of
:{{cmdroot|ldconfig -p | grep bioapi}}
then it should work.

===Installing and configuring the driver===
====Installing the driver====
*Download {{path|TFMESS_BSP_LIN_1.0.zip}} from the [http://www.upek.com/support/dl_linux_bsp.asp UPEK support site] and unzip it into a seperate folder, as it will not create one.
*Change to that folder and do as root:
:{{cmdroot|sh install.sh}}
:If you're running Gentoo, Debian or Ubuntu Dapper, use
:{{cmdroot|sh install.sh /usr/lib}}
{{HINT|
For me it didn't work this way, but following did:
:sh install.sh /usr/local/lib
greetings, tec}}
{{HINT|On my debian install I had to "cp libtfmessbsp.so /usr/lib" to avoid a errormessage during "sh install.sh /usr/lib": "Could not find file:/usr/lib/libtfmessbsp.so"}}
:If that fails, it may be that make install failed up above -- try setting LD_LIBRARY_PATH, do the make install again, and come back here and try this again. You also need {{cmd|mod_install|}} from bioapi in your PATH.
:May there still occures and error, which means mod_install: command not found.
:Then login as root - not su!
:Do this:
:{{cmdroot|sh install.sh}}
:again. It should work. SU to root does not work since then the /usr/local/bin directory is not used per default.

====Configuring permissions for non-root use====
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), you may need to do all or at least some of the things in this section. More details on what is necessary on which distributions would be greately appreciated.
*Create two groups, one for access to BioAPI files and the other for access to the usb files. (This is done for full generality; i.e., you may have other USB devices which you want accessable to other users, without exposing your BioAPI configuration to them). Add your normal user (the one you wish to use PAM-aware applications with) to both of these groups.
On {{Debian}} this is done with
:{{cmdroot|addgroup --system bioapi}}
:{{cmdroot|addgroup --system usbfs}}
:{{cmdroot|adduser yournormaluser bioapi}}
:{{cmdroot|adduser yournormaluser usbfs}}
On {{SUSE}} this is done with
:{{cmdroot|groupadd --system bioapi}}
:{{cmdroot|groupadd --system usbfs}}
:{{cmdroot|groupmod -A yournormaluser bioapi}}
:{{cmdroot|groupmod -A yournormaluser usbfs}}
On {{Mandriva}} this is done with
:{{cmdroot|groupadd -r bioapi}}
:{{cmdroot|groupadd -r usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}
On {{Fedora}} this is done with
:{{cmdroot|groupadd bioapi}}
:{{cmdroot|groupadd usbfs}}
:{{cmdroot|usermod -G bioapi,usbfs yournormaluser}}

:(where {{cmd|yournormaluser|}} is your normal user name). You will need to log out and log back in for this to take effect.
*Set permissions on the BioAPI config/registry directory:
:{{cmdroot|chown -R root:bioapi /usr/local/var/bioapi/}}
:{{cmdroot|chmod -R 770 /usr/local/var/bioapi/}}
:(change this path if you used an alternate BioAPI install directory above)
*Set permissions on the files in {{path|/proc/bus/usb}}:
:{{cmdroot|chown -R root:usbfs /proc/bus/usb}}
:{{cmdroot|chmod -R g+X /proc/bus/usb}}
:{{cmdroot|chown root:usbfs /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:{{cmdroot|chmod 660 /proc/bus/usb/`lsusb <nowiki>|</nowiki> sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`}}
:You may need to replace {{cmd|lsusb|}} with its full path, which is something like {{cmd|/sbin/lsusb|}} or {{cmd|/usr/bin/lsusb|}} depending on your distro. It might be necessary to put these lines into a script which is run at startup and resume from suspend/hibernate.
In {{Fedora}} {{cmd|lsusb|}} is not installed by default. To intall it just type:
:{{cmdroot|yum install usbutils}}

*As an alternative to the {{cmd|chown|}}/{{cmd|chmod|}} commands above, you can set mount options for usbfs with a line in {{path|/etc/fstab|}}; an example would be
none /proc/bus/usb usbfs defaults,devgid=108,devmode=0660,busgid=108,busmode=0770,listgid=108,listmode=0660 0 0
:where 108 is replaced with the numerical group ID of the usbfs group (you can determine this with something like {{cmd|cat /etc/group <nowiki>|</nowiki> grep usbfs <nowiki>|</nowiki> cut -d':' -f 3|}}). Make sure you only have one {{path|/proc/bus/usb}} entry in {{path|/etc/fstab}}. See the {{cmd|mount(8)|}} manpage for more information on these options. This is "cleaner" but seems to have a few weird issues -- see the talk page for details.
*You may also have files in {{path|/dev/bus/usb}}, which the driver will try before {{path|/proc/bus/usb}}. If this is another usbfs mount point ({{cmd|mount|}} shows a line containing {{cmdresult|/dev/bus/usb type usbfs}}), then simply follow the above instructions with {{path|/dev/bus/usb}} rather than {{path|/proc/bus/usb}}. Otherwise, you may be running a new kernel (i.e. 2.6.15) that makes usbfs-like files available through {{path|/dev/bus/usb}}.
*On systems running udev these files are dynamically created; you can configure their permissions by editing a udev config file. On Debian this is done by changing the <tt>usb_device</tt> line of {{path|/etc/udev/permissions.rules}} to read
SUBSYSTEM=="usb_device", MODE="0660", GROUP="usbfs"
*For the beta versions only, there is a logfile, which needs to exist with the proper permissions:
:{{cmdroot|touch /var/log/BSP.log && chown root:bioapi /var/log/BSP.log && chmod 660 /var/log/BSP.log}}

====Miscellaneous configuration====
* To increase the security level (minimize false accept rate), set this in {{path|/etc/tfmessbsp.cfg}}:
security-level="5"
{{WARN|Please see discussion section Security Level!}}

===Testing the driver and enrolling a fingerprint===
To test the driver and generate the file containing your fingerprint information, you need a sample program included with the driver. The compilation steps below were discovered by trial and error; if they don't work for you, try the binary {{cmd|Sample|}} utility that came with the beta versions of the driver (i.e., {{path|TFMESS_BSP_LIN_1.0beta2.zip}} as mentioned above).
Go to the folder where you extracted {{path|TFMESS_BSP_LIN_1.0.zip}} and do:
:{{cmdroot|cd NonGUI_Sample}}
:Edit {{path|main.c|}} and remove (or comment out) the line
#include "port/bioapi_port.h"
:then add the line
#include <stdlib.h>
:{{cmdroot|gcc -o Sample main.c -L/usr/local/lib -lbioapi100 -DUNIX -DLITTLE_ENDIAN}}
:{{cmdroot|./Sample}}
:Note that Sample may only run as root, unless you've already configured the usbfs file permissions.
:You can try to "e"nroll (to record a fingerprint for an account) and then "v"erify (to test a fingerprint against the one it expects for an account).
:You'll save a step later if you use your own login username as the username to enroll here.
:If running {{cmd |./Sample|}} produces the error message 'BioAPI_ModuleLoad failed, BioAPI Error Code: 6477 (0x194d)'
:then uncommenting the line
://BioAPI_SetGUICallbacks(gModuleHandle, NULL, NULL,TextGuiCallback, NULL);
:in {{path|main.c|}} can help.

==Login via pam_bioapi==

The following explains how to add fingerprint authentiation to programs that use the PAM (Pluggable Authentication Modules) framework, such as Gnome's GDM and KDE's KDM and screensaver.

===Getting required libs & tools===
====Installing pam_bioapi====
*Prerequisites
:On SuSE 10, I needed to install the pam-devel RPM
:In general, you will need pam itself (standard for most distros) as well as the pam development files (probably an optional package for your distro).
*Get and compile the pam_bioapi module.
{{HINT|A new version, pam_bioapi 0.3.0, with multi-finger and identification support can be found [http://www.nax.cz/pub/bioapi/pam_bioapi/pam-bioapi_0.3.0.tar.gz here].
There's work in progress. pam_bioapi and biometrics-manager can be downloaded [http://download.savannah.gnu.org/releases/pam-bioapi/ here].}}
:{{cmduser|wget http://www.qrivy.net/~michael/blua/pam_bioapi/pam_bioapi-latest.tar.bz2}}
:{{cmduser|tar xjf pam_bioapi-latest.tar.bz2}}
:{{cmduser|cd pam_bioapi-0.2.1}}
:{{cmduser|wget http://badcode.de/downloads/fingerprint.patch}}
:{{cmduser|patch -p0 < fingerprint.patch}}
:If you want to, review the patch. In general you should review all code you download and compile, if possible.
:{{cmduser|<nowiki>./configure --libdir=/lib && make </nowiki>}}
:and as root
:{{cmdroot| make install}}
{{NOTE|If you get a 'rpl_malloc' error in /var/log/auth.log when trying to use the fingerprint reader, redo these steps and remove the related term from Makefile after running ./configure. (FC3, Debian etch)}}
*If you get 'configure: error: cannot find required header: security/_pam_macros.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again. If you are using a Mandriva distribution, do "urpmi libpam0-devel" instead.
*If you get 'configure: error: cannot find required header: security/pam_modules.h' and are on a Debian-like system, do "apt-get install libpam0g-dev" and try again.
*If you get 'configure: error: cannot find required header: sqlite3.h' and are on a Debian-like system, do "apt-get install libsqlite3-dev" and try again.
*If you get 'make: msgfmt: command not found' and are on a Debian-like system, do "apt-get install gettext" and try again.
*If you get 'PAM [dlerror: /lib/security/pam_bioapi.so: undefined symbol: BioAPIMemoryFuncs]' error in your syslog, replace 'LIBS = ' line in {{path|libpam_bioapi/makefile}} with the following (of course, replace {{path|/opt/bioapi/}} with the path where you installed bioapi):
LIBS = -L/opt/bioapi/lib -lbioapi100 -lbioapi_mds300 -lmds_util
*Use the sample tool from the fingerprint reader to create {{path|<username>.bir}} (<tt><username></tt> '''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:
:{{cmdroot|SERIAL<nowiki>=`BioAPITest | sed -ne "/Fingerprint/{n;n;s/^.*: $.\{9\}$$.\{4\}$$.\{4\}$$.\{4\}$$.*$/\1-\2-\3-\4-\5/gp}"` </nowiki>}}
:{{cmdroot|echo $SERIAL}} should print something like {{cmdresult|<nowiki>{5550454b-2054-464d-2f45-535320425350}</nowiki>}} now.
:If it does, do:
:{{cmdroot|mkdir -p /etc/bioapi/pam/$SERIAL}}
:{{cmdroot|cp <username>.bir /etc/bioapi/pam/$SERIAL}}
:If not, you might just try
:{{cmdroot|SERIAL<nowiki>={5550454b-2054-464d-2f45-535320425350}</nowiki>}}
:as this value is hardcoded into the UPEK docs.

===Configuring pam===
The following part is distribution specific. On {{Ubuntu}} or {{SUSE}} you can modify {{path|/etc/pam.d/common-auth}} (on {{Gentoo}} and {{Fedora}} it is {{path|/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/bioapi/pam/
password sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_unix.so nullok_secure

----
For '''Gentoo'''-Users - this allows you to attempt a password first. If you simply press enter, it then prompts for a fingerprints. Create a file named {{path|/etc/pam.d/bioapi}}. This also means that remote services, such as SSH keep working:

auth required pam_env.so
auth sufficient pam_unix.so likeauth nullok
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/
auth required pam_deny.so

account required pam_unix.so

session required pam_limits.so
session required pam_unix.so

----

Now, simply replace "auth include system-auth" in all services that you wish to use fingerprint for with "auth include bioapi". For example, {{path|/etc/pam.d/kde}} by default contains

auth include system-auth
auth required pam_nologin.so

account include system-auth

password include system-auth

session include system-auth

Simply replace the first "system-auth" with bioapi and you can also get rid of KDE desktop lock with a fingerprint. If you do not wish to allow for "password fallback" then remove

auth sufficient pam_unix.so likeauth nullok

from {{path|/etc/pam.d/bioapi}}.

{{WARN|If su/sudo expects to receive the root password (SuSE 10), you need to have fingerprint settings for root (that is, copy in a root.bir as well as a your-username.bir). Otherwise, they get a segmentation fault. Which is a little unfortunate, given that you need to su or sudo to change your settings... }}
{{WARN|Not only SuSE 10 requires root.bir to be available for su to work. Just make sure you have root.bir when su is not working with your fingerprint reader but other applications are...}}
Note that sshd may pick up the fingerprint settings from {{path|/etc/pam.d/common-auth}}. I didn't want that, so I removed the "auth include common-auth" line from {{path|/etc/pam.d/sshd}} and replaced it with the lines that were originally in my {{path|/etc/pam.d/common-auth}}. That way most local services use the fingerprint reader, but sshd does not.

{{NOTE|su/sudo will call for your fingerprint even if you are remote via ssh. Pressing *CTLR-c* (or closing graphic window) will allow you the desired password option.}}

Another way to do this is to create a file ({{path|/etc/pam.d/bioapi|}} for example) which contains the {{cmd|pam_bioapi.so|}} lines, and explicitly {{cmd|@include|}} this '''before''' {{path|/etc/pam.d/common-auth|}} in the files for services which should use the fingerprint reader. In this case you should leave {{path|/etc/pam.d/common-auth|}} alone.

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

In {{Fedora}} the original 'session' terms in {{path|/etc/pam.d/system-auth}} need to be kept.

{{HINT|The setup described above will/could affect remote ssh logins to also use biometric logins, which is a bit silly (who wants to remote ssh to the laptop, and then have to walk over to it and swipe your finger) To avoid that you can copy the default <tt>/etc/pam.d/system-auth</tt> to <tt>/etc/pam.d/sshd</tt> which will allow the sshd service to use the standard authentication procedure.}}

----

To enable normal password authorization to work with remote SSH in {{SUSE}} 10.3, edit the <tt>/etc/pam.d/sshd</tt> file. Remove all entries and replace them with:

auth required pam_env.so
auth required pam_unix2.so
auth required pam_nologin.so
account required pam_unix2.so
password required pam_pwcheck.so nullok
password required pam_unix2.so nullok use_first_pass use_authtok
session required pam_limits.so
session required pam_unix2.so

{{NOTE|These entries are what common-auth normally does. Since we've changed common-auth around for bioapi, these need to be specified manually. -Ransak}}

----

You can do some useful testing with [http://pamtester.sourceforge.net/ {{cmd|pamtester|}}], which calls the pam modules as if it were a program of your choice. Examples:
:{{cmdroot|pamtester xdm yourusername authenticate}}
:{{cmduser|pamtester xscreensaver yourusername authenticate}}
where {{cmd|yourusername|}} is your username. Note that {{cmd|pamtester|}} should run as root if and only if the program in question does.

===Application support===
The implementation of fingerprint scanning support in the relevant applications varies.

Here is the behaviour of the most common ones:
* In gdm enter your username and there should pop up an (ugly) image to swipe your finger and... magic - you can login without a password.
* kdm doesn't give any visual indication, other than that the cursor stops blinking. Just swipe your finger and hope it lets you log in.
* In xdm, enter your username and a blank password, then swipe (there is no popup as well). Identification support for xdm can be achieved with [http://www.nax.cz/pub/bioapi/2005/xdm/xdm_bio.patch this patch].
* The KDE screen saver in SUSE 10 requires you to enter an empty password (or select the correct user and then enter an empty password) in order to get the fingerprint prompt.
* For Fedora users, the redhat-config tools will crash if no root.bir presents. Also, there won't be any visual idication unless X server is properly configured for root to access. Just swipe your finger when the HDD stopped blinking or issue the following command in advance:
:{{cmduser|xhost +local:}}
* For RHEL4 users gdm, console (virtual terminal) logins and the xscreensaver all work

===kdm support===
To add graphical popup to kdm, you need following:
* Patch for pam_bioapi. This patch adds third parameter to {{path|pam_bioapi.so}} module, which is a name of file with additional environment variables that will be supplied to the UPEK driver.
:{{cmdroot|wget http://upir.cz/linux/patches/pam_bioapi-0.2.1-alter-environ.patch}}
:{{cmdroot|patch -p1 < pam_bioapi-0.2.1-alter-environ.patch}}
* Edit your {{path|Xsetup}} file (on SUSE 10 it's {{path|/etc/X11/xdm/Xsetup}}) and add these lines:
echo "XAUTHORITY=$XAUTHORITY" > /var/lib/xdm/kdm_env
echo "DISPLAY=$DISPLAY" >> /var/lib/xdm/kdm_env
* In {{path|/etc/pam.d/xdm}} file, add {{path|/var/lib/xdm/kdm_env}} as a third parameter for {{path|pam_bioapi.so}} module:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/xdm/kdm_env
* On Ubuntu simply do:
echo "DISPLAY=$DISPLAY" >> /var/lib/kdm/kdm_env
* If you have created /etc/pam.d/bioapi then modify:
auth sufficient pam_bioapi.so {5550454b-2054-464d-2f45-535320425350} /etc/bioapi/pam/ /var/lib/kdm/kdm_env

Please note, that this won't work if you have more than one Xserver.

==Make xscreensaver use the scanner==
If you are using Gentoo, you can get a portage overlay with the necessary patches here: http://www.zzamboni.org/brt/files/xscreensaver-fingerprint-overlay.tar.gz
*Get the needed xscreensaver sources:
:{{cmduser|wget http://www.jwz.org/xscreensaver/xscreensaver-4.23.tar.gz}}
:{{cmduser|tar xzf xscreensaver-4.23.tar.gz}}
:{{cmduser|cd xscreensaver-4.23}}
:{{cmduser|wget http://www.nax.cz/pub/bioapi/2005/xscreensaver/xscreensaver-4.22_alternativeAuth.diff mirror: http://zepan.org/files/xscreensaver-4.22_alternativeAuth.diff For xscreensaver 5.00, you can get a patch here: http://www.zzamboni.org/brt/files/xscreensaver-5.00-alternativeauth.patch}}
*After reviewing the patch (it's small and straightforward), do
:{{cmduser|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 <tt>pam</tt> and <tt>pam_bioapi</tt>. It should apply with some offset, don't mind that. If it says something about rejected though, then there's a problem.
*Compile with
:{{cmduser|./configure --with-pam && make}} 
*If you receive an error like "Couldn't find X11 headers/libs" and are running a Debian-like system, try "apt-get install xlibs-dev"
*If you receive an error like "undefined reference to `XmuPrintDefaultErrorMessage'" then install the libxmu-dev package and run the previous line again and then install as root with
:{{cmduser|su -c make install}} .
*Make sure that the newly compiled xscreensaver is used:
:{{cmduser|which xscreensaver}} should return
:{{cmdresult|/usr/local/bin/xscreensaver}} .
*In case it doesn't, try adjusting your PATH.

==Common problems==
===Bioapi error #3===
This is sometimes caused by improper permissions. The full error message is "BioAPI Error Code: 3 (0x3)".

However, at least on Gentoo, recent upgrades to glibc and gcc 4.1.1 caused Bioapi to break down due to some sort of incompatibility with bioapi registry. Reinstalling does '''not''' repair the issue automatically. However, you can still fix the issue manually, by removing /var/bioapi. You need to reinstall tfm-fingerprint driver after reinstalling bioapi so that the driver is properly re-registered. As root, type

:{{cmdroot|emerge -C bioapi}}
:{{cmdroot|rm -rf /var/bioapi}}
:{{cmdroot|emerge -av1 bioapi tfm-fingerprint}}

Code/enable-fingerprint-reader

2009-01-10T04:38:30Z

Dpward: Updated link to bioapi-c++.patch

#!/bin/bash
# Install UPEK fingerprint reader driver and associated software on Linux systems.
# Source: http://thinkwiki.org/wiki/Script_for_enabling_the_fingerprint_reader

set -e -E -x -u # verbose, abort if anything fails

WHERE=/opt/bioapi
PASSWD_ENROLLS=0 # should "passwd" do fingerprint enrollment (always)?

########################################
# Install (patched) bioapi:

mkdir -p $WHERE
wget -N http://www.qrivy.net/~michael/blua/bioapi/bioapi-latest.tar.bz2
wget -N -O bioapi-c++.patch 'http://cvs.pld-linux.org/cgi-bin/cvsweb/SOURCES/Attic/bioapi-c++.patch?rev=1.3'
sha1sum --check <<EOF
932425e847449e9612c6894dcbaf44630aecfc13 bioapi-latest.tar.bz2
a838e9ab9bcad9c146856d41135460e7ac29a4ec bioapi-c++.patch
EOF
tar xjf bioapi-latest.tar.bz2
pushd bioapi-1.2.2
patch -i ../bioapi-c++.patch -p1
./configure --with-Qt-dir=no --prefix=$WHERE
make
make install
install -m644 include/bioapi_util.h $WHERE/include/bioapi_util.h
install -m644 include/installdefs.h $WHERE/include/installdefs.h
install -m644 imports/cdsa/v2_0/inc/cssmtype.h $WHERE/include/cssmtype.h
chmod o-w $WHERE/var/bioapi
popd

########################################
# Tell ldconfig about bioapi libraries:

[ -d /etc/ld.so.conf.d ] || { echo "Unsupported distribution: no /etc/ld.so.conf.d directory."; exit 1; }
echo $WHERE/lib > /etc/ld.so.conf.d/bioapi.conf
ldconfig
ldconfig -p | grep -q bioapi || { echo "ldconfig doesn't see bioapi"; exit 1; }

########################################
# Install UPEK driver:

wget -N http://www.upek.com/support/download/TFMESS_BSP_LIN_1.0.zip
sha1sum --check <<EOF
c73466b5c3b26415b300d5c5ffb76deaefadeb32 TFMESS_BSP_LIN_1.0.zip
EOF
mkdir -p driver
pushd driver
unzip ../TFMESS_BSP_LIN_1.0.zip
PATH="$PATH:$WHERE/bin" sh install.sh $WHERE/lib/
cd NonGUI_Sample
perl -i -pe 'print "#include <stdlib.h>\n//DISABLED: " if m!^#include "port/bioapi_port.h"$!' main.c
gcc -o Sample main.c -I$WHERE/include -L$WHERE/lib -lbioapi100 -DUNIX -DLITTLE_ENDIAN
install Sample -m755 $WHERE/bin/upek-NonGUI_Sample
popd

SERIAL=`$WHERE/bin/BioAPITest | sed -ne "/Fingerprint/{n;n;s/^.*: $.\{9\}$$.\{4\}$$.\{4\}$$.\{4\}$$.*$/\1-\2-\3-\4-\5/gp}"`

########################################
# Install (patched) pam_bioapi:

wget -N http://www.qrivy.net/~michael/blua/pam_bioapi/pam_bioapi-latest.tar.bz2
wget -N http://badcode.de/downloads/fingerprint.patch
sha1sum --check <<EOF
a0bdf3436e55f7dc8b4795243f08a4c9b399dec8 pam_bioapi-latest.tar.bz2
619254a5bcd3acb8bf1d72b15ea69bfe00f0f064 fingerprint.patch
EOF
tar xjvf pam_bioapi-latest.tar.bz2
pushd pam_bioapi-0.2.1
patch -p0 < ../fingerprint.patch
CPPFLAGS="-I$WHERE/include" LDFLAGS="-L$WHERE/lib" ./configure --prefix=$WHERE
make
make install
ln -vfs $WHERE/lib/security/pam_bioapi.so* /lib/security/
popd

########################################
# Install pamtester:

wget http://mesh.dl.sourceforge.net/sourceforge/pamtester/pamtester-0.1.2.tar.gz
sha1sum --check <<EOF
33bcc610d7f208b50a0a23c144bdbd1e2cae4ac6 pamtester-0.1.2.tar.gz
EOF
tar xzvf pamtester-0.1.2.tar.gz
pushd pamtester-0.1.2
./configure --prefix=$WHERE
make
make install
popd

########################################
# Configure pam to use pam_bioapi:

grep -Eq 'Fedora Core release [456]|Red Hat Enterprise Linux AS release 4' \
/etc/redhat-release || { echo \
"I don't know how to configure PAM on this distribution.
See: http://thinkwiki.org/wiki/How_to_enable_the_fingerprint_reader#Configuring_pam";
exit 1; }

PAMFILE=/etc/pam.d/system-auth
if ! grep -q 'pam_bioapi\.so' $PAMFILE; then
perl -i -pe '
if (!$a && m/^auth.*pam_unix\.so/) {$a=1; print
"auth sufficient pam_bioapi.so '$SERIAL' /etc/bioapi/pam/\n"}
' $PAMFILE
if [ $PASSWD_ENROLLS == 1 ]; then
perl -i -pe '
if (!$p && m/^password/) {$p=1; print
"password required pam_bioapi.so '$SERIAL' /etc/bioapi/pam/\n"}
' $PAMFILE
fi
fi

########################################
# USB permissions (set now and add to startup):

RC_FILE=/etc/rc.local
SET_PERMS=$WHERE/bin/set_fingerprint_perms

cat > $SET_PERMS <<'EOF'
#!/bin/bash
# Make fingerprint reader USB device world-writable:
chmod -R a+X /proc/bus/usb
chmod 666 /proc/bus/usb/`/sbin/lsusb | sed -ne "/0483:2016/s/Bus\ $.*$\ Device\ $.*$:\ .*/\1\/\2/p"`
EOF
chmod 755 $SET_PERMS

$SET_PERMS

[ -e $RC_FILE ] || { echo "No $RC_FILE, can't handle this distribution."; exit 1; }
if ! grep -q 0483:2016 $SET_PERMS; then
echo $SET_PERMS >> $RC_FILE
fi

########################################
# Enroll:

mkdir -p /etc/bioapi/pam/$SERIAL
pushd /etc/bioapi/pam/$SERIAL
read -p "Now enroll your Unix accounts, including root (press Enter to start, then 'e' to enroll)."
$WHERE/bin/upek-NonGUI_Sample
popd

########################################
# Done:

set +x
cat<<EOF

Success.
* To test the fingerprint-enabled PAM login, run this as root:
$WHERE/bin/pamtester -v login USERNAME authenticate
* Add the following command to your resume-from-suspend script:
$SET_PERMS

EOF

Script for enabling the fingerprint reader with BioAPI

2009-01-10T04:36:16Z

Dpward: /* The script */ Found new link to missing patch file

Using the [[Integrated Fingerprint Reader|integrated fingerprint reader]] under Linux is currently a fairly complicated [[How to enable the fingerprint reader|process]]. The following script automates the installation of the fingerprint software, for some Linux distributions. It covers most components (bioapi framework, driver, pam_bioapi, PAM setup, USB device permissions pamtester and enrolling), and handles all the downloading, patching and installation.

Usage: just copy into a file and run as root.

After installation, all PAM-enabled system functions will use the fingerprint reader (and if it fails, default to the usual password entry). This includes:
* KDE's KDM login (enter an empty password, then swipe finger)
* KDE's screensaver (enter an empty password, then swipe finger)
* Gnome's GDM login
* <tt>su</tt>
* <tt>sudo</tt>

Everything is intalled into {{path|/opt/bioapi}}, so it doesn't pollute your filesystem. The only effects outside {{path|/opt/bioapi}} are one-line changes to the ldconfig configuration, PAM configuration and {{path|/etc/rc.local}}, and a few symlinks in {{path|/lib/security}}.

For details, manual installation and hints for other distributions, see [[How to enable the fingerprint reader]].

===Distributions supported by this script===
* {{Fedora}} 4, 5, 6
* Red Hat Enterprise Linux 4

If you add support for additional distributions, please update this script (using conditionals where necessary) instead of branching it.

==The script==
{{CodeRef|enable-fingerprint-reader}}

The patch has been moved to http://cvs.pld-linux.org/cgi-bin/cvsweb/SOURCES/Attic/bioapi-c++.patch?rev=1.3. However in CVS it has been marked as obsolete.

==Ideas for improvement==
* Support more distributions
* Minimize changes to {{path|/etc/pam.d/system-auth}} by creating a separate file (e.g., {{path|/etc/pam.d/bioapi-auth}}) and <tt>@include</tt>-ing it.
* Do something about {{path|/etc/pam.d/sshd}} - it invokes {{path|/etc/pam.d/system-auth}} by stacking, so remote SSH logins now invoke the fingerprint reader... See related discussion in [[How_to_enable_the_fingerprint_reader]].
* Install and configure a patched xscreensaver (as explained in [[How_to_enable_the_fingerprint_reader]]).
* Add "<tt>OnResume 10 /opt/bioapi/bin/set_fingerprint_perms</tt>" to [[Software Suspend 2|suspend2]]'s {{path|/etc/hibernate/hibernate.conf}}?

* The script ends with:
+ wget -N http://badcode.de/downloads/fingerprint.patch
--13:03:23-- http://badcode.de/downloads/fingerprint.patch
=> `fingerprint.patch'
Connecting to XXX.XXX.XXX.XXX:80... connected.
Proxy request sent, awaiting response... 401 Authorization Required
Authorization failed.

(proxy don't need authorization)
the file is under authorization

[[Category:Scripts]]