Professional Documents
Culture Documents
Contents
1 Introduction ................................................................................................................................................... 4
1.1 Aadhaar Authentication at a Glance ............................................................................................. 4
1.2 Target Audience and Pre-Requisites............................................................................................ 4
2 Registered Devices ...................................................................................................................................... 5
2.1 Public Devices ....................................................................................................................................... 5
2.2 Registered Devices .............................................................................................................................. 5
2.3 PID Creation – Signing and Encrypting Biometrics ................................................................ 8
2.4 RD Service APIs .................................................................................................................................... 9
2.4.1 Interface Methods .................................................................................................................... 10
2.4.2 Input/Output XMLs ................................................................................................................. 10
2.5 Levels of Device Compliance ........................................................................................................ 13
2.5.1 Level 0 Compliance ................................................................................................................. 13
2.5.2 Level 1 Compliance ................................................................................................................. 13
2.6 Registration and Key Management............................................................................................ 13
2.7 Certificates, Keys Policies .............................................................................................................. 13
3 Sequence Diagrams.................................................................................................................................. 14
4 “Certified RD Services" Registry ......................................................................................................... 15
5 Device Discovery....................................................................................................................................... 17
5.1 Linux & Windows Discovery & API Calling............................................................................. 17
5.2 Android Discovery & API Calling ................................................................................................ 19
6 Keystore Security ..................................................................................................................................... 20
7 Register & DeRegister API..................................................................................................................... 21
7.1 Register API ........................................................................................................................................ 21
1 Introduction
The Unique Identification Authority of India (UIDAI) has been created, with the mandate of
providing a Unique Identity (Aadhaar) to all Indian residents. The UIDAI provides online
authentication using demographic and biometric data.
Aadhaar authentication is the process wherein Aadhaar Number, along with other attributes,
including biometrics, are submitted online to the Aadhaar system for its verification on the
basis of information or data or documents available with it. During the authentication
transaction, the resident’s record is first selected using the Aadhaar Number and then the
demographic/biometric inputs are matched against the stored data which was provided by
the resident during enrolment/update process.
This document assumes that readers are fully familiar with Aadhaar authentication model,
related terminology, and authentication API technology details. Before reading this
document, readers must read the Aadhaar authentication API specification available at
http://uidai.gov.in/images/FrontPageUpdates/aadhaar_authentication_api_2_0_1.pdf
IMPORTANT NOTE: In this document, term “Device Provider” used to refer to a device
manufacturer or any agency who has partnership with the manufacturer to manage device
certification and related software/security aspects of registered devices. Device provider
should be an entity registered in India and is responsible for STQC certification, device key
management (as per this spec), and any security or other responsibilities set forth by UDIAI
as part of device provider ecosystem rules.
2 Registered Devices
This chapter describes the specification in detail for registered devices for biometric device
providers and also provides details on registration flow before these can be used with larger
host devices.
Before understanding registered devices and the need for it, it is important to understand
how public devices work.
Public devices are biometric capture devices that provide Aadhaar compliant biometric data
to the application, which, in turn encrypts the data before using for authentication purposes.
Currently AUA/Sub-AUA applications manage the biometric capture feedback user
experience, any validation, and encryption of PID block. With public devices, providers may
or may not provide an easy to use libraries to application developers.
Several security measures are taken to ensure strong transaction security and end to
end traceability even in public devices. These security measures fall into prevention and
traceability. These include deploying signed applications, host and operator authentication
by AUA, usage of multi-factor authentication, resident SMS/Email alerts on authentication,
biometric locking, encryption/signing of sensitive data, and so on.
Following is the logical diagram of a registered device (for illustration purposes only, actual
HW design may differ). Detailed sequence diagrams are given later in the document.
ASA
Server
RD Service
There is no requirement for entire registered device to be physically separate unit. This is to
ensure all devices (integrated and discrete) such as external devices connected to
phones/laptops as well as biometric embedded phones, etc. can all act as registered devices.
NOTE: Rest of the document uses the term “RD Service” to refer to device provider’s
registered devices service that allows capture and processing of biometrics. This RD
Service then returns encrypted PID block containing signed biometrics (using device private
key within the registered devices secure zone) back to the calling application. All registered
devices providers MUST provide certified RD Service for various supporting operating
systems so that applications can integrate easily in a secure and standard way without
needing to embed any special software within applications. Providers also must ensure
that RD service can be run under separate user not needing root/admin privileges.
UIDAI does not mandate any specific hardware design and device providers are
expected to innovate appropriate form factors for market use. Key design mandate is that
registered devices MUST securely sign the biometric data, form the encrypted PID
block within the RD Service and give it back to application for use within Aadhaar
authentication.
It is important to note that it is in device provider’s interest to ensure the above two
items are implemented securely since any compromise on these will result in fraudulent
activities signed using the device provider key. As per IT Act it is essential for the key
owners (device provider) to protect the signature key and take responsibility for any
compromise.
Note: Device public-private key generation/initialization and signing of device public key
with device provider key can be performed at any point of time during device’s lifecycle.
However, the specific device key pair used to sign biometrics for the purposes of
Aadhaar authentication should be used for UIDAI purposes only.
Process of PID creation within RD Service is described below:
1. RD Service provides standard APIs as per UIDAI standards (see next section for
details) to application developers to call whenever biometric capture is required.
2. RD Service should return service and device info (see later sections for API details) to
calling applications which includes “device provider model ID (Mi)”, “device public
key cert (Mc) (signed by Device Provider Key)”, and “Device Code (Dc)”. These
attributes are used by application to form Meta element of authentication XML (see
Authentication API Specifications 2.0).
3. When RD Service is called, it should capture, process, sign the biometric record (FMR,
FIR, IIR, FID) using device key, and form the encrypted PID block before returning the
encrypted PID block with other metadata to application.
4. Within PID block, every biometric record (bio element) should have “Biometric
Signature (Bs)” for that data. A separate independent attribute is used instead of any
signature that is embedded within bio record to ensure various image and ISO
formats are supported.
5. RD Service should use the following logic to sign the biometric record:
a. Bh = SHA-256(bio_record) of each successful biometric capture.
b. Be = DSA(Bh+ts+Dc, Dpk) where;
Dpk is the device private key
ts is the PID timestamp (in String representation)
Dc is the unique device code in String format
Refer section 2.7 for supported signature algorithms.
c. Bs = base64(Be)
6. Within PID block, for the “Bios” element, attribute “dih” should be computed as:
SHA-256(dpId+rdsId+rdsVer+dc+mi+idHash)
a. dpId – Device Provider ID as assigned during certification.
b. rdsId – RD Service ID as assigned during certification.
c. rdsVer – RD Service Version.
d. mi – Device Provider Model ID.
e. idHash – SHA-256 of any internal physical ID that is used to recognize physical
device (such as serial number). This should be read automatically without any
user input. This ID is not expected to change during the life of that physical
device. idHash MUST match what was sent during registration (see
Register API call later).
7. Within PID block, wadh is added if passed by the calling application (see
PidOptionsOpt element later).
8. After capturing the biometric, RD Service forms the encrypted PID block as per
Aadhaar Authentication API 2.0 specification and returns it to application along with
other metadata.
a. Note that RD Service MUST store latest UIDAI public key used for PID
encryption and should have a mechanism to initialize and update over the air.
All RD Services MUST provide the following standard APIs to ensure applications have a
common way to interface with all Aadhaar compliant registered devices. This is a necessary
condition for certification of registered devices.
All RD Services must provide a standard interface having the following two methods and
MUST work without ANY state stored within driver across calls.
// main capture call which takes PidOptions XML data as input and returns PidData XML
as output
String capture (String pidOptions);
// utility method to obtain DeviceInfo XML from the RD Service
String getDeviceInfo ();
A mechanism to discover the RD Service and invoke these methods are described in later
sections of this document.
/*
PidOptions:
ver: Version of the PidOtopns spec. Currently it is “1.0”. This is necessary to
allow applications to gracefully upgrade even when RD service may be been
upgraded. RD Service must support current version and one previous version
to allow apps to upgrade at different points in time.
Opts:
Int fCount (optional) number of finger records to be captured (0 to 10)
Int fType (optional) ISO format (0 for FMR or 1 for FIR), 0 (FMR) is default
CustOpts:
Allows vendor specific options to be passed. Param element may repeat.
*/
<PidData>
<Resp errCode="" errInfo="" fCount="" fType="" iCount="" iType="" pCount=""
pType="" nmPoints="" qScore=""/>
<DeviceInfo />
<Skey ci="">encrypted and encoded session key</Skey>
<Hmac>SHA-256 Hash of Pid block, encrypted and then encoded</Hmac>
<Data type="X|P"> base-64 encoded encrypted pid block </pid>
</PidData>
/*
Resp:
Int errCode (mandatory) 0 if no error, else standard error codes
String errInfo (optional) additional info message in case of error/warning
Int fCount (mandatory for FP) number of finger records actually captured
Int fType (mandatory for FP) actual format type – 0 (FMR) or 1 (FIR)
Int iCount (mandatory for Iris) number of iris records actually captured
Int iType (mandatory for Iris) actual Iris format (0 for IIR)
Int pCount (mandatory for Photo) number of face photo records actually captured.
Currently face matching is not supported.
Int pType (mandatory for Photo) face format. Currently face matching is not
supported.
Int nmPoints (mandatory for FMR capture) Number of minutiae points when FMR is
captured. Applications may use this for accepting or retrying the capture.
If multiple fingers are captured, send comma delimited numbers.
Int qScore (optional) If quality check is done, send a normalized score that is
between 0 and 100. Device providers may allow configuration within RD service
to use specific quality check algorithms to be enabled. Either it can be
configured within RD service or applications can pass those under
PidOptionsCustOptsParam.
Skey:
String skey (mandatory) encrypted session key as per auth spec
String ci (mandatory) UIDAI public key identifier as per auth spec
Hmac:
String hmac (mandatory) hmac value as per auth spec
*/
1. Device providers to register and obtain a device provider ID via UIDAI portal.
2. Device provider can register one or more public certificate procured from CA and get
it signed by UIDAI. These are then used to sign the device public key certificate.
3. Device providers can rotate, revoke their keys via the UIDAI portal.
3 Sequence Diagrams
Sequence diagram for L0 device is given below:
Certified RD services and devices details are made available at the following URL:
https://authportal.uidai.gov.in/devices/rdservice_registry.xml
Beta version details that are going through certification is made available at:
https://authportal.uidai.gov.in/devices/rdservice_registry_beta.xml
/**
lastUpdated: Timestamp in YYYYMMDDhhmmss format depicting when this file was
last updated.
ttl: Time to Live in hrs. This is an indicator for applications caching this file to refresh
the cache with new file. After ttl time window has passed, applications should
do HTTP HEAD request can be made to check if the file has changed and
download if changed.
RDServicerdsId: Unique alpha-numeric ID assigned to an RD Service post
certification (separate per OS).
RDServicedpId: Unique Device Provider ID. Alpha-numeric.
RDServiceVersion: This element repeats to capture all certified versions across
operating systems from this provider.
VersionrdsVer: Version of the RD Service.
VersionrdsMD5: MD5 checksum of the certified RD Service installable. Agencies
installing RD Services should download and verify the checksum to ensure
they are indeed using certified versions.
VersionosId: Enum depicting ID of the operating system for which this RD Service
version is certified. Values can be LINUX, WINDOWS, ANDROID, WINDOWS
MOBILE, etc.
VersionosVer: Version of the OS for which this RD Service is released. This can be a
comma delimited string containing version numbers in the form “x.y.z”. Also,
“+” sign may be there (e.g., 3.4+) depicting any version above can be used.
VersionProviderModel: This element may be repeated for all models that are
supported by this RD Service version.
ProviderModelmi: Provider Model ID. Alpha numeric.
ProviderModeltype: Type of the device. Thi is a comma delimited string depicting
that this device can be used for fingerprint and/or iris and or photo (face
modality not yet supported). Typically it will be just “F” or “I” or “P”. But if a
device model supports both Fingerprint and Iris (unlikely scenario), this will
be “FI” and so on.
ProviderModellevel: Certification level for this registered device model. It can be
either “L0” or “L1”.
**/
5 Device Discovery
The RD service will run with on the host machine. The RD service will be listening on the
port starting 11100 - 11120 biding only to 127.0.0.1. Any of these ports can be used by the
RD service and as a best practice please start from the start to listen until you find one of
these ports free. Applications should scan these ports and discover the service.
The RD service will respond back only for the queries listed as part of the interface. Should
not entertain any other calls and should reject or disconnect without any indications. For all
other failed/malformed request the RD service would simply not respond.
The RD-Service call is similar to a HTTP 1.1 GET call. Except that it use the RD-SERVICE as
the verb and * as the request URI. A new VERB is introduced to avoid any HTTP based bots
or virus from infecting the service (This is just based on the defense in depth). This solution
all together cannot protect against all attacks but helps to ensure that the client is well aware
of the situation.
Applications should first scan the ports and try call the following to see if there is a valid RD
Service listening on the port.
RDSERVICE * HTTP/1.1
HOST: 127.0.0.1:<apps port>
EXT: app_name
HTTP/1.1 200 OK
CACHE-CONTROL:no-cache
LOCATION:http://127.0.0.1:<rd_service_port>
Content-Length: length in bytes of the body
Content-Type: text/xml
Connection: Closed
<RDService status="READY|USED|NOTREADY|..." info="provider info for display
purposes">
<Interface id="CAPTURE" path="/rd/capture" />
<Interface id="DEVICEINFO" path="/rd/info" />
</RDService>
Based on the path, subsequent calls from application can be made to RD Service.
http://127.0.0.1:<port>/<CAPTURE-path>
http://127.0.0.1:<port>/<INFO-path>
The RD-Service call can be called by any number of client simultaneously and the system can
respond back the same information for everyone calling. The RD service will ensure it’s able
to connect to the device and other error checks before it responds back to the call. The status
should be “READY” if the device is ready. For all other errors please look at the spec.
Apps have to decide if they need L0 or L1 devices or could change the authentication to
multifactor in case of L0.
CAPTURE - The capture call is a blocking call and only one client can call at any point in time.
CAPTURE http://127.0.0.1:<rd_service_port>/<CAPTURE_path>
HOST: 127.0.0.1:<port>
<PidOptions /> <!—see XML details in earlier sections -->
HTTP/1.1 200 OK
CACHE-CONTROL:no-cache
LOCATION:http://127.0.0.1:<rd_service_port>/<CAPTURE_path>
Content-Length: length in bytes of the body
Content-Type: text/xml
Connection: Closed
<PidData /> <!—see XML details in earlier sections -->
DEVICEINFO http://127.0.0.1:<rd_service_port>/<INFO_path>
HOST: 127.0.0.1:<port>
HTTP/1.1 200 OK
CACHE-CONTROL:no-cache
LOCATION:http://127.0.0.1:<rd_service_port>/<INFO_path>
Content-Length: length in bytes of the body
Content-Type: text/xml
Connection: Closed
<DeviceInfo /> <!—see XML details in earlier sections -->
o Call “INFO” intent and verify the provider package name against locally cached
UIDAIRDServices registry to make sure only certified ones are being used.
o Call "CAPTURE" intent to capture the encrypted biometrics.
6 Keystore Security
In case of L1 the following security has to be in place.
1. Keystore is inside the TEE and only the internal service has access to the same.
2. The private key should not be extractable (wrapped or direct)
3. The key pair has to be generated inside TEE.
In case of L0 the following security has to be in place. When OS is giving you a keystore
facility satisfying the following requirements, device provider should use that.
1. Keystore file should be limited with read and write rights only for the user as whom
the RD service runs and no other user accounts should have access to the file/store.
2. The RD service should run as a user account who does not have login privileges.
3. Keystore password has to be complex and auto generated. The following list of
approaches are possible:
a. A combination of random data, user credentials and device identification
data -derived key using identities (MAC, bluetooth, harddisk serial number,
processor id and other device id’s) that exist within the system. The logic
how key is derived using these values has to be obfuscated to avoid any
possible security threats.
b. The Key derivation logic should be in a compiled native machine dependent
and can not be an open api.
c. The password should be changed for every Key rotation.
d. White cryptography to derive the password.
e. The password should be more than 16 characters in length and should
contain minimum of 3 special characters, small letters, capital letters and
numbers
f. A server side logic to help with opening the keystore.
4. The RD service should fail its integrity check upon the keystore file permissions not
correct or has unwanted access and should inform the server about such failures.
This failure would be tracked as an incident by the device provider.
5. All type of access and access attempts to the keystore should have audit logs.
6. The private key should not be extractable (wrapped or direct)
7. It is recommended that key pair is generated inside the capture_n_sign service. If
key pairs are generated on management server, then private key must be returned
and MUST BE strongly encrypted using AES-256 session key generated at the client.
Note that device authentication must be performed before allowing any connection
to management server,
8. The keystore has to be cleared and zeroed in case the RD service is deleted.
This API will be whitelisted only for the device providers. Both digital signature and API key
validation will be done for the callers to ensure only certified providers are able to call this
API. In addition, IP whitelisting will also be done.
Input:
Output:
Input:
Output:
8 Management Section