** About This Package **
========================

pam_bioapi - Provides a PAM-compliant interface to use in biometrically
authenticating or identification local users.

** Dependencies **
==================

For installation you have to have BioAPI framework and sqlite3 installed.

** Testing **
=============

To test: add a file named "test-pam_bioapi" in /etc/pam.d/ with the contents like this:
"auth required pam_bioapi.so -b {263a41e0-71eb-11d4-9c34-124037000000}"
similar for passwd functionality.

Use the test_enroll-pam_bioapi and test_verify_pam-bioapi to create and verify BIRs.

** Datasouce **
===============

For storing enrolled BIRs you have to use default SQLite3 db.

Default path (to the BIRs): /etc/bioapi/

Default db name for SQLite3 store is bioshadow.db

You can configure parameters in /etc/bioapi/birdb.conf

** Parameters of pam_bioapi **
==============================

This parameters can be specified in /etc/pam.d/* configuration files. 
Only BSP parameter (-b) is required, others are optional.

- Module ID of BSP you want to use. This is identificator of "driver" provided by 
vendor of device or other BSP developer. You can check for installed BSPs for 
example by BioAPITest utility (from Linux BioAPI distribution). If BioAPI framework 
working correctly you get something like this for UPEK's driver: 
"{5550454b2054464d2f45535320425350}". To convert this to parameter expected by
pam_bioapi please add dash ("-") after first 8 characters, then after 4, 4 and 4.
The rest should be 12 characters long (I don't counting curly brackets {}).
For example above we're getting "{5550454b-2054-464d-2f45-535320425350}".
This (without quotes) you have to specify if you want to use UPEK's device
with pam_bioapi.

- Optional but critical is -u option. It is strongly recomended to use this option
in cases where application know username. If you don't specify this option for application
like gnome-screensaver, every user with enrolled fingerprints in database will be allowed
to unlock screen! This is same for su or sudo too.

- Keep in mind driver's gui (if you use -g option) running with credentials of root and
you have to allow superuser manipulation with screen (please consult xauth utility).
Very quick and dirty solution is
# ln -s /home/user_running_X/.Xauthority /root/.Xatuhority
If application support it, it is better to use pam_bioapi without -g option!

** Examples of configuration pam module **
==========================================

I always want to have second possibility to log on by password if biometrics authentication
fails (e.i. I have very cold hand and live detection mechanism in device thinks finger
is death).

Most of configuration files from /etc/pam.d/ directory have this line for auth function:

auth       required     pam_stack.so service=system-auth

That mean configuration for all this applications is in same file called system-auth.
So I change file /etc/pam.d/system-auth to this:

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

This mean pam first try to authenticate by biometrics device by UPEK's BSP and if this fail 
it ask user for password. 

But if I want identification working in XDM and I don't want to be ask for fingerprint
if it failed for first time, I can achieve that by different configuration file
we can call it for example /etc/pam.d/system-auth-x11:

auth       sufficient   pam_unix.so likeauth nullok
auth       sufficient   pam_bioapi.so -b {5550454b-2054-464d-2f45-535320425350} -g -d :0
auth       required     pam_deny.so

If XDM call PAM for the first time password check fails and user is directly 
ask for his fingerprint. But after it if biomtrics check fail user should be ask username
and password and after that first pam module is used to login since second
pam authenticating is invoked.

I changed /etc/pam.d/xdm and /etc/pam.d/xscreensaver to this:

auth       required     pam_stack.so service=system-auth-x11

I have also third generic config for applications where biometrics authentication
isn't good idea (like sshd - if someone connecting to your computer over ssh
it is not good idea authenticate him by biometrics since you don't have control
who you actually allowing access).

For details about PAM framework please follow this link:
http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam.html

Comments are welcome.

** Thanks **
============

I would like to thanks UPEK company for their support of my development.
Josef Hajas aka nax <josef at hajas dot net>

** Licence **
=============

  Copyright (C) 2005-2006 Josef Hajas <josef at hajas dot net>
  Copyright (C) 2005 Michael R. Crusoe <michael at qrivy dot net>

  pam_bioapi is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

  libbirdb and int_bioapi under BSD licence:

  Copyright (c) 2006 Fredrik Lindberg. <fli at shapeshifter dot se>
  All rights reserved.
 
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions
  are met:
  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.
 
  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

