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.

Authentication at a Glance

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!

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.

  1. You need Java 1.6 or above installed on your computer and an Internet connection to run this sample.
  2. Unzip "auth-client-bin-1.5.zip" into a directory. You will see the following contents.
    Sample Client Runtime Directory Listing
  3. Run "runclient.bat" to run the sample application.
  4. 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.
  5. This opens a command promt asking for OS type, enter 1 or 2 (based on your OS) and press ENTER.
  6. This opens the sample authentication client. See screenshot below.
    Auth Client Main Screen
  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.
    Auth Client Preferences Screen
     
  8. Now you are ready to test!!
  9. 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.
  10. Click "Authenticate" button at the bottom right
  11. You should see a green tick mark within the "Authentication Status" field. See the following screen
    Auth Client Result Screen
  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.
  

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.

  1. 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.
  2. Unzip "auth-client-source-1.5.zip" into a directory. You should now see a directory named "auth-client-source-1.5" there
  3. Navigate to "auth-client-source-1.5" directory. You should see the following listing.
    Auth Client Source Directory Listing
  4. Within "Command Prompt", change directory ("cd") to "auth-client-source-1.5"
  5. Run "mvn eclipse:eclipse" command. If "Maven\bin" is not in path, please add it. Otherwise "mvn" command will not run.
  6. You should see "Build Successful" message like below.
    Auth Client Sample - Maven Build Screen
  7. Launch Eclipse and create a new workspace (or use current workspace if you prefer)
  8. Choose "File->Import" menu. This lanuches an import dialog.
  9. Choose "Existing Projects into Workspace" option and click "Next"
  10. Click "Browse" button next to "Select Root Directory"
  11. Navigate to "auth-client-source-1.5" and select the directory
  12. This will list 4 projects - "uidai-auth-client", "uidai-auth-xsd-model", "uidai-biometric-integration-api", and "uidai-sample-gui-app"
  13. Make sure all projects are selected. See screen below.
    Auth Client Sample - Eclipse Import Screen
  14. Click "Finish" to import all 4 projects into workspace
  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-gui-app" 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".
    Auth Client - Eclipse Run Configuration Menu
  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.
    Auth Sample Client - Eclipse Run Config Dialog
  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.
  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.
  21. Enter "999999990019" in "Aadhaar Number" field and "Shivshankar Choudhury" in the "Name" field. Additional data is available on "Testing Data" page.
  22. Click "Authenticate" button at the bottom right
  23. You should see a green tick mark within the "Authentication Status" field. See the following screen
    Auth Client Result Screen
  24. 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.
  25. 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)

 

Test Codes:

 

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
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


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.

 

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.

Certificate Detail Expiry Date
uidai_auth_prod.cer (latest) 5 Aug 2015

 

Certificate Detail Expiry Date
uidai_auth_prod_old.cer (old) 3 Oct 2013

 

 

 

              

              

 

 

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 Expiry Date
uidai_auth_sign_prod.cer (latest) 29 Jul 2015

 

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.

Certificate Detail Expiry Date
uidai_auth_stage.cer (latest) 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.

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.

  1. Unzip "c-auth-client-source-1.5.zip" into a directory. You should now see a directory named "c-auth-client-source-1.5" there
  2. Navigate to "c-auth-client-source-1.5" directory. You should see the following listing.

    Directory Listing

  3. 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
  4. The below DEFINES values are need to modify before compiling:
    LICENCE_KEY
    UIDAI_PUBLIC_CERITIFICATE
    AUA_PRIVATE_CERTIFICATE - Required for Digital Signature
  5. Auth Xml API documentation is available under the doc folder

    API Functions
     

  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

  9. On a successful make, you should see the executable file AuthClient.
  10. 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.

API Error Handling

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.

API Error Code

Description

Provision Required in the Application

Suggested Message to the User

Suggested instructions 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 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.

 

Finger print is not given properly, scanner has some dust accumulated, fingers were wet, position of finger not appropriate, scanned finger NFIQ not good

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 request should not contain more than 10 FMR/FIR records.     Auth Request has more than 10 finger 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 "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.
401 "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.

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 “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 than please contact technical helpdesk.

Non compliance with supported Authentication API version structure in CIDR.

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 before sending request to CIDR.

 

 

Ensure the authentication request is being sent 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.

This error will be returned if AUA and ASA do not have 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 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.

Either Device/Client/Server date/time is behind current one or old stored pid is getting sent.

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 some unsupported characters were found in Indian language values, “lname” or “lav”)

Application should have client/server level checks to stop users to input unsupported characters.

Technical Exception <No>

 

 

some unsupported characters were found 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

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

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”

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 initiate BFD application to help resident identify their best fingers. See Aadhaar Best Finger Detection API specification.

Application should make provison to initiate BFD application based on the error code to help resident identify their best fingers.

 

You have not done best finger detection so kindly proceed with the BFD process for successful authentication.

Refer Aadhaar Best Detection API specifications for details on the BFD process.

Resident has not done “Best Finger Detection”.

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>

 

 

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.

997 Invalid Aadhaar Status AUA application should have mechanism to handle this scenario as Aadhaar number is valid but its status is not active. Your Aadhaar number status is not active. Kindly contact UIDAI Helpline.   Aadhaar number status is either lost, deceased etc. and currently not active.
998 Invalid Aadhaar Number AUA application should have a client level validation for Aadhaar number validity ie. should be 12 digits and conform to Verhoeff algorithm. Ensure you have entered correct Aadhaar number.  Please retry with correct Aadhaar number after sometime. Ensure you have entered correct Aadhaar number. Please retry with correct Aadhaar number after sometime. If client level validations are done then Aadhaar number does not exist in CIDR.

999

Unknown error

 

Technical Exception <No>

Please contact authsupport team of UIDAI