Aadhaar Biometric Capture Device API

  • Published on
    08-Apr-2015

  • View
    241

  • Download
    3

Embed Size (px)

Transcript

UIDAIUnique Identification Authority of India moda Planning Commission, Govt. of India 3rd Floor, Tower II, Jeevan Bharati Building, Connaught Circus, New Delhi 110001

AADHAAR BIOMETRIC CAPTURE DEVICE APIUID Client Device interface RC1 UIDAI, 2009 - 1010 Page 1 of 24

RC1

AADHAAR Biometric Capture Device API

Table of Contents1. INTRODUCTION ....................................................................................................................... 3 1.1 OBJECTIVE OF THIS DOCUMENT ............................................................................................ 3 1.2 INTERFACE OVERVIEW ......................................................................................................... 3 1.2.1 Device Manager ........................................................................................................... 4 1.2.2 Vendor Device Manager ............................................................................................... 4 1.2.3 Application .................................................................................................................... 5 1.3 SECURITY CONSIDERATIONS ................................................................................................ 5 2. API USAGE WORKFLOWS & EXAMPLES .............................................................................. 7 2.1 DISCOVERY AND STARTUP ................................................................................................... 7 2.1.1 DM Startup ................................................................................................................... 7 2.1.2 VDM Startup ................................................................................................................. 8 2.1.3 Application Startup........................................................................................................ 8 2.2 DEVICE MANAGEMENT ......................................................................................................... 8 2.2.1 Device Arrival ............................................................................................................... 8 2.2.2 Device Removal ........................................................................................................... 9 2.2.3 Device Discovery & PNP............................................................................................... 9 2.3 SAMPLE CAPTURE ............................................................................................................. 10 2.3.1 Auto Capture .............................................................................................................. 10 2.3.2 Forced Capture........................................................................................................... 10 2.4 FINGERPRINT CAPTURE ..................................................................................................... 10 3. API METHODS ....................................................................................................................... 11 3.1 API VERSION NUMBER ...................................................................................................... 11 3.2 BIOMETRIC DEVICE MANAGEMENT AND DISCOVERY .............................................................. 11 3.2.1 Connect ...................................................................................................................... 11 3.2.2 Device Arrival ............................................................................................................. 12 3.2.3 Device Removal ......................................................................................................... 13 3.2.4 Ping ............................................................................................................................ 14 3.2.5 VDM Events ............................................................................................................... 14 3.3 BIOMETRIC DEVICE COMMAND API METHODS AND NOTIFICATIONS ........................................ 14 3.3.1 Subscribe ................................................................................................................... 14 3.3.2 Start Capture .............................................................................................................. 15 3.3.3 Force Capture............................................................................................................. 15 3.3.4 Stop Capture .............................................................................................................. 16 3.3.5 Capture Complete....................................................................................................... 16 3.3.6 Detection .................................................................................................................... 16 3.3.7 User Feedback ........................................................................................................... 16 3.4 BIOMETRIC DEVICE VIDEO STREAMING AND SAMPLE API METHODS ....................................... 17 3.4.1 Get Frame .................................................................................................................. 18 3.4.2 Get Sample ................................................................................................................ 18 3.5 RETURN CODES ................................................................................................................ 18 3.6 DATA TYPES AND REPRESENTATION ................................................................................... 19 3.6.1 Biometric Modality Enumeration.................................................................................. 20 3.6.2 Biometric Position Enumeration .................................................................................. 20 3.6.3 SampleFormat Enumeration ....................................................................................... 21 3.6.4 Actionable User Feedback .......................................................................................... 21 4. NOTES & CLARIFICATIONS ................................................................................................. 22 4.1 SUPPORTING IRIS CAMERAS.............................................................................................. 22 4.2 SUPPORTING DIFFERENT VIDEO FORMATS ........................................................................... 22 4.2.1 Iris device showing video of the portion of the face...................................................... 22 4.2.2 Iris device showing two videos of the two eyes ............................................................ 23

UIDAI, 2009 - 2010

Page 2 of 24

RC1

AADHAAR Biometric Capture Device API

1.

Introduction

The Unique Identification Authority of India (UIDAI) has been created, with the mandate of providing a unique identity to all Indian residents. The UIDAI proposes to use biometrics to eliminate duplicates and ensure uniqueness during the enrolment process. Quality of collected biometric data is critical for the accuracy of de-duplication and a key component for the success of the program. While the program will be using the biometric capture devices from different vendors, it is critical to maintain consistent data collection process. This will be achieved by standardizing the biometric capture process flow around the UID Enrolment Software. This Biometric Capture Device API is to be used by the UID Enrolment Software to communicate with the Biometric Capture Devices.

1.1

Objective of this document

The previous version of this document was provided for feedback from device vendors and application developers. This document incorporates the feedback received, and is now available for implementation. This version of the API will be used for the initial rollout of the UID enrolment client. This is Version 1.0 of this API.

1.2

Interface Overview

The Aadhaar client interacts with the biometric devices through a two-layer structure, which is described in the following diagram.

The following components are clearly identified:

RC1

AADHAAR Biometric Capture Device API

1. DM: The vendor independent Device Manager, which orchestrates the discovery, of the VDMs by the application, and manages connectivity to the VDM. 2. VDM: The Vendor Device Manager, provided by the device vendor, which manages the device, and allows for biometric data capture. 3. Application: The Application that needs to use the biometric devices for capture. The UID Enrolment Software is an example of such an application. The API is specified as communication protocol between the Application, the DM, and the VDM. All communication is over TCP/IP sockets. This serves two purposes. First is isolation: the software from each vendor will be executed in a separate process. Second is platform-independence: the devices will be directly accessible from the different platforms and environments: native, Java, .NET. The communication will be done by exchanging the XML messages. The API method will be executed by sending the request message and waiting for the corresponding response message. The response will be sent after the method execution is completed.Note, it is possible that the next request will be sent without waiting for the previous request to complete, and that multiple API methods, even of the same type, could be executed in parallel. For example the application can issue Subscribe request and immediately after that StartCapture request, without waiting for the response to the Subscribe request. Another example would be that the application can issue two Get Frame requests, in order to maintain pending Get Frame request while the previous Get Frame requests is being processed and responded.

There will be two types of API methods: commands and notification events. The command API methods are initiated by the Application, while the event API methods are initiated by the Biometric Capture Device. Video stream from the Biometric Capture Device will be delivered using the binary protocol over a separate channel. The final captured biometric samples will also be delivered using the binary protocol through a separate channel. The request and response messages for both video stream and biometric samples will be encoded using ASN1 BER. See http://en.wikipedia.org/wiki/Asn1 1.2.1 Device Manager The DM service will be provided by the UID. The DM responds to the following requests: 1. Connect 2. Device Arrival 3. Device Removal 4. Ping The DM provides applications with the following events. 1. Device Arrival 2. Device Removal The DM listens on a TCP/IP port (specified later in this document). Applications and the VDMs must connect to this port once, and communicate over this open connection. 1.2.2 Vendor Device Manager The VDM must manage the state of the device, including the maintenance of state within the DM. In addition, it must perform the actions requested by the application. The VDM must support the following commands: 1. Subscribe

UIDAI, 2009 - 2010

Page 4 of 24

RC1 2. 3. 4. 5. 6. 7. Unsubscribe Start Capture Stop Capture Force Capture Get Frame Get Sample

AADHAAR Biometric Capture Device API

The following notifications are provided by the VDM to the application 1. Capture Complete 2. Detection 3. User Actionable Feedback Certain operations are not provided in this API, instead the separate configuration utility application provided by the vendor is expected to provide a graphical user interface for users to manage the device if required. The UI must facilitate the following operations: 1. Configuration, including port number override 2. Device Self Test 3. Device Reset / Reinitialization 4. Device Calibration 5. Device Startup 6. Device Shutdown If the device does not support any of these operations, the feature is not required in the UI. For instance, a device that does not support a soft-shutdown would not provide such an option in the UI. The vendor must provide installer (and uninstaller) for the VDM and configuration utility (if any). The vendor may chose to complete configuration at installation time. The VDM must maintain an open socket for accepting commands from the Application. The application is expected to connect to this socket, and exchange commands, and events over this connection. A separate socket is to be provided for Video streams, and Biometric Samples. This connection must be maintained only for the duration of capture, and transmission of the Biometric Sample. 1.2.3 Application The Application must connect to the DM to discover the biometric devices. Once discovered, the application must connect to the required devices. These connections are maintained for the life of the application, and the application must expect to receive notifications and events about the device arrivals and removals during this time.

1.3

Security Considerations

We would like to ensure that the UIDAI is able to validate that the data transmitted by the client is indeed the same data captured by the device. At this time, this is not mandatory, but we expect to make this mandatory in the near future. A packet containing the biometric sample, the capture time stamp, and the device id should be signed on the device itself. The UIDAI should be able to validate this

UIDAI, 2009 - 2010

Page 5 of 24

RC1

AADHAAR Biometric Capture Device API

signature. It should also be possible to invalidate a specific device in case the key is compromised. This API will be modified appropriately to capture this additional information.

UIDAI, 2009 - 2010

Page 6 of 24

RC1

AADHAAR Biometric Capture Device API

2.

API Usage Workflows & Examples

This section discusses how this API could be used by an application to connect with, and capture biometric samples from biometric devices. These workflows are indicative, and provided for a better understanding of the use case of this API. Other uses may be made of the API, and the vendors should not assume only these workflows.

2.1

Discovery and Startup

The DM orchestrates the discovery of the devices by the application. On initialization, the DM listens to a port that is either specified in a configuration file, or that lies within a well-known range of port addresses. Similarly, on initialization, the VDM, and applications must follow the same sequence to connect to the DM on this port. On connection, the VDM (or applications) register with the DM by sending a message that contains their details. The DM responds with similar details, completing the connection. The following sections contain more details for each of these programs. 2.1.1 DM Startup On initialization, the DM goes through the following steps: 1. Check configuration file for port number. 2. If present, attempt to listen on this port. 3. If not present, scan...