This is a module agent pair that can be used to authenticate remotely
with a fingerprint. The module and the agent are designed to work with
the American Biometric Corporation's (ABC) BiomousePlus fingerprint reader.

  www.biomouse.com

This distribution comes in two parts. The first is the binary only
commercial biomouse kernel module, and fingerprint recognition library
-- these are a subset of the ABC developer's kit, and are included in
the 'smartcard' directory, with the permission of ABC. The second part
is a LGPLd PAM agent/module combination, which can be found in the
'print' directory.

To prepare your system, you will need a BiomousePlus device, and a
2.2.x Linux kernel with module support. Here is what you need to do:

   /sbin/insmod -f smartcard/3.2c/drvs/2.2.5-15/biomouse.o

   /bin/grep biomouse /proc/devices

This should give some output like this: 254 biomouse, which means that
you need to do the following:

   /bin/mknod -m 0666 /dev/biomouse 254 0

(Substitute 254 if your /proc/devices file says something else.)

At this point, your system should be able to talk to the biomouse
device.

Next, you need to build the agent and module. You'll need
Linux-PAM-0.70+ and gtk+-1.2 or gtk+-1.0. (I'd be very happy to receive
a more KDE friendly version of the agent, but I'm so little
clued in to GUIs that learning a little of one is enough for
me... If you can make the GTK one better, I'd be happy with that too!)
NB. The agent is an X-dialog box thing that displays your fingerprint
as it is entered.

If you have these installed, you should 'cd prints', and do:

  ./configure
  make all

This will build, three things:

  pam_fp240x240.so - the PAM module (requires Linux-PAM-0.70 or better)

  fp240x240@prototype1 - the PAM (client side) agent

  fp240 - a practice program that uses the libpamc client library to
          load the agent and can be used to store a digest of your
          fingerprint, for authentication purposes.

So, you have all of these. How do you use them? You'll need a
server-client application that supports client side PAM agents. One
such application is ssh. You may need the full PAM patch to enhance
your current version of ssh. (You can find the latest version of this
patch here:

   ftp://ftp.kernel.org/pub/linux/libs/pam/pre/applications

At the time of writing its an alternative PAM patch to the one found
on www.replay.com. Perhaps it will become part of the offical RPM?
Note, there is no crypto in this patch so it can be downloaded from
anywhere.)

Then, you should amend your /etc/pam.d/ssh config file to look
something like this (its fine to use pam_unix instead of pam_pwdb or
some other modules):

#%PAM-1.0
auth       required     pam_nologin.so
auth       sufficient   pam_fp240x240.so
auth       required     pam_pwdb.so shadow
account    required     pam_pwdb.so
password   required     pam_cracklib.so
password   required     pam_pwdb.so shadow nullok use_authtok
session    required     pam_pwdb.so

You should install the module (pam_fp240x240.so) in /lib/security/

You should install the agent (fp240x240@prototype1) in /lib/pamc/
(you may have to create this directory).

You should run fp240 like this:

  ./fp240 `whoami` fpfile

put your preferred finger on the biomouse and select authenticate when
you are done (if your fingerprint stabilizes, the agent may quit on
its own). A digest of your fingerprint is now stored in 'fpfile'. The
way the module is written, it will look for good fingerprints in
~/.ssh/fingerprint, so you should do this:

  /bin/mv fpfile ~/.ssh/fingerprint

If all is configured correctly, the next time you log in via ssh, you
should get the opportunity to use your fingerprint to authenticate
you! ;)

Bugs outstanding:

  - why do the agent _and_ the module need to initialize the driver?

I'd like to hear about any other problems.

If you'ld like me to investigate adding support for other biometrics,
email me...

Cheers

Andrew <morgan@linux.kernel.org>
