williamren / thinkfinger Goto Github PK

@PACKAGE_STRING@
===============================================================================

ThinkFinger is a driver for the UPEK/SGS Thomson Microelectronics fingerprint
reader (USB ID 0483:2016).  The device is being found either as a standalone
USB device, built into USB keyboards or built into laptops.  The following
laptop vendors are using the device:

- Dell
- IBM/Lenovo
- Toshiba

Toshiba is shipping their laptops either with the UPEK/SGS Thomson Micro-
electronics fingerprint reader or with a fingerprint reader built by AuthenTec.
The AuthenTec fingerprint reader is *not* supported by ThinkFinger.

SONY laptops with the UPEK/SGS Thomson Microelectronics fingerprint
reader are not supported.

ThinkFinger is devided into two parts: libthinkfinger and pam_thinkfinger.

libthinkfinger is a library to be used in order to communicate with the finger-
print reader.

The utility 'tf-tool' can be used to acquire and to verify fingerprints.

Installation Instructions
=========================

Please check the INSTALL file.

Simple Test Tool: tf-tool
=========================

Usage: tf-tool [--acquire | --verify | --add-user <login> ] [--verbose]

To acquire a fingerprint run 'tf-tool --acquire'.  You will be prompted to
swipe your finger.  It needs three successful swipes to get a fingerprint.
This fingerprint is being stored in '/tmp/test.bir'.

To verify a fingerprint run 'tf-tool --verify'.  tf-tool will read a finger-
print image from '/tmp/test.bir' and compare that with the finger which
is being swiped.

Notes:

It is likely that you have to run 'tf-tool' as root as it needs to access the
USB device.  On most distribution the device node can not be accessed by a
regular user.

The switch '--add-user' is only available if ThinkFinger was built with PAM
support.

Pluggable Authentication Module: pam_thinkfinger
================================================

The pluggable authentication module pam_thinkfinger can be used for PAM (e.g.
to log into your system).  The module needs to be copied to the location
where PAM expects the modules to reside.  On most GNU/Linux distributions
PAM modules are stored in '/lib/security'.

Also, the PAM module requires uinput.  For further details, please read section
"Kernel Requirements" of the installation instructions provided by the file
'INSTALL'.

In order to use pam_thinkfinger, PAM needs to be aware of the module.  To
achieve this please edit '/etc/pam.d/common-auth'.  You are required to add
the following directive before any pam_unix or pam_unix2 directives:

     auth     sufficient     pam_thinkfinger.so

See [1] for a complete example how '/etc/pam.d/common-auth' looks like.

The module does only trigger for users which have deposited their fingerprint
in '/etc/pam_thinkfinger/'.

E.g. if the user 'bob' wants to login using his fingerprint, his fingerprint
needs to be stored at '/etc/pam_thinkfinger/bob.bir'.  See [2] for a more
detailed example.

Notes:

If your PAM uses the pam_unix module, you need to pass a specific argument in
the /etc/pam.d/common-auth directive:

     auth     required     pam_unix.so try_first_pass

Otherwise, the password entered at the pam_thinkfinger prompt is not considered
by pam_unix.  This is only the case for pam_unix, because pam_unix2
automatically enables the try_first_pass argument by default.  More information
are available in the Linux-PAM documentation at:

  http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/sag-pam_unix.html

If you have troubles using the PAM module you may want to pass the 'debug'
option:

     auth     required     pam_unix.so debug

With this option the PAM module will be verbose and use syslog(3) for debug
output.

PAM Compatibility
=================

The pluggable authentication module pam_thinkfinger should work with all
PAM aware applications.

Authors
=======

Timo Hoenig <[email protected]>, <[email protected]>
Pavel Machek <[email protected]>

Thanks
======

Wolfgang Hafenscher <[email protected]> (project page)
Luca Capello <[email protected]> (patches, man pages)
Stephan Berberig <[email protected]> (patches)
Evgeni Golov <[email protected]>

Also, to big thanks to everyone else involved with the project by testing,
reporting bugs and communicating on thinkfinger-devel.

Project Page
============

* http://thinkfinger.sourceforge.net

SVN
===

* svn co https://thinkfinger.svn.sourceforge.net/svnroot/thinkfinger

Mailing List
============

* https://lists.sourceforge.net/lists/listinfo/thinkfinger-devel

[1] Example for a ThinkFinger-enabled '/etc/pam.d/common-auth'

#%PAM-1.0

auth	required	pam_env.so
auth	sufficient	pam_thinkfinger.so
auth	required	pam_unix2.so

[2] Example how to store a fingerprint image for user 'bob'

root@host~> tf-tool --add-user bob

( Now user 'bob' has to swipe his finger three times )

@PACKAGE_STRING@ (@PACKAGE_BUGREPORT@)
Copyright (C) 2006, 2007 Timo Hoenig <[email protected]>

Initializing... done.
Please swipe your finger (successful swipes 3/3, failed swipes: 0)... done.
Storing data (/etc/pam_thinkfinger/bob)... done.

Now 'bob' can authenticate himself by swiping his finger.