Aadhaar Authentication Basics

Aadhaar Authentication Basics

This book walks you through Aadhaar authentication basics and helps you test using sample authentication client as well as setup

development environment using the source code provided. Click on the chapters below to navigate.

Introduction

Aadhaar authentication is the process wherein Aadhaar Number, along with other attributes, including biometrics, are submitted

online to the CIDR for its verification on the basis of information or data or documents available with it. Aadhaar authentication

provides several ways in which a resident can authenticate themselves using the system. At a high level, authentication can be

‘Demographic Authentication’ and/or ‘Biometric Authentication’.

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. Fingerprints in the input are matched against all stored 10 fingerprints.

Note: In all forms of authentication the Aadhaar Number needs to be submitted so that authentication is reduced to a 1:1 match. In

addition, Aadhaar authentication service only responds with a “yes/no” and no Personal Identity Information (PII) is returned as

part of the response.

Aadhaar authentication enables agencies to verify identity of residents using an online and electronic means where the agency

collects required information from the resident along with resident’s Aadhaar Number and passes the same to UIDAI systems for

verification. Aadhaar authentication service provides services to instantly verify the identity of the resident against the available

data in CIDR. Based on the needs of the service, different identifiers could be used along with Aadhaar Number. These identifiers

could be combination of biometrics (such as fingerprints, iris impressions) and/or demographic information (such as Name, Date of

birth, Address) and/or a secret PIN or OTP number known only to the resident.

Authentication API

Aadhaar authentication service is exposed as stateless service over HTTPS. Usage of open data format in XML and widely used

protocol such as HTTP allows easy adoption and deployment of Aadhaar authentication. To support strong end to end security and

avoid request tampering and man-in-the-middle attacks, it is essential that encryption of data happens at the time of capture on the

capture device.

If you have not read the Aadhaar Authentication Specification (version 1.5 Rev 1) document, it's important that you do now before

proceeding!

Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18

1 of 26 6/12/2012 10:24 AM

Next few chapters takes you through details on running sample application code, setting up source code within Eclipse, and usage

of test codes and data.

Running Sample Application

UIDAI has created a fully working sample Java client application to help the community rapidly develop applications that use

Aadhaar authentication. This application is written in Java and demonstrates various features of Aadhaar authentication. This

application is provided on an "AS-IS" basis and should not be considered as a supported, production strength software. This

chapter covers details about downloading, installing, and running the sample and setting up development environment with the

source code.

Sample Java application (both binary and source code zip files) to test Aadhaar authentication can be downloaded from here.

Running Sample from Distribution

When you download the binary distribution using downlink above, you get "auth-client-bin-1.5.zip". Follow steps below to install

and run the client. These directions are for Windows OS. If you are using Linux or other OS, you may make appropriate

modification to build and run the client.

You need Java 1.6 or above installed on your computer and an Internet connection to run this sample.1.

Unzip "auth-client-bin-1.5.zip" into a directory. You will see the following contents.2.

Run "runclient.bat" to run the sample application.3.

In order to use Indian name matching, it is required that the java apps run in UTF-8 character encoding mode. For that, in

Java, following VM arguments has to be passed "-Dfile.encoding=UTF8". This is already added to the "runclient.bat"

file.

4.

This opens a command promt asking for OS type, enter 1 or 2 (based on your OS) and press ENTER.5.

This opens the sample authentication client. See screenshot below.6.


2 of 26 6/12/2012 10:24 AM

Click "Edit->Preferences" menu to make sure you see following screen with values. Ensure license key, AUA code, Sub

AUA code are as listed under "Testing Data" page.

7.


3 of 26 6/12/2012 10:24 AM

Now you are ready to test!!8.

Enter "999999990019" in "Aadhaar Number" field and "Shivshankar Choudhury" in the "Name" field. See "Testing Data"

page for details on test data for testing various combinations.

9.

Click "Authenticate" button at the bottom right10.

You should see a green tick mark within the "Authentication Status" field. See the following screen11.


4 of 26 6/12/2012 10:24 AM

If you have issues, first ensure you have followed all steps correctly. If you face network or connection errors, please make

sure your Internet connection is working well. If test server (auth.uidai.gov.in) is down or not reachable, try after some time.

12.

If nothing works (!), please write to the discussion group.13.

Developing using Sample

As explained in previous chapter, sample Java client with source code is provided to help the community rapidly develop

applications that use Aadhaar authentication. This application is written in Java and demonstrates various features of Aadhaar

authentication. This application is provided on an "AS-IS" basis and should not be considered as a supported, production strength

software. This chapter covers details about downloading and setting up development environment.

Sample Java application (both binary and source code zip files) to test Aadhaar authentication can be downloaded from here.

Setting up Development Environment

When you download the source distribution using downlink above, you get "auth-client-source-1.5.zip". Follow steps below to

setup the client as a development environment. These directions are for Windows OS. If you are using Linux or other OS, you may

make appropriate modification to the instructions below.

You need Java 1.6.20 or above, Apache Maven 2.2.1 or above, and Eclipse Java IDE installed on your computer to

setup environment based on this page. You can use the source code and setup environment if you want it in other IDEs and

build environments.

1.

Unzip "auth-client-source-1.5.zip" into a directory. You should now see a directory named "auth-client-source-1.5" there2.

Navigate to "auth-client-source-1.5" directory. You should see the following listing.3.


5 of 26 6/12/2012 10:24 AM

Within "Command Prompt", change directory ("cd") to "auth-client-source-1.5"4.

Run "mvn eclipse:eclipse" command. If "Maven\bin" is not in path, please add it. Otherwise "mvn" command will not run.5.

You should see "Build Successful" message like below.6.

Launch Eclipse and create a new workspace (or use current workspace if you prefer)7.

Choose "File->Import" menu. This lanuches an import dialog.8.

Choose "Existing Projects into Workspace" option and click "Next"9.

Click "Browse" button next to "Select Root Directory"10.

Navigate to "auth-client-source-1.5" and select the directory11.

This will list 4 projects - "uidai-auth-client", "uidai-auth-xsd-model", "uidai-biometric-integration-api", and "uidai-sample-

gui-app"

12.

Make sure all projects are selected. See screen below.13.


6 of 26 6/12/2012 10:24 AM

Click "Finish" to import all 4 projects into workspace14.

If you have project that provides biometric integration API implementation, you will have to add it to the class path of the

"uidai-sample-gui-app" project. Also, update the value of field, biometricAPIImplementationClass, in the

SampleClientMainFrame.java to the value of the class that implements the API.

15.

Select "SampleClientMainFrame.java" under project "uidai-sample-gui-app" (src/main/java/in/gov/uidai/auth/sampleapp

folder) and choose "Run->Run COnfigurations" menu or click "Run" icon on toolbar and choose "Run COnfigurations".

16.


7 of 26 6/12/2012 10:24 AM

Click "New Launch Configuration" icon on left top corner within the dialog. This created a new default run configuration for

the sample application.

17.

In order to use Indian name matching, it is required that the java apps run in UTF-8 character encoding mode. For that, in

Java, following VM arguments has to be passed "-Dfile.encoding=UTF8". Within "Run Configurations" doalog, add

this to VM arguments.

18.

Click "Run" button on the bottom right within the "Run Configuration" dialog to run the application. you should see the

sample application GUI window.

19.

Choose "Edit->Preferences" menu option and ensure you choose appropriate path for public key file and keystore file (they20.


8 of 26 6/12/2012 10:24 AM

are available under "auth-client-source-1.5\uidai-auth-client\src\main\resources" folder. Ensure license key, AUA code,

Sub AUA code are as listed under "Testing Data" page.

Enter "999999990019" in "Aadhaar Number" field and "Shivshankar Choudhury" in the "Name" field. Additional data is

available on "Testing Data" page.

8.

Click "Authenticate" button at the bottom right9.

You should see a green tick mark within the "Authentication Status" field. See the following screen10.

If you have issues, first ensure you have followed all steps correctly. If you face network or connection errors, please make

sure your Internet connection is working well. If test server (auth.uidai.gov.in) is down or not reachable, try after some time.

11.

If nothing works (!), please write to the discussion group.12.

Testing Data

Test Codes

Test URLs: (remember to append AUA code and first two digits of Aadhaar number)

Auth URL - http://auth.uidai.gov.in/auth/1.6/<aua-code>/<1st-digit-of-uid>/<2nd-digit-of-uid>/

OTP URL - http://auth.uidai.gov.in/otp/1.6/<aua-code>/<1st-digit-of-uid>/<2nd-digit-of-uid>/

BFD URL - http://auth.uidai.gov.in/bfd/1.6/<aua-code>/<1st-digit-of-uid>/<2nd-digit-of-uid>/

Test Codes:

AUA Code ("ac" attribute) : "public"

Sub-AUA Code ("sa" attribute) - "public"

License Key ("lk" attribute) : You can use any of the following license keys given below. Binary distribution of sample client

is shipped with the first one below.

"MKg8njN6O+QRUmYF+TrbBUCqlrCnbN/Ns6hYbnnaOk99e5UGNhhE/xQ=" - allows usage of PI, PA, PFA,

BIO-FMR, BIO-FIR, BIO-IIR, OTP, PIN, Indian Language

ASA License key fo testing - MMZS5K8bEkGWFQe6y_ruBu9tFR2yQFQkqmECCpp9veRawhue1oGpa4s

Public key certificate - See chapter on certificates (remember to use Staging/Test certificate for testing and production


9 of 26 6/12/2012 10:24 AM

certificate for production)

Keystore for digital signature for "public" AUA - Keystore in p12 file format (keystore Password: "public", Alias: "public")

Test Data

Note: Following data are purely for testing and are not of real residents. Neither Aadhaar numbers nor demographic/biometric

data are real and are ONLY available in test system. Any resemblance to real people is purely coincidental!

Sample biometric data given below is "base 64" encoded. Just add the encoded string to "bio" element (remove the newline when

you are cutting the data). ALL TEST RECORDS HAVE SAME BIOMETRIC.

bio=Rk1SACAyMAAAAADkAAgAyQFnAMUAxQEAAAARIQBqAGsgPgCIAG0fRwC2AG2dSQBVAIUjPABuALShMgCxAL0jMAByAM6lPgCmAN2

kQQBwAN8qNAB1AN8mPADJAOcgOQA8AOorNABoAOomOQC+AO2fMQDFAPqlSgCvAP8lRQB8AQuhPABwAQ4fMgB7ASqcRADAAS4iNwCkAT

MeMwCFATYeNwBLATYwMQBWATcoMQCkATecMQBEATwyMgBJAUciQQCkAU8cNQB9AVQWNgCEAVUVRACoAVgYOgBBAV69NgCsAWeYNwAA

Following are the test UIDs and their demographic data. All of them have same bio record as given above. If you have your own

Aadhaar number (real one) then you can use that to test too.

uid=999999990019

name=Shivshankar Choudhury

dob=13-05-1968

dobt=V

gender=M

phone=2810806979

[email protected]

street=12 Maulana Azad Marg

vtc=New Delhi

subdist=New Delhi

district=New Delhi

state=New delhi

pincode=110002

uid=999999990026

name=Kumar Agarwal

dob=04-05-1978

dobt=A

gender=M

phone=2314475929

[email protected]

building=IPP, IAP

landmark=Opp RSEB Window

street=5A Madhuban

locality=Veera Desai Road

vtc=Udaipur

district=Udaipur

state=Rajasthan

pincode=313001

uid=999999990042

name=Fatima Bedi

dob=30-07-1943

dobt=A

gender=F

phone=2837032088

[email protected]

building=K-3A Rampur Garden

vtc=Bareilly

district=Bareilly

state=Uttar Pradesh

pincode=243001

uid=999999990057

name=Rohit Pandey

dob=08-07-1985

dobt=A

gender=M

phone=2821096353


10 of 26 6/12/2012 10:24 AM

[email protected]

building=603/4 Vindyachal

street=7TH Road Raja Wadi

locality=Neelkanth Valley

poname=Ghatkopar (EAST)

vtc=Mumbai

district=Mumbai

state=Maharastra

pincode=243001

uid=999922220032

name=Anisha Jay Kapoor

gender=F

dob=01-01-1982

dobt=V

building=2B 203

street=14 Main Road

locality=Jayanagar

district=Bangalore

state=Karnataka

pincode=560036

uid=999922220013

name=Nitin Kumar Dixit

gender=M

dob=02-03-1972

dobt=V

building=1190/4

street=5th Cross, 26th Main

locality=JP Nagar, phase 1

district=Bangalore

state=Karnataka

pincode=560078

uid=999922220021

name=Swamynathan Srini

gender=M

dob=23-01-1947

dobt=V

building=34-2

street=K G Lane

locality=Sarjapur Area

district=Bangalore

state=Karnataka

pincode=560035

uid=999922220045

name=John Alex Doe

gender=M

dob=12-09-1973

dobt=V

building=78 Block D

street=Sarjapura Road

locality=Sarjapura

district=Bangalore

state=Karnataka

pincode=560081

uid=999922220050

name=Ali Akbar

gender=M

dob=14-10-1962

dobt=V

building=34

street=Raj Main Street

locality=K R puram

district=Bangalore

state=Karnataka

pincode=560078

uid=999922220066


11 of 26 6/12/2012 10:24 AM

Certificate Detail Expiry Date

uidai_auth_prod.cer (latest) 3 Oct 2013

Certificate Detail Expiry Date

uidai_auth_stage.cer (latest) 22 Sept 2015

name=Amy John

gender=F

dob=11-07-1987

dobt=V

building=A303

street=14th Cross

locality=BTM II Layout

district=Bangalore

state=Karnataka

pincode=560035

uid=999922220078

name=Kishore Shah

gender=M

dob=21-05-1987

dobt=V

building=23 Level 1

street=Church Street

locality=Central Area

district=Bangalore

state=Karnataka

pincode=560076

Certificate Details

Aadhaar authentication requires the identity data of the resident within the XML (PID block) to be encrypted. AES-256 session

key is encrypted using UIDAI's 2048- public key. This page contains all certificates available for the ecosystem.

Production Public Key Certificates

Note: Latest production public key certificate will always be available under link https://developer.uidai.gov.in/site/sites/default

/files/uidai_auth_prod.cer

Following table lists out all production public key certificates issued so far with their expiry date.

Staging/Testing Public Key Certificates

Note: Latest staging/testing public key certificate will always be available under link https://developer.uidai.gov.in/site/sites/default

/files/uidai_auth_stage.cer

Following table lists out all staging/testing public key certificates issued so far with their expiry date.

.

Developing in C/C++

NOTE: This code is contributed by Geodesic team and is available on as-is basis. Sample C application to test Aadhaar


12 of 26 6/12/2012 10:24 AM

authentication can be downloaded from here.

A sample C client with source code is provided to help the community rapidly develop applications that use Aadhaar

authentication. This sample application is written in C for the GeoAmida device and it demonstrates various features of Aadhaar

authentication. This application is provided on an "AS-IS" basis and should not be considered as a supported, production strength

software. This chapter covers details about downloading and setting up development environment.

Setting up Development Environment

When you download the source distribution from the link above, you get "c-auth-client-source-1.5.zip". Please follow steps below

to setup the client as a development environment. These directions are for Linux OS and ARM devices. If you are using Windows

or other OS, you may make appropriate modification to the instructions below.

Unzip "c-auth-client-source-1.5.zip" into a directory. You should now see a directory named "c-auth-client-source-1.5" there1.

Navigate to "c-auth-client-source-1.5" directory. You should see the following listing.2.

Dependency Libraries:

libxml >= 2.7.6

openssl >= 0.9.8

Digital Signature Generation requires an additional libraries:

libXslt >= 1.1.24

libxmlsec1 >= 1.2.9

3.

The below DEFINES values are need to modify before compiling:

LICENCE_KEY

UIDAI_PUBLIC_CERITIFICATE

AUA_PRIVATE_CERTIFICATE - Required for Digital Signature

4.

Auth Xml API documentation is available under the doc folder

5.

You may use any editor tool (Eclipse, emacs or vim) installed on your development machine and setup the environment

variable, LD_LIBRARY_PATH in order to find libraries.

6.

Within "Command Prompt", change directory ("cd") to "c-auth-client-source-1.5"7.

Sample Makefile included in the build for Geoamida and gcc version.

CC = arm-xscale-linux-gnueabi-gcc

CFLAGS = -D__XMLSEC_FUNCTION__=__FUNCTION__ -DXMLSEC_NO_XSLT=1 -DXMLSEC_NO_XKMS=1

-DXMLSEC_CRYPTO_DYNAMIC_LOADING=1 -DXMLSEC_CRYPTO=\"openssl\" -DUNIX_SOCKETS -D XML_SECURITY

LDFLAGS = -lwebcam -lbiometric -lautils -lxml2 -lcurl -lcrypto -lanet -lxmlsec1 -g

8.

On a successful make, you should see the executable file AuthClient.9.

Run AuthClient. It will generate Auth-XML. During compilation if the "-D XML_SECURITY" flag is set, then the Digital

Signature will be created along with Auth Xml.

10.

API Error Handling


13 of 26 6/12/2012 10:24 AM

This page provides guidelines for handling API errors within the application. While developing applications, AUAs need to decide

how to handle the errors gracefully and provide resident/operator friendly messages. Simply showing the error on screen is not

helpful. This document is an attempt to provide guidelines for doing better error handling.

Follwing table desribes API error codes, suggestion for how to handle it, possible message to user, and probable reasons for the

error.

APIError

Code

DescriptionProvision Required in

the Application

SuggestedMessage to the

User

Suggestedinstructions to the

user

Probable Reasons

100 “Pi” (basic) attributes

of demographic data

did not match

User should be allowed

to re- enter his/her

personal information

attributes like name,

lname, gender, dob,

dobt, age, phone, email

whichever is used for

authentication in

application

Please re-enter

your <name,

lname, gender,

dob, dobt, age,

phone, email>.

Operator should

re-enter correct

details personal

information as per

the Aadhaar letter.

Ensure correct

Aadhaar Information

is entered.

One or more personal

information attributes

not matching.

200 “Pa” (address)

attributes of

demographic data did

not match


to re- enter his/her

personal address

attribute like co (care

of), house, street, lm

(land mark), loc

(locality), vtc, subdist,

dist, state, pc (postal pin

code), po (post office)

whichever is used for

authentication in

application

Please re-enter

your <co (care of),

house, street, lm

(land mark), loc

(locality), vtc,

subdist, dist, state,

pc (postal pin

code), po (post

office)>.

Operator should

re-enter correct

details personal

information as per

the Aadhaar letter.

Ensure correct

Aadhaar Information

is entered.

One or more personal

address attributes not

matching.

300 Biometric data did not

match


to give his finger prints

“n” number of times. N

should be configurable

and should be set as per

application requirement.

(E.g. For Banking

Applications it can be

set at a maximum of 5

times)

Please give your

finger prints again.

Ensure correct

Aadhaar number is

entered and try

authenticating again

with another finger;

ensure finger is

placed correctly;

ensure fingers are

clean; ensure finger

is not very dry;

ensure fingerprint

scanner is clean.

After repeated

failure, if the

resident is genuine,

exception handling

Finger print is not given

properly, scanner has

some dust accumulated,

fingers were wet,

position of finger not

appropriate, scanned

finger NFIQ not good


14 of 26 6/12/2012 10:24 AM

provision would

need to be followed

to provide service.

Please contact

UIDAI helpdesk to

inform about the

issue and to

understand the steps

for the updation of

the biometric

information in

CIDR.

310 Duplicate fingers used Application should

prompt user to try again

with distinct fingers.

Please try again

with distinct

fingers.

Operator should

insure that the

resident is providing

distinct fingers (two

different fingers) for

“two finger”

authentication.

Error occurs when

same finger is sent as

two or more separate

records within same

request. For two-finger

auth, if resident puts

same finger again, then

this happens.

311 Duplicate Irises used Application should


with distinct irises.

Please try again

with distinct irises.

Operator should

ensure that the


distinct irises (two

different irises) for

authentication.

Error occurs when

same iris is sent as two

or more separate

records within same

request.

312 FMR and FIR cannot

be used in same

transaction

Application should

ensure that

authentication request

does not mix FMR and

FIR in the same

transaction e.g. in case

of two finger

authentication, data for

two distinct fingers

should either be sent in

FMR format or in FIR

format.

Technical

Exception <No>

Contact technical

helpdesk.

Auth packet cannot

mix fingerprint "image"

records (FIR) and

fingerprint "minutiae"

records (FMR). AUA

app should choose

either one or another.

FMR is recommended.

313 Single FIR record

contains more than

one finger

Application should


by placing single finger.

Please try again by

placing Single

finger on the

authentication

device.

Operator should

ensure that the


single finger for

authentication.

As per ISO spec, one

FIR can contain one or

more finger images

within itself (like slap,

etc). UIDAI currently

supports single finger

record only. If there is a

requirement to send 2

fingers, 2 different

biometric records

should be sent.

314 Number of FMR/FIR

should not exceed 10

Application should

ensure that one auth

Auth Request has more

than 10 finger records


15 of 26 6/12/2012 10:24 AM

request should not

contain more than 10

FMR/FIR records.

315 Number of IIR should

not exceed 2

Application should

ensure that one auth

request should not

contain more than 2 IIR

records.

Auth Request has more

than 2 iris records

400 "Tkn" validation

failed

Application should

derive the value of tkn

(currently only mobile

number) from network.

This element is meant

for self-service

transations on mobile

(SMS/USSD, etc) where

AUA derives the mobile

number from the

network provider and

passes it on as part of

API to use it as a factor.

Provided "Tkn” details

are not matching with

registered values in

CIDR.

401 "OTP" validation

failed

Application should have

provision for allowing

user to provide OTP

value again and after

some retries

(configurable) option to

generate OTP again.

Please provide

correct OTP value.

If there are repeated

failures user is

advised to generate

new OTP and send

the authentication

request using the

new OTP.

Incorrect OTP value is

entered. Input not

matching with the value

in CIDR.

500 Invalid

Skeyencryption

Application should not

have hard coded digital

certificate information.

It should be

configurable.

Technical

Exception <No>

Note: Application

can throw Auth

API error code

number on screen.

So that contact

centre or

application support

helpline can

understand the

reason.

Contact technical

helpdesk.

Use of wrong digital

certificate for

encryption of AES-256

Key (session key).

501 Invalid value for “ci”

attribute in “Skey”

element

Application should not

have hard coded “ci”

attribute value. It

should be configurable.

Technical

Exception <>

Ensure that expiry date

of UIDAI certificate

used for encryption of

Skey is specified as “ci”

value.

502 Invalid Pid

Encryption

Application should do

extensive testing using

UIDAI Test Auth

Service to ensure

compliance with auth

API.

Technical

Exception <No>

Ensure that correct

AES encryption has

been used.

Ensure that AES key



16 of 26 6/12/2012 10:24 AM

“Pid” XML was

encrypted and specified

as value for Skey.

503 Invalid HMac

encryption

Application should do

extensive testing using

UIDAI Test Auth

Service to ensure

compliance with auth

API.

Technical

Exception <No>

Ensure that correct

AES encryption has

been used.

Ensure that AES key


“Hmac” was encrypted

and specified as value

for Skey.

Ensure that same AES

key is used for

encryption of Pid and

Hmac.

504 Session key

re-initiation required

due to expiry or key

out of sync


a provision to send full

session key and initiate

a new session in case of

such failure.

Technical

Exception <No>

Please try again. When Synchronized

Session Key scheme is

used, this can happen if

either session is expired

(currently configured to

max 4 hrs) or if the key

goes out of sync.

505 Synchronized Skey

usage is not allowed

Application should use

full skey

Technical

Exception <No>

Switch to full skey

scheme

This happens when

AUA does not have

privilage to use SSK

scheme

510 Invalid Auth XML

format

Application

Authentication request

should comply to

Authentication API

latest version and

application should

validate its structure

before sending it to

CIDR for

authentication.

Technical

Exception <No>

Please ensure that

the latest

recommended API is

used for application

development. Refer

UIDAI website for

the latest version of

API.

If this does not

resolve the issue

than please contact

technical helpdesk.

Non compliance with

supported

Authentication API

version structure in

CIDR.

511 Invalid PID XML

format

Application


should comply to PID

XML format defined in

Authentication API

latest version and

structural validation

should be done before

encryption of PID

XML.

Technical

Exception <No>

Please ensure that

the latest

recommended API is

used for application

development. Refer

UIDAI website for

the latest version of

API.

If this does not

resolve the issue

Non compliance with

supported

Authentication API

version structure in

CIDR.


17 of 26 6/12/2012 10:24 AM

than please contact

technical helpdesk.

520 Invalid device Application should

ensure that “tid”

attribute in Auth XML

has value “public”

Technical

Exception <No>

Using any other value

other than “public” (all

lower case, no spaces

or special char) will

result in this error.

521 Invalid Finger device

(fdc in Meta element)

Application should

obtain proper code from

fingerprint sensor

vendor and use it

Technical

Exception <No>

FDC codes are assigned

as part of certification

and application

developer should use

proper fdc code given

by the fingerprint

sensor/extractor vendor

522 Invalid Iris device

(idc in Meta element)

Application should

obtain proper code from

iris sensor vendor and

use it

Technical

Exception <No>

IDC codes are assigned

as part of certification

and application

developer should use

proper idc code given

by the iris

sensor/extractor vendor

530 Invalid authenticator

code

Application should pass

valid AUA code in


which is registered with

UIDAI. Value of this

code should be

configurable.

Technical

Exception <No>

AUA code used in


is not valid.

or

AUA code used in the

Auth URL is not same

as the AUA code used

in the Auth XML.

540 Invalid Auth XML

version


supported valid API

version in

authentication request.

Value of this should be

configurable.

Technical

Exception <No>

API version used in

Auth XML

(Authentication

request) is either not

supported or invalid.

541 Invalid PID XML

version


supported valid API

PID XML version in

authentication request.

Value of this should be

configurable.

Technical

Exception <No>

Version of the “Pid”

element used

In the PID XML

(Authentication

request) is either not

supported or invalid.

542 AUA not authorized

for ASA.

Application should

ensure link is in place

between AUA-ASA

Ensure the

authentication

request is being sent

This error will be

returned if AUA and

ASA do not have


18 of 26 6/12/2012 10:24 AM

before sending request

to CIDR.

through the

authorized ASA as

per the records of

UIDAI.

or

Please contact

UIDAI helpdesk to

report the issue and

to understand further

steps for the

updation of

ASA-AUA linkage.

linking in the portal

543 Sub-AUA not

associated with

“AUA”

Application should

ensure Sub-AUA is

added and associated

with correct AUA


to CIDR.

Ensure the

authentication

request is being sent

through the

associated AUA as

per the records of

UIDAI.

or

Please contact

UIDAI helpdesk to

report the issue and

to understand further

steps for the

updation of

ASA-AUA linkage.

This error will be

returned if Sub-AUA

specified in “sa”

attribute is not added as

“Sub-AUA” in portal

550 Invalid “Uses”

element attributes

Application should use

valid attributes defined

in API for <Uses> tag

and validation on Auth

request should be done


to CIDR.

Technical

Exception <No>

Invalid attributes used

in Uses tag.

This error is typically

reported if “bt”

attribute has been

specified but bio=”n”

in Uses element. “bt”

attribute is required

only if bio=”y” in Uses

element.

561 Request expired

(“Pid->ts” value is

older than N hours

where N is a

configured threshold

in authentication

server)

AUA application should

not store Pid block and

in case of application

which are using thick

client there should be a

provision to sync up

date with server at start.

1. In case of

Device/Client

based Application

a. Either

device date/time is

behind current

date/time or

request is old.

Please try again.

2. In case of

Please verify that the

device/client

date/time is

synchronised with

Indian Standard

Time (IST) and

resend the

authentication

request.

Either Device/Client

/Server date/time is

behind current one or

old stored pid is getting

sent.


19 of 26 6/12/2012 10:24 AM

web based

Application

a. Technical

Exception <No>

562 Timestamp value is

future time (value

specified “Pid->ts” is

ahead of

authentication server

time beyond

acceptable threshold)

AUA application should

not store Pid block and

in case of application

which are using thick

client there should be a

provision to sync up

date with server at start.

1. In case of

Device/Client

based Application

a. Either

device date/time is

ahead current

date/time or

request is old.

Please try again.

2. In case of

web based

Application

a. Technical

Exception <No>

Please verify that the

device/client

date/time is

synchronised with

Indian Standard

Time (IST) and

resend the

authentication

request.

Device/Client/server

date/time is ahead than

current date/time.

563 Duplicate request

(this error occurs

when exactly same


was re-sent by AUA)

Application should ask

user to try again.

Please submit your

request again.

User is required to

send the

authentication

request once again.

If same “Auth XML” is

sent more than once to

server, then, 2nd

and

subsequent requests

will fail with this error.

564 HMAC Validation

failed

Application should

create HMAC using

SHA-256

Technical

Exception <No>

HMAC is not

calculated using API

defined algorithm

565 License key has

expired


a configurable License

key management

feature through which

one can manage Key

without changing

application.

Technical

Exception <No>

Current License has

expired.

566 Invalid license key Application should have

a License key

management feature

through which one can

manage Key without

changing application.

Technical

Exception <No>

License key used in

application is invalid.

567 Invalid input (this

error occurs when


client/server level

Technical

Exception <No>

some unsupported

characters were found


20 of 26 6/12/2012 10:24 AM

some unsupported

characters were found

in Indian language

values, “lname” or

“lav”)

checks to stop users to

input unsupported

characters.

in Indian language

values, “lname” or

“lav” in Auth request

XML

568 Unsupported

Language


client/server level

checks to restrict users

to only select language

from API supported

local Language.

Technical

Exception <No>

Value of “lang”

attribute is not from the

list supported by

authapi.

569 Digital signature

verification failed

(this means that


XML was modified

after it was signed)

Application should

ensure security of data

end to end ie. From

client/device to CIDR

server by using

appropriate

communication

protocol.

Technical

Exception <No>


XML was modified

after it was signed.

570 Invalid key info in

digital signature (this

means that certificate

used for signing the


is not valid – it is

either expired, or does

not belong to the

AUA or is not created

by a well-known

Certification

Authority)


an independent module

for signing Auth XML

and certificate should

be stored and manage

outside of the

application.

Technical

Exception <No>

Certificate used for

signing the


is not valid – it is either

expired, or does not

belong to the AUA or is

not created by a

well-known

Certification Authority

571 PIN Requires reset

(this error will be

returned if resident is

using the default PIN

which needs to be

reset before usage)

Please reset your

PIN in UIDAI

updation

application and

use new PIN in

this application.

Please change your

default PIN through

UIDAI updation

client and resend

your authentication

request.

This error will be

returned if resident is

using the default PIN

which needs to be reset

before usage.

572 Invalid biometric

position (This error is

returned if biometric

position value - “pos”

attribute in “Bio”

element - is not

applicable for a given

biometric type -

“type” attribute in

“Bio” element.)


client level validation to

check “type” and

corresponding valid

“pos” values before

creating PID block.

Technical

Exception <no>

This error is returned if

biometric position value

- “pos” attribute in

“Bio” element - is not

applicable for a given

biometric type - “type”

attribute in “Bio”

element


21 of 26 6/12/2012 10:24 AM

573 Pi usage not allowed

as per license


a configurable business

rule which can restrict

the usage of Pi attribute

based on AUA license

authorization.

Technical

Exception <No>

Pi usage not allowed as

per license

574 Pa usage not allowed

as per license

Application can have a

client level check to

restrict/allow entry of

“pa” attribute as per

license of AUA.

Technical

Exception <No>

Pa usage not allowed as

per license

575 Pfa usage not allowed

as per license




“pfa” attribute as per

license of AUA.

Technical

Exception <No>

Pfa usage not allowed

as per license

576 FMR usage not

allowed as per license




“FMR” attribute as per

license of AUA.

Technical

Exception <No>

FMR usage not allowed

as per license

577 FIR usage not allowed

as per license




“FIR” attribute as per

license of AUA.

Technical

Exception <No>

FIR usage not allowed

as per license

578 IIR usage not allowed

as per license




“IIR” attribute as per

license of AUA.

Technical

Exception <No>

IIR usage not allowed

as per license

579 OTP usage not





“OTP” attribute as per

license of AUA.

Technical

Exception <No>

OTP usage not allowed

as per license

580 PIN usage not





“PIN” attribute as per

license of AUA.

Technical

Exception <No>

PIN usage not allowed

as per license


22 of 26 6/12/2012 10:24 AM

581 Fuzzy matching usage

not allowed as per

license




“ms” attribute in pi, pa

and pfa element as per

license of AUA.

Technical

Exception <No>

Fuzzy matching usage

not allowed as per

license

582 Local language usage

not allowed as per

license




local language attribute

in pi, pa and pfa

element as per license

of AUA.

Technical

Exception <No>

Local language usage

not allowed as per

license

584 Invalid Pin code in

Meta element

Pincode should have a

valid value (in lov

attribute)

Technical

Exception <No>

If pincode value is not

one of the valid values

in UIDAI system, this

error occurs

585 Invalid Geo code in

Meta element

Geo code value must be

a valid lat.long value in

decimal format as per

spec (in lov attribute)

Technical

Exception <No>

If geo code does not

have proper format as

per spec (decimal

representation with

porecision upto 4

decimal values for lat

and long), this error

occurs

710 Missing “Pi” data as

specified in “Uses”

Application should

validate pid block

before encrypting data

with API specified PID

block structure and

“Uses” element

attributes values to

ensure PID block have

all the elements and

attributes. Client level

validation should also

be put to check all

mandatory and

conditional fields of

API XML.

Technical

Exception <No>

Missing “Pi” data as


720 Missing “Pa” data as


Same as 710 Technical

Exception <No>

Missing “Pa” data as


721 Missing “Pfa” data as



Exception <No>

Missing “Pfa” data as



23 of 26 6/12/2012 10:24 AM

730 Missing PIN data as



Exception <No>

Missing PIN data as


740 Missing OTP data as



Exception <No>

Missing OTP data as


800 Invalid biometric data AUA to review

biometric device being

used and whether

templates are ISO

compliant.

Technical

Exception <No>

FMR value is not ISO

compliant – bad header

or other issue with

templates.

FIR/IIR value is not

compliant, or templates

could not be extracted

for the given FIR/IIR

for matching purposes.

810 Missing biometric

data as specified in

“Uses”


Exception <No>

Missing biometric data

as specified in “Uses”

811 Missing biometric

data in CIDR for the

given Aadhaar

number

Your Biometric

data is not

available in CIDR.

Ensure correct

Aadhaar number is

entered and try

authenticating again.

After repeated

failure, if the

resident is genuine,

exception handling

provision would

need to be followed

to provide service.

Please contact

UIDAI helpdesk to

inform about the

issue and to

understand the steps

for the updation of

biometric

information in

CIDR.

812 Resident has not done

“Best Finger

Detection”.

Application should

make provison to

initiate BFD application

You have not done

best finger

detection so kindly

Refer Aadhaar Best

Detection API

specifications for

Resident has not done

“Best Finger

Detection”.


24 of 26 6/12/2012 10:24 AM

Application should

initiate BFD

application to help

resident identify their

best fingers. See

Aadhaar Best Finger

Detection API

specification.

based on the error code

to help resident identify

their best fingers.

proceed with the

BFD process for

successful

authentication.

details on the BFD

process.

820 Missing or empty

value for “bt”

attribute in “Uses”

element


Exception <No>

Missing or empty value

for “bt” attribute in

“Uses” element

821 Invalid value in the

“bt” attribute of

“Uses” element


Exception <No>

Invalid value in the

“bt” attribute of “Uses”

element

901 No authentication

data found in the

request (this

corresponds to a

scenario wherein

none of the auth data

– Demo, Pv, or Bios –

is present)

Application should

validate that User

giveatleast one auth

factor before encryption

of PID block.

Technical

Exception <No>

All factors of Auth are

optional. Hence, it is

possible to attempt an

auth without specify

any values for any of

the factors – Pi, Pa,

Pfa, Bio or Pv. If none

of these elements have

any value that can be

used for authentication

purposes, then, this

error will be reported.

902 Invalid “dob” value in

the “Pi” element (this

corresponds to a

scenarios wherein

“dob” attribute is not

of the format

“YYYY” or “YYYY-

MM-DD”, or the age

of resident is not in

valid range)


a client level check to

check dob date format

and age business rules

specified (Current Rule

is that age should not be

less than 0 and greater

than 150 years)

Please enter dob in

specified date

format or enter age

in specified range.

Re-enter the date of

birth or age and

resend a new

authentication

request.

“dob” attribute is not of

the format “YYYY” or

“YYYY-MM-DD”, or

the age of resident is

not in valid range.

910 Invalid “mv” value in

the “Pi” element


Exception <No>

911 Invalid “mv” value in

the “Pfa” element


Exception <No>

912 Invalid “ms” value Same as 710 Technical

Exception <No>


25 of 26 6/12/2012 10:24 AM

913 Both “Pa” and “Pfa”

are present in the


(Pa and Pfa are

mutually exclusive)

Same as 710 Attempt to use Pa and

Pfa both in the same

request can result in

this error.

930-939 Technical error that

are internal to

authentication server

AUA/ASA should call

UIDAI tech support.

Technical

Exception <No>

UIDAI server side

issues. UIDAI tech

support to review the

scenario and take

appropriate action.

940 Unauthorized ASA

channel

AUA should consult

ASA.

Technical

Exception <No>

941

Unspecified ASA

channel

AUA should consult

ASA.

Technical

Exception <No>

980 Unsupported option AUA to review the auth

client to check whether

any dev feature is being

used in prod

Technical

Exception <No>

Currently this error is

not reported. Can be

used in future.

999 Unknown error User to ensure that UID

number is correct.

Technical

Exception <No>

UID number is wrong

or if OTP was used,

OTP did not match.


26 of 26 6/12/2012 10:24 AM

Date post:	24-Oct-2014
Category:	Documents
Upload:	asingh18in
View:	417 times
Download:	11 times

Aadhaar Authentication Basics

Documents