Professional Documents
Culture Documents
Aadhaar Authentication Basics
Aadhaar Authentication Basics
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 residents 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 residents 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 manin-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!
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.
1/23
7/12/2014
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.
7. 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.
https://developer.uidai.gov.in/site/book/export/html/18
2/23
7/12/2014
https://developer.uidai.gov.in/site/book/export/html/18
3/23
7/12/2014
12. 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.
13. If nothing works (!), please write to the discussion group.
4/23
7/12/2014
7.
8.
9.
10.
11.
12.
13.
Launch Eclipse and create a new workspace (or use current workspace if you prefer)
Choose "File->Import" menu. This lanuches an import dialog.
Choose "Existing Projects into Workspace" option and click "Next"
Click "Browse" button next to "Select Root Directory"
Navigate to "auth-client-source-1.5" and select the directory
This will list 4 projects - "uidai-auth-client", "uidai-auth-xsd-model", "uidai-biometric-integration-api", and "uidai-sample-gui-app"
Make sure all projects are selected. See screen below.
5/23
7/12/2014
15. If you have project that provides biometric integration API implementation, you will have to add it to the class path of the "uidai-sample-guiapp" project. Also, update the value of field, biometricAPIImplementationClass, in the SampleClientMainFrame.java to the value of the class
that implements the API.
16. 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".
17. Click "New Launch Configuration" icon on left top corner within the dialog. This created a new default run configuration for the sample
application.
18. 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.
19. Click "Run" button on the bottom right within the "Run Configuration" dialog to run the application. you should see the sample application GUI
window.
https://developer.uidai.gov.in/site/book/export/html/18
6/23
7/12/2014
20. Choose "Edit->Preferences" menu option and ensure you choose appropriate path for public key file and keystore file (they 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.
8. Enter "999999990019" in "Aadhaar Number" field and "Shivshankar Choudhury" in the "Name" field. Additional data is available on "Testing
Data" page.
9. Click "Authenticate" button at the bottom right
10. You should see a green tick mark within the "Authentication Status" field. See the following screen
11. 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.
Testing Data
Following page provide data necessary to test Aadhaar authentication. Several test Aadhaar numbers are provided for testing. If you
are a developer having real Aadhaar number, you can also test using your own Aadhaar number. To add your real Aadhaar number
into test system, fill up this form. If you have questions, ask using the discussion group.
Test Codes
Test URLs: (remember to append AUA code and first two digits of Aadhaar number)
Auth URL - http://auth.uidai.gov.in/1.6/<aua-code>/<1st-digit-of-uid>/<2nd-digit-of-uid>/<asa-license-key>
OTP URL - http://auth.uidai.gov.in/otp/1.5/<aua-code>/<1st-digit-of-uid>/<2nd-digit-of-uid>/<asa-license-key>
BFD URL - http://auth.uidai.gov.in/bfd/1.6/<aua-code>/<1st-digit-of-uid>/<2nd-digit-of-uid>/<asa-license-key>
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.
AUA License Key: "MEWs4XwP0AzUVGSlKwZkMqeHJqyOvzIfz1rxEFm1uu0cRhoxjeWcIqY" - allows usage of PI, PA, PFA,
BIO-FMR, BIO-FIR, BIO-IIR, OTP, PIN, Indian Language
https://developer.uidai.gov.in/site/book/export/html/18
7/23
7/12/2014
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=sschoudhury@dummyemail.com
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=kma@mailserver.com
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=bedi2020@mailserver.com
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
https://developer.uidai.gov.in/site/book/export/html/18
8/23
7/12/2014
gender=M
phone=2821096353
email=rpandey@mailserver.com
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
https://developer.uidai.gov.in/site/book/export/html/18
9/23
7/12/2014
uid=999922220066
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.
Expiry Date
5 Aug 2015
Certificate Detail
uidai_auth_prod_old.cer (old)
https://developer.uidai.gov.in/site/book/export/html/18
Expiry Date
3 Oct 2013
10/23
7/12/2014
UIDAI Digital Signature: For validating signature in the UIDAI response xml , you are requested to make use of the new signature public
key attached below. (Not required if you are not validating signatures in API responses or using the trust root validation for validating
the UIDAI response xml signature)
Certificate Detail
uidai_auth_sign_prod.cer (latest)
Expiry Date
29 Jul 2015
Expiry Date
22 Sept 2015
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 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.
3. Dependency Libraries:
libxml >= 2.7.6
openssl >= 0.9.8
Digital Signature Generation requires an additional libraries:
libXslt >= 1.1.24
https://developer.uidai.gov.in/site/book/export/html/18
11/23
7/12/2014
6. 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.
7. Within "Command Prompt", change directory ("cd") to "c-auth-client-source-1.5"
8. 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
API
Error
Code
100
Description
Pi (basic) attributes of User should be allowed to redemographic data did not enter his/her personal information
match
attributes like name, lname,
gender, dob, dobt, age, phone,
email whichever is used for
authentication in application
Suggested
Message to
the User
Suggested
instructions to the
user
Please re-enter
your <name,
lname, gender,
dob, dobt, age,
phone, email>.
Probable Reasons
200
Pa (address) attributes
of demographic data did
not match
https://developer.uidai.gov.in/site/book/export/html/18
Please re-enter
your <co (care
of), house,
street, lm (land
mark), loc
(locality), vtc,
subdist, dist,
12/23
7/12/2014
authentication in application
300
310
311
312
Contact technical
helpdesk.
313
https://developer.uidai.gov.in/site/book/export/html/18
Technical
Exception
<No>
7/12/2014
finger
Single finger on
the
authentication
device.
314
Number of FMR/FIR
should not exceed 10
315
400
401
500
Invalid Skeyencryption
Technical
Exception
<No>
Technical
Exception <>
Contact technical
helpdesk.
Note:
Application can
throw Auth API
error code
number on
screen. So that
contact centre
or application
support helpline
can understand
the reason.
501
502
https://developer.uidai.gov.in/site/book/export/html/18
7/12/2014
503
504
Technical
Exception
<No>
505
Technical
Exception
<No>
510
511
520
Invalid device
https://developer.uidai.gov.in/site/book/export/html/18
Technical
Exception
<No>
7/12/2014
521
522
530
Technical
Exception
<No>
Technical
Exception
<No>
Technical
Exception
<No>
540
Technical
Exception
<No>
541
Technical
Exception
<No>
542
Ensure the
This error will be returned if
authentication request is AUA and ASA do not have
being sent through the
linking in the portal
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.
543
https://developer.uidai.gov.in/site/book/export/html/18
Ensure the
This error will be returned if
authentication request is Sub-AUA specified in sa
16/23
7/12/2014
or
Please contact UIDAI
helpdesk to report the
issue and to understand
further steps for the
updation of ASA-AUA
linkage.
550
561
Technical
Exception
<No>
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.
Either Device/Client/Server
date/time is behind current one
or old stored pid is getting
sent.
2.
In case of
web based
Application
a.
Technical
Exception
<No>
562
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
https://developer.uidai.gov.in/site/book/export/html/18
17/23
7/12/2014
a.
Technical
Exception
<No>
563
564
565
566
567
Technical
Exception
<No>
568
Unsupported Language
Technical
Exception
<No>
569
Digital signature
verification failed (this
means that authentication
request XML was
modified after it was
signed)
570
https://developer.uidai.gov.in/site/book/export/html/18
Please submit
your request
again.
Technical
Exception
<No>
Technical
Exception
<No>
7/12/2014
571
Please reset
your PIN in
UIDAI updation
application and
use new PIN in
this application.
572
Technical
Exception <no>
573
Technical
Exception
<No>
574
575
576
577
FIR usage not allowed as Application can have a client level Technical
per license
check to restrict/allow entry of
Exception
FIR attribute as per license of
<No>
AUA.
https://developer.uidai.gov.in/site/book/export/html/18
19/23
7/12/2014
578
579
580
PIN usage not allowed as Application can have a client level Technical
per license
check to restrict/allow entry of
Exception
PIN attribute as per license of
<No>
AUA.
581
Fuzzy matching usage not Application can have a client level Technical
allowed as per license
check to restrict/allow entry of
Exception
ms attribute in pi, pa and pfa
<No>
element as per license of AUA.
582
Local language usage not Application can have a client level Technical
allowed as per license
check to restrict/allow entry of
Exception
local language attribute in pi, pa
<No>
and pfa element as per license of
AUA.
584
585
710
Missing Pi data as
specified in Uses
720
Missing Pa data as
specified in Uses
Same as 710
https://developer.uidai.gov.in/site/book/export/html/18
Technical
Exception
<No>
Technical
Exception
<No>
Technical
Exception
<No>
20/23
7/12/2014
721
Same as 710
Technical
Exception
<No>
730
Same as 710
Technical
Exception
<No>
740
Same as 710
Technical
Exception
<No>
800
810
Technical
Exception
<No>
811
Your Biometric
data is not
available in
CIDR.
812
https://developer.uidai.gov.in/site/book/export/html/18
21/23
7/12/2014
kindly proceed
with the BFD
process for
successful
authentication.
820
Same as 710
Technical
Exception
<No>
821
Same as 710
Technical
Exception
<No>
901
No authentication data
Application should validate that
found in the request (this User giveatleast one auth factor
corresponds to a
before encryption of PID block.
scenario wherein none of
the auth data Demo,
Pv, or Bios is present)
Technical
Exception
<No>
902
Please enter
dob in specified
date format or
enter age in
specified range.
910
Same as 710
Technical
Exception
<No>
911
Same as 710
Technical
Exception
<No>
912
Invalid ms value
Same as 710
Technical
Exception
<No>
913
https://developer.uidai.gov.in/site/book/export/html/18
7/12/2014
930939
Technical
Exception
<No>
940
Unauthorized ASA
channel
Technical
Exception
<No>
941
Technical
Exception
<No>
980
Unsupported option
Technical
Exception
<No>
997
Your Aadhaar
number status is
not active.
Kindly contact
UIDAI Helpline.
998
999
Unknown error
Technical
Exception
<No>
Please contact
authsupport team of
UIDAI
https://developer.uidai.gov.in/site/book/export/html/18
23/23