/---------------------------------------------------------------------------/ *

• NIST Linux/Unix BioAPI Reference Implementation
• Version: 1.1 (NIST Linux/Unix Evaluation Release)
• File Created: 08/27/02 File Updated: 11/07/02
• This README describes the implementation and installation details for the
• BioAPI Reference Implementation for Unix/Linux based systems.

/---------------------------------------------------------------------------/

1. Overview

2. Contact

3. System Requirements

4. Distribution

5. Build Instructions

6. Installation Instructions

7. Sample/Test App Instructions

8. Uninstalling and Package Removal

9. Distribution Summary

10. Disclaimer

11. Credits

12. Quick-Start Guide ===============================================================================

13. Overview

This package contains the BioAPI reference implementation for Unix-based platforms (in particular Linux and Solaris). The Unix-based reference implementation was developed by the Convergent Information Division (CISD), Information Technology Laboratory (ITL) of the National Institute of Standards and Technology (NIST). The Unix-based reference implementation is based directly on the BioAPI Consortium's Windows reference implementation and the Common Data Security Architecture (CDSA) reference implementation. The Unix-based reference implementation includes the Sample application and the MdsEdit utility from code provided by the International Biometric Group (IBG). Although this distribution has only been tested on Linux and Solaris, it is anticipated that porting it to other Unix-based platforms should be fairly straight-forward.

See the HTML files in this distribution for details of the BioAPI reference implementation.

2. Contact

Robert Snelick National Institute of Standards and Technology (NIST) (301) 975-5924 rsnelick@nist.gov

3. System Requirements

This release of the BioAPI has been built with the following software for an x86 platform (little-endian):

Red Hat Linux Version 7.3 2.96-112, Kernal 2.4.18-10 gcc Version 2.96 GNU Make Version 3.79.1 Qt GUI Toolkit Version 3.0.3

The release has been tested on the following systems:

• Red Hat Linux Version 7.3 2.96-112, Kernal 2.4.18-10
• Red Hat Linux Version 7.2 2.96-108.7.2, Kernal 2.4.9-34

AND

This release of the BioAPI has been built with the following software for the sparc platform (big-endian):

Solaris 8 (SunOS 5.8) Generic_108528-15 sparc SUNW,Ultra-60 Qt GUI Toolkit Version 3.0.3

Note: You must have QT version 3.0 or higher for the GUI related code. It is included with Red Hat Versions 7.3 and higher. The lastest version of QT can be downloaded at http://www.trolltech.com. QT does not come with Solaris distributions.

Note: If you wish to install the implementation without any GUI based code, see sections 5.4 for more information.

The makefile system as distributed here assumes that the Qt libraries were compiled using the native Sun C/C++ compiler. This is why all code which relies on Qt is compiled with the Sun C/C++ compiler, and not GCC/G++ like the rest of the code (Because there are known problems linking GCC/G++and Sun C/C++ compiled code). If your local SunOS systems has an installation of Qt that was compiled with GCC/G++ instead, you will need to adjust some of our makefiles to use GCC/G++ instead. Here are the locations of the makefiles: apps/CMDS, apps/MdsEdit, apps/QSample, and addins/qtpwbsp.

4. Distribution

The distribution comes as a compressed tar file (bioapi_unix_1.1.tar.gz). The follows commands can be used to extract the source code distribution.

A. Un-compress the distribution "gz" file (bioapi_unix_1.1.tar.gz) by typing at the command line:

% gunzip bioapi_unix_1.1.tar.gz

B. Un-archive the distribution "tar" file (bioapi_unix_1.1.tar) by typing at the command line:

% tar -xvf bioapi_unix_1.1.tar

This creates a subdirectory called 'bioapi' in the current directory that contains all the files in the distribution. The full path of the 'bioapi' directory is referred to as 'BIOAPI_PATH' in this document.

Follow the detailed instructions below for installation or jump to the Quick-Start Guide in section 12.

5. Build Instructions

The BioAPI reference implementation installs as two main components: binaries and data files. The binaries consist of dynamic shared libraries and executable programs. The data files consist of the Module Directory Service (MDS) database and registry. By default, both the binaries and the data files are installed into system directories (/usr/local and /var respectively). However, a configuration script has been provided which allows these locations to be altered.

Note that installing this software using the default locations will require that the installation be performed by someone with root priviledges. Also, once installed into the default system directories, only users with root priviledges will be able to run the software.

Below we describe the steps for configuring and building this package.

5.1 Set environment variable QTDIR to point to the installtion directory where Qt version 3.0 or higher is installed, and cd (change dir) to the top-level BIOAPI_PATH directory. For example,

   % cd BIOAPI_PATH
   % setenv QTDIR /usr/lib/qt3

   Note: QT is a GUI Toolkit that is used in the Sample application and
   the Mds Edit uitility.

   Note: Some Linux (e.g., Red Hat) distributions come with QT pre-install
   and set this variable automatically. If you don't have QT install on
   your system you can download the lastest version at 
   http://www.trolltech.com. 

5.2 Configure the software

  Configuration involves choosing which directories the software will use 
  for installation and operation.  Choosing a suitable configuration will 
  depend upon the local environment and needs of the users.  

  A configuration script has been provided which must be used to configure 
  the software.  The script has two main command-line options for choosing 
  the installation/operation directories.  They are:

  --prefix=[BINARY_INSTALL_PATH]  Sets path for the shared libs, includes 
                                  and executables:
                                  (Default: /usr/local)

  BINARY_INSTALL_PATH/bioapi   - includes (.h files) and executables 
                                 (test/example apps)
  BINARY_INSTALL_PATH/lib      - shared libraries (.so files)


  --with-mds=[MDS_INSTALL_PATH]   Sets path for the MDS database and 
                                  registry files:
                                  (Default: /var)

  MDS_INSTALL_PATH/bioapi_mds  - contains MDS database & registry base dir

  [**Note, hereafter BINARY_INSTALL_PATH and MDS_INSTALL_PATH will be used 
  to refer to the actual directories that were configured]


  There are several alternatives possible for configuring the software as 
  outlined below:


  First Configuration Alternative
  -------------------------------

  In the first alternative, the software may be configured to accept the 
  default installation paths, which are in system directories.  (The 
  defaults are BINARY_INSTALL_PATH=/usr/local and MDS_INSTALL_PATH=/var)  
  In this scenario only the system administrator (root) will be able to 
  install the software and run the example/test programs which come with 
  the package. 

  % ./configure

  NOTE: The default location for the libraries is /usr/local/lib. This
  directory may not be in the search path of the runtime link loader. 
  Therefore, before execution of the applications, the 
  LD_LIBRARY_PATH should be set to include /usr/local/lib or 
  /etc/ld.so.conf should include /usr/local/lib.

  If you want the *standard* library path, that is, /usr/lib you can set
  this with:

  % ./configure --prefix=/usr

  This will place the libraries in /usr/lib and the MDS data path in
  /var/bioapi_mds. With this the runtime linker will discover the libraries
  automatically.

  Second Configuration Alternative
  --------------------------------

  In the second alternative, the software can be configured to install 
  itself into non-system directories.  This option enables the software 
  to be installed and run by ordinary (non-priveldged) users.  (Note 
  however that using this configuration only the user who installs the 
  software will have access to it)

  % ./configure --prefix=/home/rob/local --with-mds=/home/rob/local

  Note: --prefix=/home/rob/local sets "LIB_INSTPATH"
  Note: Since (as in this example) you have chosen to install the shared 
  libraries (i.e., the .so files) to a *non-standard* location that is 
  not automatically searched by the runtime link loader you'll need to set 
  your LD_LIBRARY_PATH environment variable to include "LIB_INSTPATH" 
  prior to running any of the executables.

  For csh type shells do:
    % setenv LD_LIBRARY_PATH LIB_INSTPATH
    or
    % setenv LD_LIBRARY_PATH "${LD_LIBRARY_PATH}:LIB_INSTPATH"

    For example:
    % setenv LD_LIBRARY_PATH /home/rob/local/lib

  For sh type shells do:

    % export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:LIB_INSTPATH"

5.3 Build the BioAPI Libraries and Executables

   % make

This command will build and create all the libraries and executables for the BioAPI software development kit. The files are placed into the ./build/devkit directory. There are five sub-directories under devkit (bin, include, install, lib, and testbin).

After sucessful compilation the contents of these directories for this distribution should look like:

bin: MdsEdit QSample

include: bioapi_api.h bioapi_err.h bioapi.h bioapi_schema.h bioapi_spi.h bioapi_typecast.h bioapi_type.h bioapi_util.h bioapi_uuid.h biospi.h biospi_type.h bio.tmp bsp_schema.h device_schema.h installdefs.h mds.h port/bioapi_lock.h port/bioapi_port.h

install: install.sh mds_install mod_install uninstall.sh

lib: libbioapi100.so libbioapi_dummy100.so libbioapi_mds300.so libbioapi_util.a libCMDS.a libinstall.a libmds_util.a libmds_util_api.a libport.a libpwbsp.so

testbin: BioAPITest

5.4 Non-GUI Installation Option

If you want to build the system with out the GUI based code add the --without-gui flag to the configuration. This option can be added with any of the configuration options described above. The result of this flag is that the GUI Password BSP, MdsEdit, and Sample application will not be built. Instead a non-GUI version of the Password BSP and Sample application are built. This is a quick and easy way to test the implementation without relying on the QT GUI Toolkit.

% ./configure --without-gui

6. Installation Instructions

Depending upon the configuration options chosen in step 5.2, root priviledges may be required to install the software. In any case simply type:

% make install

If you do not have the correct priviledges to install the software for the configuration chosen in step 5.2, you will get an error message to the effect: "Under the present configuration only root can install bioapi". In that case simpy re-login as root (su root) and run "make install" again.

Otherwise, the software installs all of the files in ./build/devkit" to BINARY_INSTALL_PATH/bioapi and the shared libraries from ./build/devkit/lib into BINARY_INSTALL_PATH/lib. It also installs the Module Directory Service (MDS), the BioAPI framework, and the sample Biometric Service Providers (BSPs) to MDS_INSTALL_PATH/bioapi_mds.

If installation succeeds, you will see a series of messages similar to the following:

 mkdir /usr/local/bioapi
 installing bioapi files to /usr/local/bioapi
 cp -fR /home/rob/bioapi/build/devkit/* /usr/local/bioapi
 cd /usr/local/bioapi/install; ./install.sh all

 Installing BIOAPI ...

 Module Directory Services (MDS) ...
 MDS installed successfully.
 BioAPI Framework ...
 Module installed successfully.
 BioAPI Dummy Addin ...
 Module installed successfully.
 BioAPI Password BSP Module ...
 Module installed successfully.
 Done.

 Installing Test Modules ...

 No test modules to install ... OK

 Done.

7. Sample/Test App Instructions

The BioAPI reference implementation comes with a simple test program called BioAPITest and a sample GUI-based application called QSample.

** Note: System administrator (root) priviledges (i.e., write permission
   to the installation files) may be required to run these programs 
   depending up how the software was configured and where the MDS DB and 
   registry was installed.  See section 5 and 6 above for configuration 
   and installation instructions.

To run the test program type:

% cd BINARY_INSTALL_PATH/bioapi/testbin % ./BioAPITest

The output from the test program should be self-explanatory. This is a simple Non-GUI test application that simply interacts with the BioAPI and prints out information about the loaded BSPs.

To run the sample application type:

% cd BINARY_INSTALL_PATH/bioapi/bin % ./QSample

A window will appear with a menu to select a biometric technology. Select the Password BSP. Then type in a user name and select the Enroll button. Type a password on the edit box. Then select the Verify button. Type in a password. If the password matches the enrolled password for the user, an information dialog will appear indicating a match. Otherwise, the information dialog will indicate a non-match.

The template Dummy BSP have stub APIs and will report an error for any operation attempted. The Password BSP will enroll and verify a user.

Note there is a Sample Application and Password BSP that is not GUI-Based. The use of this version is simular, but is a one time pass-through and is by default set to the Password BSP.

To run the MDS Edit Utility type:

% cd BINARY_INSTALL_PATH/bioapi/bin % ./MdsEdit

A window will appear that has a tree structure that allows you to browse the software modules that have been installed.

8. Uninstalling and Package Removal

Below is a list of commands the can be used to uninstall the BioAPI reference implementation.

A. % make clean

Removes all the files (objects, libraries, executables) created in the build process. This command can be executed at any level in the directory hirearchy (it will clean from that point down).

B. % make distclean

Same as "make clean", but also removes the build/devkit/(bin, include, install, lib, and test) directories and the configure files (e.g., the makefiles). This command only applies to the top level BIOAPI_PATH directory. WARNING: make "distclean" will remove the makefiles and hence the capibilites for "make install/uninstall" and "make remove".

C. % make uninstall

This uninstalls the framework, MDS, and BSPs. You may need 'root' priviledge to run this command depending up on the software was installed (see sections 5 and 6 above). You must run this before running the "make remove" command. This command only applies to the top level BIOAPI_PATH directory.

D. % make remove

This removes the software development kit. This command only applies to the top level BIOAPI_PATH directory.

E. The sequence (in this order) to completely remove the distribution is:

  % make uninstall
  % make remove
  % make distclean

Again, these commands must be executed relative to the BIOAPI_PATH directory and may require root priveledge for the "make uninstall" and "make remove".

9. Distribution Summary

Below is a list of targets and the location of where they are built relative to the BIOAPI_PATH directory:

Target Type Location

BioAPITest Application apps/Test QSample Application apps/Sample Sample Application apps/NonGUI_Sample MdsEdit* Application apps/MdsEdit libCMDS.a* Library apps/Cmds libport.a# Library framework/port libbioapi_util.a Library framework/bioapi_util libmds_util.a Library framework/mds_util libmds_util_api.a Library framework/mds_util_api libinstall.a Library framework/h_layer/install libbioapi100.so Shared Library framework/h_layer libbioapi_mds300.so Shared Library addins/dl/mds libbioapi_dummy100.so Shared Library addins/bioapi_dummy_addin libpwbsp.so Shared Library addins/pwbsp libpwbsp.so Shared Library addins/qtpwbsp (GUI-version) mds_install Utility addins/dl/mds/mds_install mod_install Utility apps/mod_install

• Integrated from the International Biometric Group (IBG) code.

 as source code so that the location of the registery could be dynamic.

[Note: The locations of BINARY_INSTALL_PATH and MDS_INSTALL_PATH are set by the configure script (see section 5 above for details)]

BINARY_INSTALL_PATH/bioapi/bin BINARY_INSTALL_PATH/bioapi/include BINARY_INSTALL_PATH/bioapi/install BINARY_INSTALL_PATH/bioapi/lib BINARY_INSTALL_PATH/bioapi/testbin

BINARY_INSTALL_PATH/lib

MDS Database: MDS_INSTALL_PATH/bioapi_mds/BioAPIFFDB Registry : MDS_INSTALL_PATH/bioapi_mds/registry

10. Disclaimer

See the disclaimer notice in this directory.

11. Credits

Windows Implementation: See the contributers file in this directory. NIST BioAPI Implementation Linux port: Robert Snelick, NIST Configuration system: Mike Indovina, NIST MDS Editor Utility for Unix: International Biometric Group (IBG)

12. Quick-Start Guide

If root:

% cd BIOAPI_PATH
% ./configure --prefix=/usr
% make
% make install
% /usr/bioapi/testbin/BioAPITest
% /usr/bioapi/bin/QSample
% /usr/bioapi/bin/MdsEdit

If not root and install in /home/rob/local:

% cd BIOAPI_PATH
% ./configure --prefix=/home/rob/local --with-mds=/home/rob/local
% setenv LD_LIBRARY_PATH /home/rob/local/lib
% make
% make install
% /home/rob/local/bioapi/testbin/BioAPITest
% /home/rob/local/bioapi/bin/QSample
% /home/rob/local/bioapi/bin/MdsEdit

For a non-GUI version, replace the configure statement with:
% ./configure --prefix=/home/rob/local --with-mds=/home/rob/local --without-gui