AADHAAR AUTHENTICATION API
AADHAAR authentication service will be exposed as stateless service
over HTTPS with mutual SSL authentication (server and client certificate
validation). Usage of HTTP allows any device such as computer, mobile
phone, micro-ATM devices, and PoS systems to communicate over broadband,
GPRS, and similar communication channels.
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. For establishing a secure channel, AUAs
are required to be registered and their public key needs to be shared
with UIDAI. Process for registration and key sharing will be specified
later.
Following is the URL format for AADHAAR authentication service:
https://<
host>/<
ac>/<
uid[0]>/<
uid[1]>/
API input data should be sent to this URL using POST parameter “input”.
Details
host – AADHAAR authentication server name. Currently it is “auth.uidai.gov.in”.
ac – A unique code for the AUA which is assigned by
UIDAI during AUA registration process. This is an alpha-numeric string
having maximum length 40.
uid[0] and uid[1] – First 2 digits of AADHAAR Number. Used for load-balancing.
For all valid responses, HTTP response code 200 is used. All
application error codes are encapsulated in response XML element. In the
case of connection and other server errors, standard HTTP error
response codes are used (4xx codes such as 403, 404, etc.). HTTP
automatic redirects also should be handled by AUA server.
Input Data Format
AADHAAR authentication will use XML as the data format for input and
output. To avoid sending unnecessary data, do not pass any optional
attribute or element unless its value is different from default value.
Any bad data or extra data will be rejected.
Following is the data format for authentication API:
<Auth uid=”" tid=”" ac=”" ver=”" txn=”">
<Skey>encrypted and encoded session key</Skey> <Uses
pi=”" pa=”" bio=”" bt=”" pin=”" otp=”"/> <Data>encrypted and
then encoded block</Data> </Auth>
“Data” element contains “Pid” (Personal Identity Data) element which
is a base-64 encoded encrypted block. Complete “Data” block should be
encrypted at the time of capture on the capture device. See next chapter
for details.
Following is the format for “Pid” element:
<Pid ts=”"> <Demo>
<Pi ms=”E” name=”" gender=”M|F|T” dob=”" phone=”" email=”"/>
<Pa ms=”E” co=”" house=”" street=”" lm=”" loc=”" vtc=”" dist=”"
state=”" pc=”"/> </Demo> <Bios>
<Bio>encoded biometric</Bio> <Bio type=”FMR|FIR|IIR”>encoded biometric</Bio> </Bios>
<Pv otp=”" pin=”"/> </Pid>
Details
Element: Auth (mandatory)
root element of the input XML for authentication service.
Attributes:
uid – (mandatory) AADHAAR Number of the resident
tid – (mandatory) For Registered devices, send its unique Terminal ID. For Public devices, value should be passed as “public”.
ac – (mandatory) A unique code for the AUA which is
assigned by UIDAI during AUA registration process. This is an
alpha-numeric string having maximum length 40.
ver – (optional) version of the API. Defaulted to
latest version. Suggested to use latest version always by leaving this
attribute unless an application wants specific version compatibility.
Currently only valid value is “1.0″.
txn – (optional) AUA specific transaction
identifier. AUA can choose to pass this as part of input. This is
returned as part of response as is. This can be an alphanumeric string
of maximum length 50.
Element: Data (mandatory)
Contains the encrypted “Pid” element in base-64 encoding
Element: Uses (mandatory)
This element specifies the authentication factors used by the
request. When an authentication factor is specified in this element,
that specific attribute must be present in the encrypted data block.
This is particularly useful in situations where the AUA does not fully
control the terminal device, but wishes to maintain a certain level of
control on the authentication transaction.
Attributes:
pi – (mandatory) Valid values are “y” or “n”. If the
value is “y” then at least one attribute of element “Pi” (part of
“Demo” element) should be used in authentication. Otherwise, it is not
mandated.
pa – (mandatory) Valid values are “y” or “n”. If the
value is “y” then at least one attribute of element “Pa” (part of
“Demo” element) should be used in authentication. Otherwise, it is not
mandated.
bio – (mandatory) Valid values are “y” or “n”. If
the value is “y” then at least one biometric element “Bio” (part of
“Bios” element) should be used in authentication. Otherwise, it is not
mandated.
bt – (mandatory only if “bio” attribute has value
“y”) provide a comma separated list of biometrics used. Valid values
that can be used in this comma separated list are “FMR”, “FIR”, and
“IIR”. If “FMR” is part of the list, then at least one “Bio” element
with type FMR should be used. Similarly, if “FIR” or “IIR” are part of
the list, then at least one “Bio” element with those types must be used.
pin – (mandatory) Valid values are “y” or “n”. If
the value is “y” then PIN should be used in authentication. Otherwise,
“pin” is not mandated.
otp – (mandatory) Valid values are “y” or “n”. If
the value is “y” then OTP should be used in authentication. Otherwise,
“otp” is not mandated.
Element: Skey (mandatory only for Public devices)
Value of this element is base-64 encoded value of encrypted session key. See next chapter for encryption details.
Element: Pid (mandatory)
Attributes:
ts – (mandatory) Timestamp at the time of
demographic and biometric input capture. This is in ISO 8601 date and
time format “YYYY-MM-DDThh:mm:ss”. Time zone automatically defaulted to
IST (UTC +5.30).
AUAs can queue authentication requests and send it to AADHAAR
authentication server to support occasional lack of network connectivity
on the field. Maximum time up to which requests can be queued will be
defined by UIDAI policy. During initial release, this will be configured
to 24 hours. All requests with “ts” value older than this limit will be
rejected.
Element: Demo (optional)
- Contains child elements “Pi” and “Pa” both of which are optional.
- All demographic data fields as per KYR specifications.
Element: Pi (Optional)
- This element captures attributes related to “Personal Identity”
Attributes:
- ms – (optional) “Matching Strategy” for “name” attribute. Currently
only the value “E” (Exact) is supported. This is used only when “name”
attribute is specified. Future releases will support fuzzy matching.
- name – (optional) Name of the resident.
- gender – (optional) Valid values are “M” for male, “F” for female, and “T” for transgender.
- dob – (optional) Date of Birth in “YYYY-MM-DD” format. If only year needs to be authenticated, then use format “YYYY”.
- phone – (optional) Registered mobile phone number of the resident.
- email – (optional) Registered email address of the resident.
Element: Pa (Optional)
This element captures attributes related to “Personal Address”. These
are address fields as provided by the resident during enrolment or
later updates. Only attributes that are sent as part of input will be
compared.
Attributes:
- ms – (optional) “Matching Strategy” for address attributes.
Currently only the value “E” (Exact) is supported. This is used only
when at least one address attribute is specified.
- co – (optional) “Care of” person’s name.
- house – (optional) House identifier.
- street – (optional) Street name.
- lm – (optional) Landmark if any.
- loc – (optional) Locality where resident resides.
- vtc – (optional) Name of village or town or city.
- dist – (optional) District name.
- state – (optional) State name.
- pc – (optional) Postal pin code.
Element: Bios – (optional)
This element can have one or many “Bio” elements carrying biometric records to be matched.
Element: Bio (optional)
base 64 encoded biometric record
Attributes:
type – (optional) This attribute specifies type of
the biometric. Valid values are “FMR” (Finger Minutiae), “FIR” (Finger
Image), and “IIR” (Iris Image). Defaulted to “FMR”.
FMR – The biometric data is of type Fingerprint Minutiae Record. This
data is in ISO minutiae format with no proprietary extensions
allowed. o FIR – The biometric data is of type Fingerprint Image Record.
The data is a fingerprint image packaged in ISO 19794-4 format, which
could contain a compressed or uncompressed image, of type PNG, WSQ, or
Jpeg2000. o IIR – The biometric data is of type Iris Image Record. The
data is an iris image packaged in ISO 19794-6 format, which could
contain a compressed (or uncompressed) image, which could be of type
PNG, or Jpeg2000.
Element value contains base-64 encoded biometric record.
Element:
Pv (optional)
This element (“Pin Value”) is used to support additional secret “pin”
or “otp” or both for supporting multi-factor authentication.
Attributes:
pin – (optional) Actual value of PIN as set by resident. This attribute contains a 6 digit numeric value.
otp – (optional) Most recently activated
challenge-response OTP value for resident. Resident can send an
SMS/Email to a specified short code or to specified email address to
obtain an OTP and then use the last active OTP as part of
authentication. This attribute contains a 6 digit numeric value. Unlike
PIN, OTP is a one-time usage token.
Output Data Format
Authentication API does not provide any identity data as part of the
response. All it does is to match given input and respond with a
“yes/no”. Response XML is as follows:
<AuthResp ret=”y|n” code=”" txn=”" err=”"/>
Details
Element: AuthResp Attributes:
ret – this is the main authentication response. It is either “y” or “n”.
code – unique alphanumeric authentication response
code having maximum length 40. AUA is expected to store this for future
reference for handling any disputes. AADHAAR authentication server will
retain authentication trail only for a short period of time as per UIDAI
policy. After that period, older authentication trails will be deleted
and this code will become unusable.
txn – Authenticator specific transaction identifier. This is exactly the same value that is sent within the request.
err – Failure error code. If authentication fails
(“ret” attribute value is “n”), this attribute provides any of the
following codes:
“100″ – “Pi” (basic) attributes of demographic data did not match.
“200″ – - “Pa” (address) attributes of demographic data did not match
“300″ – Biometric data did not match
“500″ – - Invalid encryption
“510″ – Invalid XML format
“520″ – Invalid device
“530″ – Invalid authenticator code
“540″ – - Invalid version
“550″ – Invalid “Uses” element attributes
“700″ – Invalid demographic data
“710″ – Missing “Pi” data as specified in “Uses”
“720″ – Missing “Pa” data as specified in “Uses”
“730″ – Missing PIN data as specified in “Uses”
“740″ – Missing OTP data as specified in “Uses”
“800″ – - Invalid biometric data
“810″ – Missing biometric data as specified in “Uses”
“999″ – - Unknown error