ACS AET65 User guide

Application Programming Interface
idvation GmbH
Otto-Hesse-Straße 19 / T5 Phone [phone]
D-64293 Darmstadt Fax [phone]
[email protected] www.idvation.com
Application Programming Interface
AET65
Fingerprint Reader

Document Title Here
AET65 API
Version 1.0
idvation GmbH
Otto-Hesse-Straße 19 / T5 Phone [phone]
D-64293 Darmstadt Fax [phone]
[email protected] www.idvation.com Title Here
Page 2 of 84
Revision History
Version Date Prepared By Description of Changes
1.0 August 6 2010 Melissa Balmes
•Based on UPEK’s BSAPI
Reference Manual; Changed
document filename to
API_AET65_v1.0
•Changed Title to AET65 Fingerprint
Reader Application Programming
Interface
•Added Introduction
August 26 2010 Melissa Balmes •Removed all details on BSSRV

Document Title Here
AET65 API
Version 1.0
idvation GmbH
Otto-Hesse-Straße 19 / T5 Phone [phone]
D-64293 Darmstadt Fax [phone]
[email protected] www.idvation.com Title Here
Page 3 of 84
Table of Contents
1.0. Introduction .............................................................................................................6
2.0. BSAPI.......................................................................................................................7
2.1. Terminology...........................................................................................................................7
2.2. Overview................................................................................................................................7
2.3. Architecture............................................................................................................................7
2.4. Naming Conventions .............................................................................................................8
3.0. BSAPI.DLL Functions .............................................................................................9
3.1. General Description...............................................................................................................9
3.1.1. Error Handling...............................................................................................................9
3.1.2. Memory Management...................................................................................................9
3.1.3. Interactive Operations...................................................................................................9
3.1.4. Multi-threading ..............................................................................................................9
3.1.5. Anti-latent Checking....................................................................................................10
3.2. Application General Functions.............................................................................................11
3.2.1. ABSInitialize................................................................................................................11
3.2.2. ABSInitializeEx............................................................................................................11
3.2.3. ABSTerminate.............................................................................................................11
3.2.4. ABSOpen ....................................................................................................................12
3.2.5. ABSClose....................................................................................................................13
3.2.6. ABSEnumerateDevices ..............................................................................................13
3.2.7. ABSGetDeviceProperty ..............................................................................................14
3.2.8. ABSFree......................................................................................................................14
3.3. Biometric Functions .............................................................................................................15
3.3.1. ABSEnroll....................................................................................................................15
3.3.2. ABSVerify....................................................................................................................16
3.3.3. ABSVerifyMatch..........................................................................................................17
3.3.4. ABSCapture ................................................................................................................18
3.3.5. ABSCheckLatent.........................................................................................................19
3.3.6. ABSNavigate...............................................................................................................20
3.4. Image Grabbing Functions ..................................................................................................21
3.4.1. ABSGrab.....................................................................................................................21
3.4.2. ABSRawGrab..............................................................................................................23
3.4.3. ABSListImageFormats................................................................................................24
3.4.4. ABSGrabImage...........................................................................................................25
3.4.5. ABSRawGrabImage....................................................................................................26
3.5. Miscellaneous Functions .....................................................................................................28
3.5.1. ABSCancelOperation..................................................................................................28
3.5.2. ABSSetAppData..........................................................................................................28
3.5.3. ABSGetAppData.........................................................................................................29
3.5.4. ABSSetSessionParameter..........................................................................................29
3.5.5. ABSGetSessionParameter .........................................................................................30
3.5.6. ABSSetGlobalParameter ............................................................................................30
3.5.7. ABSGetGlobalParameter............................................................................................32
3.5.8. ABSSetLED.................................................................................................................33
3.5.9. ABSGetLED ................................................................................................................34
3.5.10. ABSBinarizeSampleImage..........................................................................................35
3.5.11. ABSGetLastErrorInfo ..................................................................................................36
3.5.12. ABSEscape.................................................................................................................36
4.0. BSGUI.DLL Functions...........................................................................................37
4.1. Using BSGUI.DLL................................................................................................................37

Document Title Here
AET65 API
Version 1.0
idvation GmbH
Otto-Hesse-Straße 19 / T5 Phone [phone]
D-64293 Darmstadt Fax [phone]
[email protected] www.idvation.com Title Here
Page 4 of 84
4.2. GUI Customization...............................................................................................................37
4.3. Default Callback Implementation.........................................................................................37
4.3.1. ABSDefaultCallback....................................................................................................37
4.4. ABS_DEFAULT_CALLBACK_CONTEXT...........................................................................38
4.5. Flags for ABS_DEFAULT_CALL BACK_CONTEXT ..............................................................
(ABS Default_CALLBACK_FLAG_xxxx).............................................................................38
5.0. Declarations...........................................................................................................39
5.1. Basic Types .........................................................................................................................39
5.2. Specific Types .....................................................................................................................39
5.2.1. ABS_DATA .................................................................................................................39
5.2.2. ABS_BIR_HEADER....................................................................................................40
5.2.3. ABS_BIR.....................................................................................................................41
5.2.4. ABS_OPERATION......................................................................................................42
5.2.5. ABS_PROFILE_DATA................................................................................................43
5.2.6. ABS_SWIPE_INFO.....................................................................................................43
5.2.7. ABS_IMAGE_FORMAT..............................................................................................45
5.2.8. ABS_IMAGE ...............................................................................................................46
5.2.9. ABS_PROCESS_DATA..............................................................................................47
5.2.10. ABS_PROCESS_BEGIN_DATA ................................................................................47
5.2.11. ABS_PROCESS_PROGRESS_DATA.......................................................................47
5.2.12. ABS_PROCESS_SUCCESS_DATA..........................................................................48
5.2.13. ABS_NAVIGATION_DATA.........................................................................................48
5.2.14. ABS_DEVICE_LIST_ITEM .........................................................................................48
5.2.15. ABS_DEVICE_LIST....................................................................................................49
5.2.16. ABS_CALLBACK........................................................................................................50
6.0. Specific Constants................................................................................................53
6.1. Flags for ABSInitializeEx (ABS_INIT_FLAG_xxxx).............................................................53
6.2. Flags for ABS_OPERATION (ABS_OPERATION_FLAG_xxxx).........................................53
6.3. Flags for Biometric and Image Grabbing Functions (ABS_FLAG_xxxx).............................54
6.4. Template Purpose Constants (ABS_PURPOSE_xxxx) ......................................................55
6.5. Key Constants for ABS_PROFILE_DATA (ABS_PKEY_xxxx)...........................................56
6.6. ABS_PKEY_IMAGE_FORMAT Values (ABS_PVAL_IFMT_xxxx) ..................................60
6.7. ABS_PKEY_REC_TERMINATION_POLICY Values (ABS_PVAL_RTP_xxxx)..................64
6.8. ABS_PKEY_REC_SWIPE_DIRECTION Values (ABS_PVAL_SWIPEDIR_xxxx)..............65
6.9. ABS_PKEY_REC_NOISE_ROBUSTNESS Values (ABS_PVAL_NOIR_xxxx)..................65
6.10. ABS_PKEY_SENSOR_SECURITY_MODE values (ABS_PVAL_SSM_xxxx)...................66
6.11. Swipe Info Flags (ABS_SWIPE_FLAG_xxxx).....................................................................67
6.12. Process Constants (ABS_PROCESS_xxxx).......................................................................68
6.13. Device Property Constants (ABS_DEVPROP_xxxx) ..........................................................71
6.14. Session and Global Parameter Constants (ABS_PARAM_xxxx)........................................72
6.15. Parameter ABS_PARAM_CONSOLIDATION_TYPE Values
(ABS_CONSOLIDATION_xxxx)..........................................................................................75
6.16. Parameter ABS_PARAM_MATCH_LEVEL Values (ABS_MATCH_xxxx)..........................75
6.17. Parameter ABS_PARAM_ANTISPOOFING_POLICY Values ...............................................
(ABS_ANTISPOOFING_xxxx).............................................................................................76
6.18. Callback Message Codes (ABS_MSG_xxxx)......................................................................76
7.0. List of Defined Result Codes................................................................................81
8.0. New Features in Version 3.5.................................................................................82
8.1. Global Parameter ABS_PARAM_IFACE_VERSION ..........................................................82
8.2. Dynamic Enrollment.............................................................................................................82
8.2.1. Global Parameter ABS_PARAM_CONSOLIDATION_COUNT..................................82
8.2.2. Structure ABS_PROCESS_BEGIN_DATA.................................................................82
8.2.3. Structure ABS_PROCESS_PROGRESS_DATA .......................................................82

Document Title Here
AET65 API
Version 1.0
idvation GmbH
Otto-Hesse-Straße 19 / T5 Phone [phone]
D-64293 Darmstadt Fax [phone]
[email protected] www.idvation.com Title Here
Page 5 of 84
8.2.4. Constant ABS_PROCESS_CONSOLIDATE..............................................................82
8.3. Image Grabbing Functions ..................................................................................................83
8.3.1. Constant ABS_FLAG_HIGH_RESOLUTION .............................................................83
8.3.2. Structure ABS_IMAGE................................................................................................83
8.3.3. New Grabbing Functions ............................................................................................83
8.4. Global Parameter ABS_PARAM_POWER_SAVE_CHECK_KEYBOARD.........................83
8.5. Internal Template Format Types .........................................................................................83
8.6. Compatibility with Windows NT Services ............................................................................84
8.7. ABS_CALLBACK and Threads............................................................................................84
8.8. Support for Terminal and Citrix............................................................................................84
Figures
Figure 1: AET65 System Block Diagram..........................................................................................6
Figure 2: AET65 Connection ............................................................................................................6

Document Title Here
AET65 API
Version 1.0
idvation GmbH
Otto-Hesse-Straße 19 / T5 Phone [phone]
D-64293 Darmstadt Fax [phone]
[email protected] www.idvation.com Title Here
Page 6 of 84
1.0. Introduction
The AET65 is a composite device, consisting of a smart card reader and a swipe fingerprint sensor. The smart
card reader and the fingerprint sensor can be used independently, but combining the two technologies provide
a higher level of security in applications. The AET65’s system diagram is shown below:
Figure 1: AET65 System Block Diagram
The smart card reader module, which is based on the ACR38-SAM core, follows the PC/SC API standards.
For information on the smart card reader module, please refer to the AET65 Smart Card Reader Reference
Manual document (REF_AET65_v1.0).
The purpose of this document is to describe the architecture and interface of Biometric Services API (BSAPI).
This is based on UPEK’s BSAPI Reference Manual and shall cover the Application Programming Interface
related only to the fingerprint sensor. This manual describes the BSAPI and how to use the different libraries
to program the fingerprint module of AET65. The libraries are responsible for handling the communication
details, parameter conversions and error handling providing programmers a simple and consistent interface
over all possible hardware. The architecture of the BSAPI can be visualized as the diagram below:
Figure 2: AET65 Connection

Document Title Here
AET65 API
Version 1.0
idvation GmbH
Otto-Hesse-Straße 19 / T5 Phone [phone]
D-64293 Darmstadt Fax [phone]
[email protected] www.idvation.com Title Here
Page 7 of 84
2.0. BSAPI
2.1. Terminology
•BSAPI – Biometric Services API
•FM – fingerprint module (fingerprint reader device) connected to host
•HOST – computer where the FM is connected to
•BioAPI – the industry standard for biometric API, developed by BioAPI Consortium [www.bioapi.org].
All references to BioAPI in this document assume version 1.1 of the standard.
•BioAPI Framework – reference implementation of BioAPI, by BioAPI Consortium.
•(BioAPI) BSP – Biometry Service Provider; 3rd party module pluggable into BioAPI Framework. BSP
provides support for particular device (e.g. fingerprint reader).
•BSP API – API below BioAPI Framework, specifying interface between BioAPI framework and BSPs.
•TFMESSBSP – Upek BSP implementation, supporting TFM and ESS devices.
2.2. Overview
BSAPI was designed to meet these requirements:
•Similar to BioAPI: development team familiar with BioAPI should be able to adopt BSAPI easily and in
reasonably short time.
•Compatibility with TFMESSBSP: BSAPI will provide functions which can behave exactly as corre-
sponding functions in TFMESSBSP. (Future version of TFMESBSP can be implemented on top of
BSAPI easily.)
•BSAPI will be implemented in simple DLL. Unlike BioAPI, BSAPI does not require any framework to
use it.
•BSAPI will provide more functionality comparing to BioAPI, so more biometric and miscellaneous
features of our devices will be available (e.g. navigation).
•Avoid need to use any low level API (e.g. PTAPI).
Do not misunderstand the term “compatibility” with BioAPI as used in the list above. There will be no binary
compatibility between BioAPI and BSAPI, nor compatibility on source level. BSAPI will provide set of function
which will allow all code using BioAPI (with TFMESSBSP) to be rewritten to use BSAPI instead, with exactly
the same behavior.
In fact, as further described below, future versions of TFMESSBSP will be thin layer on top of BSAPI.
2.3. Architecture
BSAPI is composed of several dynamic libraries (.DLL on Windows. On other system, other file extension is
used.):
•BSAPI.DLL, which contains all core functionality. This library will be mostly platform independent on
source level. Porting BSAPI to additional platforms (e.g. Linux, Mac OS X) will be relatively cheap and
fast task assuming that the underlying libraries are ported as well.
•BSGUI.DLL providing default implementation of GUI callback. The library loads graphics from sepa-
rated .zip file (window decorations and feedback images), so that customization of look & feel is pos-
sible. The library supports multiple languages (localization), generally those supported in our other
software. Applications can provide their own callback and in such case, they do not use this library.
Please note that currently BSGUI.DLL is available only for Windows platform.

Document Title Here
AET65 API
Version 1.0
idvation GmbH
Otto-Hesse-Straße 19 / T5 Phone [phone]
D-64293 Darmstadt Fax [phone]
[email protected] www.idvation.com Title Here
Page 8 of 84
Application developers can choose from several approaches on how to deal with the GUI:
•Use BSGUI.DLL as it is, will guarantee appearance of the applications, consistent with their own
applications.
•Use BSGUI.DLL, with customized .zip file (some or all of the graphics in the .zip file can be modified
or replaced with other graphics).
•Implement their own callback implementation. This allows maximal freedom in customization, includ-
ing adding support for languages not supported by BSGUI.DLL.
BSAPI is implemented on top of BioFrame. The BioFrame is a library providing high level management of the
device, quality assurance and other policies. This allows users of BSAPI to concentrate on application logic
and not sink into low level details.
Future versions of BioAPI BSP will be redesigned as a simple layer on top of BSAPI to avoid duplicity of code
in BSAPI and TFMESSBSP implementations. BSAPI should be linked statically into the TFMESSBSP. This
will prevent unnecessary exporting BSAPI symbols from the DLL so users of BioAPI could not mix the two
APIs in one program by mistake. Also due to the nature of static libraries only the required subset of BSAPI
library will be included in the TFMESSBSP.
2.4. Naming Conventions
All identifiers (names of constants, types and functions) will use prefix “ABS”, and follow the patterns below:
•ABS_MACRO_IDENTIFIER
•ABS_TYPE_IDENTIFIER
•ABSFunctionIdentifier()
In function prototypes special words IN, OUT and INOUT are used, to denote if the parameter is used to pass
data into the function, return some result data or both.

Document Title Here
AET65 API
Version 1.0
idvation GmbH
Otto-Hesse-Straße 19 / T5 Phone [phone]
D-64293 Darmstadt Fax [phone]
[email protected] www.idvation.com Title Here
Page 9 of 84
3.0. BSAPI.DLL Functions
3.1. General Description
BSAPI.DLL provides a set of functions which can read data from supported fingerprint sensor devices, and
which apply various biometric algorithms to these data.
The main header file declaring functions of BSAPI is bsapi.h. The header includes bstypes.h and bserror.h
which declare types and error status codes. The latter two headers are shared with the other libraries the
BSAPI consists of.
3.1.1. Error Handling
Almost all BSAPI.DLL functions return a status code ABS_STATUS. Code ABS_STATUS_OK (zero) means
success. All other values denote an error condition.
You may call ABSGetLastErrorInfo to retrieve more information about the error condition. Note that the
information is intended as a help for application and library developers and it's not intended to be presented to
end users.
If any BSAPI.DLL function fails, it frees any resources it might allocate. Values of output parameters are
defined only if the function succeeds i.e. if it returns ABS_STATUS_OK.
3.1.2. Memory Management
Some BSAPI.DLL functions allocate memory returned via output parameter to the calling application. The
application must use function ABSFree to free memory allocated by BSAPI.DLL in these cases.
3.1.3. Interactive Operations
Some of the BSAPI.DLL functions expect user’s interaction with FM. All these functions are collectively called
interactive operations in this document. Interactive operation functions share the way how the interaction is
achieved.
All those functions have pointer to structure ABS_OPERATION as their second parameter (just after handle
of a session). When you call any interactive operation function, it blocks until the operation finishes or until it is
canceled. While the operation is processing, callback specified by ABS_OPERATION is repeatedly called so
that the application can provide feedback to end-user.
Note that the callback implementation has some limitations. The behavior is not defined if you don’t respect
them:
•You cannot throw exceptions from the callback (if you use BSAPI from C++ or other language which
supports them).
•You cannot call majority of BSAPI functions from the callback. You can safely call only ABSFree,
ABSCancelOperation and ABSGetLastErrorInfo from the callback.
Since version 3.5 of BSAPI, the callback is always called from a thread context where the interactive operation
function has been called. (In older versions of BSAPI, this was not guaranteed).
You may cancel any running interactive operation with ABSCancelOperation if needed. You may call this
function either from the callback itself or from any other thread if you associated unique operation ID to the
operation you need to cancel.
Please note that structure ABS_OPERATION contains member Flags which can influence how the callback is
called. See description of ABS_OPERATION to get more information on this topic.
3.1.4. Multi-threading
In general, BSAPI.DLL is thread-safe. You can call BSAPI.DLL functions concurrently from multiple threads,

Document Title Here
AET65 API
Version 1.0
idvation GmbH
Otto-Hesse-Straße 19 / T5 Phone [phone]
D-64293 Darmstadt Fax [phone]
[email protected] www.idvation.com Title Here
Page 10 of 84
including multiple biometric operations on one FM. If multiple threads call BSAPI.DLL function which
communicates with FM, one of the calls is blocked (for caller it seems that the operation is still processing)
and it is resumed after the thread communicating with the device is finished.
If the function being suspended is an interactive operation, the application is informed about the situation via
the ABS_CALLBACK. See documentation of messages ABS_MSG_PROCESS_SUSPEND and
ABS_MSG_PROCESS_RESUME for more information.
The only exceptions are functions ABSInitialize and ABSTerminate. These two functions are not thread-
safe. This is usually not a problem, because they are called as part of application initialization and termination
respectively.
3.1.5. Anti-latent Checking
In general the goal of the anti-latent check is to minimize the negative impact of residual fingerprint left on the
surface of area sensor. This negative impact has two forms – security (risk of a false accept) and convenience
(risk of false reject due to the lowered image quality).
Note that for strip sensors, such checking is never performed because there is no danger, so for these
sensors the API automatically reports the last scan as not being latent.
There are two ways how to perform the anti-latent checking. The first one is built-in high level biometric
operations: enrollment and verification. I.e. calling ABSEnroll() or ABSVerify() automatically involves the anti-
latent checking and the function does not return with templates evaluated as latent ones. Instead it asks user
to clean sensor and scan finger again with appropriate callback messages. This implicit anti-latent checking
can be turned off and on by setting global parameter ABS_PARAM_LATENT_CHECK. By default the
checking is enabled.
The second way is to call ABSCheckLatent manually. BSAPI remembers automatically in a context of session
last scanned image, and when this function is called it checks whether that scan is or is not latent.
Note that the logic of each check (implicit or explicit with ABSCheckLatent) is as follows. The last scanned
image is compared with the last swipe which was considered as a valid one. If the two are same (according to
the latent check algorithm), the result of the check is positive. If the two scans differ, the last scan is
automatically stored as the last valid scan, so any subsequent checks mean that the last swipe is compared to
this last scan.
This has one side effect: you should not make multiple latent checks after single scan because only the first
anti-latent check will return any meaningful data. This includes implicit checking, so you should not call
manually ABSCheckLatent after ABSEnroll or ABSVerify unless you disable the implicit checking by the global
parameter ABS_PARAM_LATENT_CHECK.