Page 1
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
Page 2
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.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
2 of 26 6/12/2012 10:24 AM
Page 3
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.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
3 of 26 6/12/2012 10:24 AM
Page 4
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.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
4 of 26 6/12/2012 10:24 AM
Page 5
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.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
5 of 26 6/12/2012 10:24 AM
Page 6
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.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
6 of 26 6/12/2012 10:24 AM
Page 7
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.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
7 of 26 6/12/2012 10:24 AM
Page 8
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.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
8 of 26 6/12/2012 10:24 AM
Page 9
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
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
9 of 26 6/12/2012 10:24 AM
Page 10
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
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
10 of 26 6/12/2012 10:24 AM
Page 11
[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
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
11 of 26 6/12/2012 10:24 AM
Page 12
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
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
12 of 26 6/12/2012 10:24 AM
Page 13
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
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
13 of 26 6/12/2012 10:24 AM
Page 14
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
User should be allowed
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
User should be allowed
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
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
14 of 26 6/12/2012 10:24 AM
Page 15
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
prompt user to try again
with distinct irises.
Please try again
with distinct irises.
Operator should
ensure that the
resident is providing
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
prompt user to try again
by placing single finger.
Please try again by
placing Single
finger on the
authentication
device.
Operator should
ensure that the
resident is providing
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
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
15 of 26 6/12/2012 10:24 AM
Page 16
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
used for encryption of
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
16 of 26 6/12/2012 10:24 AM
Page 17
“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
used for encryption of
“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
Application should have
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
Authentication request
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.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
17 of 26 6/12/2012 10:24 AM
Page 18
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
authentication request
which is registered with
UIDAI. Value of this
code should be
configurable.
Technical
Exception <No>
AUA code used in
Authentication request
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
Application should pass
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
Application should pass
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
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
18 of 26 6/12/2012 10:24 AM
Page 19
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
before sending request
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
before sending request
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.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
19 of 26 6/12/2012 10:24 AM
Page 20
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
authentication request
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
Application should have
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
Application should have
client/server level
Technical
Exception <No>
some unsupported
characters were found
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
20 of 26 6/12/2012 10:24 AM
Page 21
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
Application should have
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
authentication request
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>
Authentication request
XML was modified
after it was signed.
570 Invalid key info in
digital signature (this
means that certificate
used for signing the
authentication request
is not valid – it is
either expired, or does
not belong to the
AUA or is not created
by a well-known
Certification
Authority)
Application should have
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
authentication request
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.)
Application should have
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
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
21 of 26 6/12/2012 10:24 AM
Page 22
573 Pi usage not allowed
as per license
Application should have
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
Application can have a
client level check to
restrict/allow entry of
“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
Application can have a
client level check to
restrict/allow entry of
“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
Application can have a
client level check to
restrict/allow entry of
“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
Application can have a
client level check to
restrict/allow entry of
“IIR” attribute as per
license of AUA.
Technical
Exception <No>
IIR usage not allowed
as per license
579 OTP usage not
allowed as per license
Application can have a
client level check to
restrict/allow entry of
“OTP” attribute as per
license of AUA.
Technical
Exception <No>
OTP usage not allowed
as per license
580 PIN usage not
allowed as per license
Application can have a
client level check to
restrict/allow entry of
“PIN” attribute as per
license of AUA.
Technical
Exception <No>
PIN usage not allowed
as per license
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
22 of 26 6/12/2012 10:24 AM
Page 23
581 Fuzzy matching usage
not allowed as per
license
Application can have a
client level check to
restrict/allow entry of
“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
Application can have a
client level check to
restrict/allow entry of
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
specified in “Uses”
720 Missing “Pa” data as
specified in “Uses”
Same as 710 Technical
Exception <No>
Missing “Pa” data as
specified in “Uses”
721 Missing “Pfa” data as
specified in “Uses”
Same as 710 Technical
Exception <No>
Missing “Pfa” data as
specified in “Uses”
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
23 of 26 6/12/2012 10:24 AM
Page 24
730 Missing PIN data as
specified in “Uses”
Same as 710 Technical
Exception <No>
Missing PIN data as
specified in “Uses”
740 Missing OTP data as
specified in “Uses”
Same as 710 Technical
Exception <No>
Missing OTP data as
specified in “Uses”
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”
Same as 710 Technical
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”.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
24 of 26 6/12/2012 10:24 AM
Page 25
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
Same as 710 Technical
Exception <No>
Missing or empty value
for “bt” attribute in
“Uses” element
821 Invalid value in the
“bt” attribute of
“Uses” element
Same as 710 Technical
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)
Application should have
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
Same as 710 Technical
Exception <No>
911 Invalid “mv” value in
the “Pfa” element
Same as 710 Technical
Exception <No>
912 Invalid “ms” value Same as 710 Technical
Exception <No>
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
25 of 26 6/12/2012 10:24 AM
Page 26
913 Both “Pa” and “Pfa”
are present in the
authentication request
(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.
Aadhaar Authentication Basics https://developer.uidai.gov.in/site/book/export/html/18
26 of 26 6/12/2012 10:24 AM