Aadhaar API

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 alpha­numeric 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