24
© UIDAI, 2009 - 1010 Page 1 of 24 moda AADHAAR BIOMETRIC CAPTURE DEVICE API UID Client Device interface RC1 UIDAI Unique Identification Authority of India Planning Commission, Govt. of India 3rd Floor, Tower II, Jeevan Bharati Building, Connaught Circus, New Delhi 110001

Aadhaar Biometric Capture Device API

Embed Size (px)

Citation preview

Page 1: Aadhaar Biometric Capture Device API

© UIDAI, 2009 - 1010 Page 1 of 24

moda

AADHAAR BIOMETRIC

CAPTURE DEVICE API UID Client – Device interface RC1

UIDAI

Unique Identification Authority of India

Planning Commission, Govt. of India

3rd Floor, Tower II, Jeevan Bharati Building,

Connaught Circus,

New Delhi 110001

Page 2: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 2 of 24

Table of Contents

1. 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

Page 3: Aadhaar Biometric Capture Device API

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:

Page 4: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 4 of 24

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

Page 5: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 5 of 24

2. Unsubscribe

3. Start Capture 4. Stop Capture

5. Force Capture 6. Get Frame

7. Get Sample

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

Page 6: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 6 of 24

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.

Page 7: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 7 of 24

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 the well

known list of ports, and attempt to listen to each port in turn.

4. On success, wait for incoming connections.

5. On failure, report an error to the

user, and allow the user to

configure the port number.

Page 8: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 8 of 24

2.1.2 VDM Startup

On initialization, the VDM goes through the following steps:

1. Check configuration file for port number.

2. If present, attempt to connect to

DM on this port.

3. If not present, scan the well known

list of ports, and attempt to connect

to each port in turn.

4. On connection, send a CONNECT

message to the DM. The DM must respond with an OK. If the OK is

not received, connect to the next

port.

5. If a connection cannot be

established wait for a little while,

and then, repeat the procedure.

Start

1. Is port specified

2. Connect to specified port

Success?N

3. Connect to

each port in range

Send Connect, Wait for response

Y

N

Success

Y

Success?

Send Connect, Wait for response

All Ports Tested?

Y

5. Wait and start again

N

2.1.3 Application Startup

Application startup is like the VDM startup, except that the strategy on failure to

connect could be different.

2.2 Device Management

The DM is responsible for managing the list of all connected applications, VDMs, and

devices. Whenever a device arrives, it must register with the DM, and continue to send

a heartbeat event at regular intervals. Failure to send the heartbeat is treated as a

removal event! The DM sends a list of all connected devices to the application after the

initial connection, by forwarding stored Arrival events.

2.2.1 Device Arrival

When the VDM senses that a device under it’s control is connected to the system, it

creates a Device Arrival event and sends it to the DM. The arrival event contains information about the device, and it’s capabilities. This allows the application to choose

the appropriate sample size for display and capture. The DM must acknowledge the

receipt of this event, forward it to all applications, and maintain a copy of this event (for

all applications that may connect in the future).

The following steps are envisioned, after initial startup and connection to the DM:

1. VDM detects a device connected to it.

2. VDM sends an Arrival event to the DM.

3. DM forwards the Arrival event to all the applications currently connected. The following diagram indicates a possible sequence of events.

Page 9: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 9 of 24

2.2.2 Device Removal

When the VDM senses that a device under it’s control is disconnected from the system,

it sends a Device Remove event to the DM. The DM must remove the reference to the event, and forward to all connected applications.

2.2.3 Device Discovery & PNP

The following diagram shows a timeline for Device Arrival, and Removal.

Application

VDM

Device Object

Device

1

2

4

5

6

Sequence of events:

1. Device Arrive Request 2. Device Arrive Request

3. Device Arrive Response

4. Device Arrive Response

5. Socket Connect

6. Socket Accept

7. Device Remove Request

8. Device Remove Request

9. Application Closes Socket 10. Device Remove Response

11. Device Remove Response

12. VDM Closes Socket

11

10

12

9

7

8

Time

Device Manager

Page 10: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 10 of 24

2.3 Sample Capture

An application connects to the DM / VDM combination to provide biometric capture

capabilities to the user. This can be done in one of 2 ways – auto capture, and forced capture. While the scenarios described here provide a continuous video stream for user

feedback, it is not a requirement that the application consume this stream.

2.3.1 Auto Capture

The Application subscribes to various events from the device, which allow it to provide

a useful interface to the user. The application then sends a StartCapture event to the

device, which provides a video stream, and subscribes the application to the

CaptureComplete event.

The application is expected (not required) to consume the video stream one frame at a time by sending GetFrame requests. Multiple GetFrame requests can be queued, and

the device will respond to each request with a frame. Once capture is completed, the device sends a capture complete message to the application. The application must then

use a GetSample request to get the biometric sample.

2.3.2 Forced Capture

If the device supports forced capture, the application may send a ForceCapture event to

the device. The device must respond with a CaptureComplete event. Following this, the

application must get the sample through a GetSample request.

2.4 Fingerprint Capture

Based on the API, here is an expected series of interactions for the capture of a fingerprint sample.

Application

Device Object

Device

Sequence of events:

1. Start Capture Request

2. Start Capture Response

3. Video Socket Connect 4. Video Socket Accept

5. Capture Complete Event Request

6. Application Closes Video Socket

7. Application Reads Sample

8. Capture Complete Event Response

9. Device Object Closes Video Socket

10. Sample is no longer available

10

Time

1

2

3

4 5

6 7 8

9

Page 11: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 11 of 24

3. API Methods

This chapter specifies the request and response messages that are exchanged between

the Application, DM and VDM. All messages are in XML. All requests and responses carry a requestId, which is a numeric value (128 bit),

represented as a 36 character UUID format string in XML. Since the API is

asynchronous, the requestId is used to connect requests with the appropriate response.

The VDM, DM and Application must not use requestId outside the scope of a request,

since this could be recycled.

3.1 API Version Number

The version number for the current API is 1.0. The version number is included in every

API message.

3.2 Biometric Device Management and Discovery

The DM service provided by the UID, is responsible for the following:

- Listen on the device arrival and removal events from the vendor-specific device

manager (VDM). - Maintain the list of the all the supported biometric devices available for the

applications. - Notify the applications about arrival and removal of the supported devices (

PNP).

The DM listens on the first available port in a port range published by the UIDAI. At this

time, the port range from 4401 to 4410 inclusive is defined for this purpose. At

startup, the DM must attempt to listen on one of these ports. In case these ports are not

available, the local administrator may assign an available port.

All applications and VDMs, that desire communication with the DM, will attempt to

connect to the ports in this range. On establishing a TCP/IP connection, they must check

that it is the DM which is listening on that port. In case they fail to connect, they must provide a graphical user interface to configure the port.

The following commands and events are supported.

3.2.1 Connect

On establishing connection with the DM, the application, and VDMs must ensure that

they are connecting with a DM, and exchange certain configuration information. <DeviceManagerEventRequest requestId=”” version=””>

<Connect apiVersion=””>

<VDM vendor=”” vdmName=”” vdmVersion=””/>

<APP vendor=”” appName=”” appVersion=””/>

</Connect>

Page 12: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 12 of 24

</DeviceManagerEventRequest>

<DeviceManagerEventResponse requestId=””>

<Return value=””/>

<ConnectResponse apiVersion=”” vendor=”” dmName=””

dmVersion=”” heartBeat=””/>

</DeviceManagerEventResponse>

In addition to exchanging the names of the vendors, version numbers of the API, and the

software, the DM responds with a heartbeat value, which is the maximum requested

time between pings (specified in seconds). Applications must provide a <APP> element,

while VDMs must provide a <VDM> element.

3.2.2 Device Arrival

The event notifies the device manager, and the application about a device arrival. The

VDM originates this event, and sends it to the DM, which in turn forwards it to the

Application. <DeviceManagerEventRequest requestId=””>

<Arrival

vdmName=””

deviceURI=””

modality=”Fingerprint Slap”

deviceMake=”Manufacturer Name”

deviceModel=”DEVICE MODEL NAME / IDENTIFIER”

hardwareRev=”1.0.0”

firmwareRev=”1.0.1”

serialNumber=”ABC1234567”

>

<Capabilities

detection=”True”

video=”True”

autoCapture=”True”

disableAutoCapture=”True”

userFeedback=”True”

graphicalFeedback=”False”

>

<VideoFormats>

<VideoFormat videoFormatId =”1”

modality=”Fingerprint Slap”>

<FrameType

biometricPosition=”Any”

size=”800,750”

pixelFormat=”Gray8”

pixelResolution=”250ppi”

/>

</VideoFormat>

</VideoFormats>

<SampleFormats>

<SampleFormat formatId=”1”

format=”ISO IEC 19794-4 2005”

views=”1”

Page 13: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 13 of 24

size=”1600,1500”

pixelResolution=”500ppi”

/>

</SampleFormats>

</Capabilities>

</Arrival>

</DeviceManagerEventRequest>

<DeviceManagerEventResponse requestId=””>

<Return value=”1” failureReason=”0”/>

</DeviceManagerEventResponse>

deviceURI is URI, where the device listens to connection from the application. It is also

used to uniquely identify the device object in the system.

modality is the biometric modality, for example: “Fingerprint” for single-finger devices,

“Fingerprint Slap” for the slap devices, “Iris”, “Face”.

deviceMake is the manufacturer or brand of the device.

serialNumber is the serial number of the device. The combination of deviceMake,

deviceModel and serialNumber should globally uniquely identify the specific device. This is important, for example to identify all biometric samples that originated from the

specific device, for example in the case of device malfunction.

Capabilities

- detection tells whether the device can automatically detect the presence of the

biometric sample, i.e. if the fingerprint reader can detect if the finger is placed on

the platen, even if the device is not capturing the data.

- video tells if the device can produce a video stream during capture, useful for the

operator.

- autoCapture tells whether the device can capture the biometric sample

automatically.

- disableAutoCapture tells whether the automatic capture can be disabled. - userFeedback tells if the device can provide the actionable user feedback,

compliant with this specification. - graphicalFeedback tells if the device can provide the additional graphical

feedback for the operator in the video.

The Device Arrival event should be sent after the device component starts listening for

the connections on the socket addressed by the deviceURI.

3.2.3 Device Removal

The event notifies the device manager, and the application about a device removal. The

VDM originates this event, and sends it to the DM, which in turn forwards it to the

Application. <DeviceManagerEventRequest requestId=””>

<Removal deviceURI=””/>

</ DeviceManagerEventRequest>

<DeviceManagerEventResponse requestId=””>

<Return value=”” failureReason=”0”/>

</DeviceManagerEventResponse>

Page 14: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 14 of 24

The device component of the removed device should be listening on the deviceURI until

the response is received. After the response is received it can close all sockets of this device that not closed already by the application.

3.2.4 Ping

This is used as a heartbeat event, to notify the DM that a VDM, is still alive. <DeviceManagerEventRequest requestId=””>

<Ping vdmName=””/>

</DeviceManagerEventRequest>

<DeviceManagerEventResponse requestId=””>

<Return value=”” failureReason=””/>

</DeviceManagerEventResponse>

The only failure condition is if the device was previously removed, or never registered.

3.2.5 VDM Events

The VDM establishes a connection with the DM on startup. The VDM sends device arrival and removal events to the DM on this connection, and expects responses on the

same connection. At startup, the VDM will send the device arrival event for each device already present in the system. Every time the PNP device is connected the VDM will

send device arrival event, and every time the PNP device is disconnected the VDM will

send device removal event.

3.3 Biometric Device Command API Methods and Notifications

When the application needs to work with the device, it opens the socket to the location

pointed by the deviceURI in the Arrival event from the Device Manager. Opening the

socket effectively opens the device. Only one application can open the device. The

device should reject the connections on the deviceURI, until the socket is closed.

3.3.1 Subscribe

Change the subscription to the device events: uses by the application to subscribe or

unsubscribe to the specific categories of the device events. Some events will be fired only when capture is in progress. <DeviceCommandRequest requestId=””>

<Subscribe>

<Event eventCategory=”Detection”/>

<Event eventCategory=”UserFeedback”/>

</Subscribe>

</DeviceCommandRequest>

<DeviceCommandResponse requestId=””>

<Return value=”1” failureReason=”0”/>

<State detected=”False”/>

</DeviceCommandResponse>

Expected behaviour: change the list of subscribed events to the list in this command

request. The events to which the device was previously subscribed can be sent by the

Page 15: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 15 of 24

device until the response is sent. Any new events can only be fired after the response is

sent. If the command is subscribing for the notification to the change of state the response should include the corresponding state at a time of response.

The following EventCategories are supported.

eventCategory Events Expected Notes

Detection Detection

UserFeedback UserFeedback

3.3.2 Start Capture

Starts the capture process, also subscribes to Capture Complete and optionally User

Feedback events. <DeviceCommandRequest requestId=””>

<StartCapture

biometricPosition=”Right Thumb”

allowManualCapture=”True”

[videoFormatId=”1”]

sampleFormatId=”1”

>

[<MissingBiometrics>

<MissingBiometric biometricPosition=”Left Middle”/>

<MissingBiometrics>]

</StartCapture>

</DeviceCommandRequest>

<DeviceCommandResponse requestId=””>

<Return value=”” failureReason=””/>

[<Video videoURI=””/>]

</DeviceCommandResponse>

Expected behaviour: starts the capture process. Any capture related event can be sent

only after the response to the start capture event. MissingBiometrics is optional. Attribute sampleFormatId is indicating the requested output sample format. Optional

attribute videoFormatId is indicating that the video stream is requested, and the desired video format referred by videoFormatId in the Device Arrival VDM event in

“Capabilities/videoFormats/videoFormat”.

3.3.3 Force Capture

Forces manual capture. Should not be issued when the capture is not started. <DeviceCommandRequest requestId=””>

<ForceCapture/>

</DeviceCommandRequest>

<DeviceCommandResponse requestId=””>

<Return value=”1” failureReason=”0”/>

</DeviceCommandResponse>

Expected behaviour: force manual capture, whether the automatic capture is on or off.

The capture complete event is sent right after the response to this event. If the capture

Page 16: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 16 of 24

complete event comes before the response, it means the event resulted from the

automatic capture.

3.3.4 Stop Capture

Stops (cancels) current capture <DeviceCommandRequest requestId=””>

<StopCapture/>

</DeviceCommandRequest>

<DeviceCommandResponse requestId=””>

<Return value=”1” failureReason=”0”/>

</DeviceCommandResponse>

Expected behaviour: stops capture process. No capture complete event should come

after the response to Stop Capture.

3.3.5 Capture Complete

<DeviceEventRequest requestId=””>

<CaptureComplete sampleURI=””/>

</DeviceCommandRequest>

<DeviceEventResponse requestId=””>

<Return value=”” failureReason=””/>

</DeviceCommandResponse>

Expected behaviour: the event should be sent upon successful completion of the

capture. The biometric sample should be available until the response is received: as a

result the device may have to maintain multiple samples and make them available at the

different URIs.

Samples must be provided in the format indicated by sampleFormatId in the Start

Capture request.

3.3.6 Detection

<DeviceEventRequest requestId=””>

<Detection detected=”True”/>

</DeviceCommandRequest>

<DeviceEventResponse requestId=””>

<Return value=”” failureReason=””/>

</DeviceCommandResponse>

Expected behaviour: notifies of the change of the state whether the biometric is

detected by the device (for example if the finger is placed or removed from the reader).

Usage example: the application needs to capture one finger, followed by the other. The

application issues capture request, which completes. The now application needs to wait for the finger removed event before issuing the next capture request, to make sure that

the same finger is not captured again immediately.

3.3.7 User Feedback

<DeviceEventRequest requestId=””>

Page 17: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 17 of 24

<UserFeedback>

<Message biometricPosition=”Right Thumb” action=”Other”

description=”Display this”/>

<!-- biometricPosition and description are optional -->

</UserFeedback>

</DeviceCommandRequest>

<DeviceEventResponse requestId=””>

<Return value=”” failureReason=””/>

</DeviceCommandResponse>

Expected behaviour: provide the actionable feedback.

3.4 Biometric Device Video Streaming and Sample API Methods

The Video Stream will be retrieved using the binary protocol for sending video frames (with the actual image data represented in ISO 19794-x) over the socket referenced by

videoURI using the pull model. The application will maintain pending Get Frame

requests for all the time that it can keep-up with the visualization.

The sample will be retrieved over the socket referenced by sampleURI, with the actual

image data represented in ISO 19794-x. The requests and the responses are represented in ASN1 BER encoding. The rationale

in choosing BER encoding is to transfer the binary data in the self-descriptive extensible

data format with the reasonably low overhead.

MessageType ::= ENUMERATED { Request, Response }

RequestCode ::= ENUMERATED { GetSample, GetFrame, ... }

RequestMessage ::= SEQUENCE {

messageType MessageType ::= Request,

requestCode RequestCode,

requestId OCTET STRING,

}

Return ::= SEQUENCE {

returnValue INTEGER { Success(1), Failed(2) }

(Success | Failed),

failureReason INTEGER

}

BiometricSample ::= SEQUENCE {

format OCTET STRING,

data OCTET STRING

}

ResponseMessage ::= SEQUENCE {

messageType MessageType ::= Response,

requestId OCTET STRING,

return Return,

...

}

Page 18: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 18 of 24

3.4.1 Get Frame

RequestMessage ::= SEQUENCE {

messageType MessageType ::= Request,

requestCode RequestCode ::= GetFrame,

requestId OCTET STRING

}

ResponseMessage ::= SEQUENCE {

messageType MessageType ::= Response,

requestId OCTET STRING,

return Return,

biometricSample BiometricSample OPTIONAL }

3.4.2 Get Sample

RequestMessage ::= SEQUENCE {

messageType MessageType ::= Request,

requestCode RequestCode ::= GetSample,

requestId OCTET STRING

}

ResponseMessage ::= SEQUENCE {

messageType MessageType ::= Response,

requestId OCTET STRING,

return Return,

biometricSample BiometricSample OPTIONAL }

3.5 Return Codes

The following return codes are standard for all the Bio API requests.

0 Not Used

1 Success

2 Failed

The following failure reasons are also used for all Bio API requests

0 Success

1 Internal Error – Unknown

2 Aborted

3 Invalid Request –XML Error

4 Invalid Request –Parameter value invalid

5 Invalid Request – Capture already in progress

6 Invalid Request – Capture is not in progress

7 Unexpected Error – Unable to access Biometric Data

8 Unable to perform request

Page 19: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 19 of 24

3.6 Data Types and Representation

The following table documents the various attributes specified in the XML, their data

types, and representation.

Attribute Type Representation Notes action String Ex. “MoveLeft”

allowManualCapture Boolean String

Ex. “True”

appName String String

For ex. “UIDAI Enrolment Client”

appVersion String String For ex. “EC 1.0 2010/06/01”

autoCapture Boolean String

For ex. “True”

Is the device capable of

automatically capturing a

biometric sample.

biometricPosition String String

Used to specify which specific

biometric is being captured.

Fully specified in the

following table.

description String Display as-is to the user. Must be in English. Used

when no standard message is

available.

detected Boolean String

Ex. “False”

detection Boolean String

For ex. “True”

Device capability that

indicates if a device can detect

the presence of biometrics sample.

deviceMake String String Device Manufacturer

deviceModel String String Device Model Name

deviceURI URI A standard resource identifier. Expected

protocol is tcp, which may be omitted.

For ex. ‘127.0.0.1:1234’

It is preferred that the ip

address, and port number are

specified to reduce confusion

between multiple network

adapters.

The deviceURI is used to

uniquely identify the device

within the system.

disableAutoCapture Boolean String

For ex. “True”

Can autocapture be disabled?

dmName String String

For ex. “UID Biometric Device Manager”

dmVersion String String

For ex. “DM 1.0 2010/06/01”

firmwareRev String String Firmware Revision for the

device

graphicalFeedback Boolean String

For ex. “True”

Can the device provide

additional feedback to the

operator within the video.

hardwareRev String String Hardware Revision for the

device

heartbeat Number String For ex. “60”

Maximum number of seconds between messages between

the component and the DM.

modality Enum String

For ex. “Fingerprint”

Allowed values

“Iris”, “Fingerprint”, “Face”

Page 20: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 20 of 24

Attribute Type Representation Notes pixelFormat String String

For ex. “Gray8”

Possible values:

pixelResolution String String For ex. “500ppi”

Device resolution in Pixels per inch.

requestId 128 bit

Integer

36 character ASCII string (UUID format).

For ex. 01234567-89AB-CDEF-0123-456789ABCDEF

UUID is documented in RFC

4122

sampleFormatId String String

serialNumber String String Serial Number for the device.

Also referred to as deviceId

size integer, integer

String. For ex. “800,750”

Height, width in pixels.

userFeedback Boolean String

For ex. “True”

Can the device provide

actionable user feedback to

the application.

vdmName String String The name provided to the

VDM.

vdmVersion String String

Vendor String String

For ex. “UIDAI”

The vendor who supplied the

specific component.

Version String String

For ex. “1.0”

The API Version number is

explicitly included in each

XML request. It is also

explicitly included in the

Connect request, and

response.

Video Boolean String

For ex. “True”

Is the device capable of

providing a video preview.

videoFormatId String String Provided by the VDM to distinguish different video

formats.

videoURI URI See deviceURI Provided by the VDM for an

application to consume video,

and biometric samples

Views Integer String

For ex. “1”

Number of views per sample?

3.6.1 Biometric Modality Enumeration

The following strings are used to enumerate the Biometric Modalities in this API.

• Face

• Iris

• Two Iris

• FingerPrint

• Fingerprint Slap

3.6.2 Biometric Position Enumeration

The following strings will be used for biometricPosition in the XML requests, events,

and responses.

• Unknown

• Right Thumb

Page 21: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 21 of 24

• Right Index

• Right Middle

• Right Ring

• Right Little

• Left Thumb

• Left Index

• Left Middle

• Left Ring

• Left Little

• Right Slap

• Left Slap

• Both Thumbs

• Left Iris

• Right Iris

• Both Iris

• Face

3.6.3 SampleFormat Enumeration

The following sampleFormats are supported.

• ISO IEC 19794-4 2005

• ISO IEC 19794-5 2005

• ISO IEC 19794-6 2005

3.6.4 Actionable User Feedback

Action Meaning PresentBiometric The device is unable to detect any biometric sample, while it is

expecting one.

The subject should be told to do the needful.

MoveLeft The device expects the subject to move to their (subject’s) left.

MoveRight The device expects the subject to move to their (subject’s)

right.

PressHarder The device is unable to get a good sample because the subject is

not pressing hard enough. The subject must be assisted in

pressing harder on the device.

PressLighter The device is unable to get a good sample because the subject is pressing too hard. The subject must be requested to apply less

pressure.

Other The action is not covered. Display the description to the operator. The description must be in English.

Page 22: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 22 of 24

4. Notes & Clarifications

4.1 Supporting IRIS Cameras

Device

Type

Video Streams Capture Requests /

Events

Notes

2 Eye 2, 1 for each eye 2 requests, and 2

events, 1 for each

eye

1 eye is captured at a time,

directly controlled by the

application.

2 Eye 1, 1 eye at a time 1 capture request,

2 capture complete

events.

1 eye is captured at a time,

under device control

2 Eye 1 – both eyes together

1 capture request, 1 capture complete

event

Both eyes are captured simultaneously

1 Eye 1 Video Stream 2 capture requests,

and 2 capture

complete events, 1

for each eye

1 eye is captured at a time,

directly controlled by the

application. The application

must specify which eye is

being captured. The

biometric position is encoded

into in the sample.

4.2 Supporting Different Video Formats

Example: two-eye Iris camera can show video of either portion of the face with two eyes

in it or the two eyes separately. In the second case the frame header describes which

eye is shown in this frame. The application needs to distinguish between the two types of the devices before

opening the device, to choose which device to open and to show the appropriate UI. This information is provided in the Device Arrival event from the VDM.

4.2.1 Iris device showing video of the portion of the face

The Device Arrival event: <DeviceManagerEventRequest requestId=”999”>

<Arrival

deviceURI=”localhost:1234”

modality=”Two Iris”

deviceMake=”LG”

deviceModel=”iCAM TD100”

hardwareRev=”1.0.0”

firmwareRev=”1.0.1”

serialNumber=”ABC1234567”

>

Page 23: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 23 of 24

<Capabilities

detection=”True”

video=”True”

autoCapture=”True”

disableAutoCapture=”True”

userFeedback=”True”

graphicalFeedback=”True”

>

<VideoFormats>

<VideoFormat videoFormatId =”1”

modality=”Face Partial”>

<FrameType size=”640,240”

pixelFormat=”RGB32”

pixelResolution=”Unspecified”

/>

</VideoFormat>

</VideoFormats>

<SampleFormats>

<SampleFormat sampleFormatId=”1”

format=”ISO IEC 19794-6 2005”

views=”2”

size=”480,480”

pixelResolution=”500ppi”

/>

</SampleFormats>

</Capabilities>

</Arrival>

</DeviceManagerEventRequest>

4.2.2 Iris device showing two videos of the two eyes

The Device Arrival event: <DeviceManagerEventRequest requestId=”999”>

<Arrival

deviceURI=”localhost:1234”

modality=”Two Iris”

deviceMake=”Manufacturer Name”

deviceModel=”I SCAN 2”

hardwareRev=”1.0.0”

firmwareRev=”1.0.1”

serialNumber=”ABC1234567”

>

<Capabilities

detection=”True”

video=”True”

autoCapture=”True”

disableAutoCapture=”True”

userFeedback=”True”

graphicalFeedback=”False”

>

Page 24: Aadhaar Biometric Capture Device API

RC1 AADHAAR Biometric Capture Device API

© UIDAI, 2009 - 2010 Page 24 of 24

<VideoFormats>

<VideoFormat videoFormatId=”1” modality=”Two Iris”>

<FrameType biometricPosition=”Left Eye”

size=”240,240”

pixelFormat=”Gray8”

pixelResolution=”250ppi”

/>

<FrameType biometricPosition=”Right Eye”

size=”240,240”

pixelFormat=”Gray8”

pixelResolution=”250ppi”

/>

</VideoFormat>

</VideoFormats>

<SampleFormats>

<SampleFormat sampleFormatId=”1”

format=”ISO IEC 19794-6 2005”

views=”2”

size=”480,480”

pixelResolution=”500ppi”

/>

</SampleFormats>

</Capabilities>

</Arrival>

</DeviceManagerEventRequest>