Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Unique
moda 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
UID Client – Device interface RC1
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
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. 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
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.
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
2. Unsubscribe
3. Start Capture
4. Stop Capture
5. Force Capture
6. Get Frame
7. Get Sample
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.
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.
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.1 DM Startup
Application startup is like the VDM startup, except that the strategy on failure to
connect could be different.
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.
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.
The following diagram shows a timeline for Device Arrival, and Removal.
Time
Application Sequence of events:
1. Device Arrive Request
2. Device Arrive Request
2 8 10 3. Device Arrive Response
4. Device Arrive Response
5. Socket Connect
Device Manager
6. Socket Accept
7. Device Remove Request
5 9 8. Device Remove Request
1 4 9. Application Closes Socket
7 11
10. Device Remove Response
6 12 11. Device Remove Response
12. VDM Closes Socket
VDM
Device Object
Device
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.
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.
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.
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.
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>
</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.
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”
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.
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>
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.
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.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
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
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”.
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
complete event comes before the response, it means the event resulted from the
automatic capture.
<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.
<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.
<DeviceEventRequest requestId=””>
<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.
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
The following strings are used to enumerate the Biometric Modalities in this API.
• Face
• Iris
• Two Iris
• FingerPrint
• Fingerprint Slap
The following strings will be used for biometricPosition in the XML requests, events,
and responses.
• Unknown
• Right Thumb
• 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
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.
<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>
<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>