Fingerprint Reader Integration using the M2SYS SDK

• Download sample program (requires installed M2SYS SDK to be run)- 21.73 KB
• Download Visual Studio 2008 source (requires M2SYS SDK to compile) - 14.71 KB

Introduction

This article presents a first look at the M2SYS Bio-PlugIn™ fingerprint identification Software Development Kit. This SDK gives independent software vendors a relatively straight-forward and robust way of integrating biometric fingerprint recognition into custom applications. A test application is presented, which exercises relevant functions from the SDK. You will need to obtain the M2SYS Bio-Plugin SDK to be able to compile and run the sample code.

Background

Bio-Plugin™ consists of a small client application that communicates with the host software and a high performance, back-end fingerprint recognition engine that performs all comparison requests. The client application communicates to the host software through a unique, loosely coupled interface and with the recognition engine through an M2SYS connection manager:

When a request to enrol, verify or identify a sample fingerprint is sent from the host application to Bio-Plugin™, a fingerprint capture window appears that blends in with the host software. Although it appears to end-users as a fully integrated component of the host software, Bio-Plugin™ actually processes all fingerprint activities separately.

The system can handle many client installations, and requires at least one server. The server stores the fingerprints and other metadata in a database, which can reside either on the same server as the fingerprint server, or on a separate server. For developing and testing, the client, server and database can reside on the same server. You will need to purchase a compatible USB fingerprint reader to begin experimenting with the system.

The architecture of the system allows developers to build an application with integrated fingerprint recognition which can run on multiple workstations without having to enrol the user's fingerprints on each system. Each client talks to a server which ultimately gets the fingerprint data from the central database.

Installation of Client and Server Software

I contacted M2SYS to get a copy of both the server and client software. The whole system needs to be licensed from the vendor, and the costs depend largely on how many users are to be stored in the fingerprint database.

Server Installation

The server installation is a Windows .MSI package which installs the server. After the installation is complete, the server must be licensed, which is accomplished through a control panel applet. M2SYS will give customers access to a web site where they can manage their client/server licenses. The documentation for the installation process provided through a Windows .chm help file is quite good. On my Vista system, the help file did not display the contents properly at first. I then found out that one as to right-click the .chm file, select properties and trust the file before re-opening it with the Windows Help system.

The server software also installs a small program with a traffic light icon into the windows taskbar, which allows you to start or stop the server. After starting the server, pressing the "View Core Server Log" button in the M2SYS control panel can help you diagnose possible problems, mostly licensing and or database connectivity problems. The server, as a default installs and uses a local Access (.mdb) file, although other database servers can be configured through an ODBC connection string.

The above shows a log where everything is configured correctly.

Client Installation

The client also installs through a .msi, at the end of which another installer for the U.are.U Digital Persona low-level SDK is launched. This secondary installer installs the required USB fingerprint drivers. Once the client has been installed, the USB fingerprint reader can be plugged-in. When the reader is plugged-in for the first time, the OS should detect the hardware and configure it automatically. Depending on what kind of fingerprint reader is purchased, a client license dialog may appear when the workstation is restarted after installing the client software.

Client Verification

Once the BioPlugin Client software is installed and activated, you can verify its basic functionality manually by following these steps:

1. Open Command Prompt window (Start -> Run -> "cmd").
2. Change to where BioPlugin Client was installed (“cd \Program Files\BioPlugin”).
3. Manually call the Single-Finger Scanning window “m2sysplugin.exe IS 0”.
4. The fingerprint scanning window will appear in the center of the screen.
5. Touch your finger to the fingerprint reader’s scanning surface.
6. At the top of the dialog, you will see the message "Fingerprint processed". This indicates that client is communicating with the server.
   • If a "Server connection failed" or "Invalid server name" message is displayed, confirm:
     • The BioPlugin Server software is running properly by checking the server log file

Manually stop the scanning window when finished "m2sysplugin.exe IS -1"

Detection of the M2Sys Client Software

Before you can use the client software, it is wise to write a little bit of code to make sure that the M2Sys client software is installed. The code below can be called from the Main(), before any Windows or forms using the M2Sys active X control. Although the SDK provides routines to detect Fingerprint readers, these cannot be used if the client software is missing. The first order of business is to write some detection logic. I chose to detect the COM registration of the Active X Bioplugin, which the client software installs. It is my hope that this GUID will not change in future versions of the M2SYS SDK.

private const string BiopluginNameInRegistry = "BioPlugInActX Control";
private const string BioPluginKey = @"CLSID\{05E8280C-D45A-494F-AE42-840A40444AFF}";

private static bool IsM2SysBioPluginInstalled()
{
    RegistryKey bioPluginRegistryKey;
    const string bioPluginKeyName = BioPluginKey;

    try
    {
        bioPluginRegistryKey = Registry.ClassesRoot.OpenSubKey(bioPluginKeyName, false);
    }
    catch
    {
        return false;
    }
    if (bioPluginRegistryKey == null)
        return false;
    string name = (string)bioPluginRegistryKey.GetValue(string.Empty);
    if (name == BiopluginNameInRegistry)
        return true;
    return false;
}

The above code is inserted at the start up of your application as shown here:

[STAThread]
private static void Main()
{
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);
    if (!IsM2SysBioPluginInstalled())
    {
        MessageBox.Show(Resources.ProgramNeedsM2Sys, Resources.MessageBoxTitle,
                        MessageBoxButtons.OK, MessageBoxIcon.Error);
        return;
    }
    Application.Run(new FingerTestForm());
}

The Fingerprint Demo Application

Now we go on to write the software to play with the control. At first, I thought the ActiveX control could be used like a UI-less COM server. I tried adding a reference to the COM server, creating an instance and using the API. This did not work, one actually needs to embed the Visual ActiveX control into the application. The way to do this is to go to the desired form, go to the Toolbox, right-click and use Choose Items... - then pick the fingerprint control:

The control then appears in the Visual Studio toolbox, after which it can be dragged to the design surface. The control can either be activated to show the current scan, or remain invisible; either way once it is on the design surface, it is possible to use the control. WPF users will need to create a WinForms UserControl which holds the Bioplugin ActiveX control. This WinForms Usercontrol is then inserted into the WPF window or page using the <WindowsFormsHost> element. The Loaded event handler then assigns the WinForms UserControl to the WindsFormsHost child.

Asynchronous Method Calls

Due to its client-server architecture, the BioPluginActX control needs to make requests to the server. The server then interacts with the database, and eventually returns information back to the ActiveX control. Upon receiving a server response, the BioPluginActX control fires an event to a sink located in the client. After the event has been received by the client, the client can make another call to retrieve error and response codes. For client application, dealing with Asynchronous method calls is intrinsically more complex than using a synchronous model. The sequence of calls to enrol fingerprints is as follows:

1. Client calls to enrol, by using bioPlugin.RegisterPrintShort(name).
2. BioPlugIn ActiveX control displays a modal dialog to register the print.
3. User scans in fingerprints.
4. Control sends scans to the server.
5. Server saves scans in database.
6. Control fires the OnRegister event back to the client application.
7. Client application makes a callback to the ActiveX control to retrieve the result property.

The application code below shows how we can make the asynchronous events look synchronous in the application.

// a synchronization primitive that helps with the 
// waiting associated with asynchronous calls
private readonly ManualResetEvent _eventRecievedInfo = new ManualResetEvent(true);

// this is the event handler for the button press
// we pass the equivalent of a function pointer to the DoFingerPrintAction call
private void _registerShortButton_Click(object sender, EventArgs e)
{
    DoFingerPrintAction(()=>_fpReader.RegisterPrintShort(_enterIdText.Text), 
					ResultCode.RegisterPrintShort);
}

private void DoFingerPrintAction(Action action, ResultCode resultCode)
{
    _currentResult = resultCode;
    _eventRecievedInfo.Reset();
    action();         // this is where the call to the ActiveX is made
    WaitForInfo();    // we wait for a response here
}

private void WaitForInfo()
{
    for (int i = 0; i < 60; i++)  // maximum wait = 60 seconds
    {
        // this needs to be called for the Windows Message pump
        // to work, and for the events to come in.
        Application.DoEvents();      
        bool gotSignal = _eventRecievedInfo.WaitOne(1000);
        if (gotSignal)
        {
            return;
        }
    }
}

// This is the event handler for the OnRegister Event
// on the bioPlugin control
private void bioPlugin_OnRegister(object sender, EventArgs e)
{
    string fromAxControl = bioPlugin.result;

    switch (_currentResult)
    {
        case ResultCode.RegisterPrintShort:
            _returnCodeFromRegistration = fromAxControl;
            break;
        case ResultCode.UpdatePrint:
            _returnCodeFromRegistration = fromAxControl;
            break;
    }
    _eventRecievedInfo.Set();
}

Note that we need to call Application.DoEvents while waiting. This ensures that the windows message pump system can deliver the COM events to our application. One of the problems with hard-coding a limit of 60 seconds is that the user must actually register his/her fingerprints within one minute, otherwise the return code will be missed.

Fingerprint Management UI Still Needed

The M2SYS Bio-Plugin control helps to solve the problem of storing and matching prints, enrolling and updating prints and deleting prints. The integrator however is still responsible for building the UI to configure, enrol, update, and delete Fingerprints. While the control does most of the heavy lifting, one problem I ran into is that the fingerprint delete functionality requires that you pass in the original unique ID (usually a name) of the record you wish to have deleted. If registrations to a central database are made from different client machines, all of the IDs will not be available on a specific machine. The control, apparently intentionally for security reasons, does not allow the developer to get a list of all of the IDs in the database. Below is some code that will connect to the local access database and retrieve the IDs. [The password in the code below should be changed to match the database password.]

private void ReadAccessDatabase()
{
    OleDbConnection thisConnection =
        new OleDbConnection(
            @"Provider=Microsoft.Jet.OLEDB.4.0;
		Data Source=C:\Program Files\BioPlugin\Database.mdb ;
            	Persist Security Info=False; Jet OLEDB:Database Password=password;");
    OleDbCommand thisCommand = new OleDbCommand
			("SELECT REGISTRATIONNO FROM PERSON", thisConnection);

    try
    {
        thisConnection.Open();
        OleDbDataReader thisReader = thisCommand.ExecuteReader();

        while (thisReader.Read())
        {
            Debug.WriteLine(thisReader.GetString(0));
        }
    }
    catch (OleDbException ex)
    {
        Console.WriteLine(ex.ToString());
    }
    finally
    {
        thisConnection.Close();
    }
}

The code to read information from a SQL Express 2008 database, in contrast looks like this: [why do we have to change anything but the connection string?]:

private void _readDB_Click(object sender, EventArgs e)
{
    SqlDataReader myDataReader = null;

    SqlConnection mySqlConnection =
        new SqlConnection(
            @"Data Source=10.0.0.1\SQLEXPRESS; 
		Initial Catalog=FingerDB; User ID=user; Password=password;");

    SqlCommand mySqlCommand = new SqlCommand
		("SELECT REGISTRATIONNO FROM dbo.PERSON", mySqlConnection);
    mySqlConnection.Open();
    myDataReader = mySqlCommand.ExecuteReader(CommandBehavior.CloseConnection);
    while (myDataReader.Read())
    {
        Debug.WriteLine(myDataReader.GetString(0));
    }
    mySqlCommand.Dispose();
    mySqlConnection.Close();
}

It is also possible to encrypt the traffic between the database client and server, by adding 'Trusted_Connection=True' to the connection string.

Using a SQL Server Express 2008 Database Server

The last part of the article brings us to making things work with SQLExpress 2008; you would need to connect to a real networked database server to query the database from a remote client. I am not going to explain in extensive details how to configure the database to make things work, the documentation from M2SYS is fairly detailed in this regard. The documentation however does not mention what you need to do to get a SQLExpress 2008 server up and running. The rough steps are as follows:

1. Download SQL Express 2008.
2. Install SQL Express 2008, writing the 'sa' password down somewhere.
3. Download and install "Microsoft SQL Server Management Studio Express".
4. The next steps are done within the SQL Server Management Studio Express program. Use 'sa' as the username, and your written down password. The server should be localhost\SQLEXPRESS.
5. Create a new database.
6. Create a new user for the database, assigning a password.
7. Grant permissions to the newly created user to Create Table, Select, etc.
8. Execute the create table query installed here: "C:\Program Files\BioPlugin\Tables-Script-SQL Server.sql". You may need to add a use yourdatabasename; as the first statement in the file.
9. On the machine running the BioPlugin server, modify the "C:\Program Files\BioPlugin\server.ini" ConnectStr entry to point to the right connection string (see code above for an example of the format) to connect to SQLExpress.
10. Stop and restart the BioPlugin server service.

Most of the problems I have had were identifying the correct connection strings to use.

Conclusion

A smooth integration of Biometrics into your application, even when using a good software integration toolkit can require some effort. Besides a required fingerprint management application, deployment of such a system will likely involve an IT organization in medium-to-large organization. Your system documentation must be good, and your support organization must be able to help your clients resolve potential problems. Your application may need to include a prerequisite installer to install the required client components; how client and server licensing works needs to be worked out from a deployment perspective and be negotiated with the vendor. Fingerprint reader hardware will also have to be purchased and distributed with the application. In heavily regulated environments, where users face audit-trails and need to authenticate very frequently during the day, an integrated biometrics solution can make your customer significantly more productive and your software will be easier and more fun to use.

History

• August 11, 2009 - Initial release