Aadhaar

Nodejs code for Aadhaar Auth API v2.5. This can be used as a reference to generate the XML file that can be sent to the Auth service.

Unfortunately, the Aadhaar API endpoints keep changing frequently. So, the code currently doesn't work out of the box. I'll update it with a working API if I get access to the current Auth service endpoint. The AUA private key is also expired. I'll update that as I get access to the latest version.

A part of the project depends on open-ssl. Make sure that it is installed. Feel free to fork / create PRs

Usage

Auth:

cd aadhaar
npm install
node lib/auth/xml.js

Main code in lib/auth/xml.js. Keys in res/. License Keys, Test data in utils/constants.js

Code explanation

Since I have received a couple of queries about how the code works, I've added a beginner-friendly high-level summary of a few cryptography concepts used by the Auth service:

Encryption

Encryption is a fundamental technique in cybersecurity that ensures data privacy by transforming readable information into an unreadable format, protecting it from unauthorized access and interception during transmission or storage. There are many encryption algorithms in use today for different purposes including encrypting the web traffic in HTTPS websites through the TLS protocol and signing transactions submitted to a blockchain, among others.

Usage in service: Encryption is used in multiple places in the service. Most importantly:

1. Pid block is encrypted using a dynamically generated session key using a symmetric encryption algorithm (Section 4.1)
2. The session key itself is encrypted using UIDAI public key using an asymmetric encryption algorithm (Section 4.1)
3. The XML message is signed with the private key of the AUA (Please note that this not the latest private key and is an expired old one) using an asymmetric algorithm (Signature element in Section 3.3.1)
4. The XML message is hashed and encrypted with the session key to validate that it was not tampered by any third-party after it was created (Hmac element in Section 3.3.1)

Symmetric / Asymmetric Encryption:

Symmetric encryption is an encryption technique that uses a single secret key for both encryption and decryption, making it efficient. Some popular symmetric encryption algorithms are: AES, 3DES and Blowfish

As opposed to symmetric encryption, Asymmetric encryption algorithms use a pair of keys (public and private) for encryption and decryption. A message encrypted with a private key can only be decrypted with its corresponding public key. Typically, these algorithms offer higher security levels compared to symmetric encryption algorithms, but they come at the cost of greater computational processing requirements. Some popular asymmetric encryption algorithms are: RSA and ECDSA

This is a good video to know more

Usage in service: The service utilizes both symmetric and asymmetric encryption techniques. The Pid block is encrypted using a symmetric session key (SKey). For the purpose of this service, this key is just some random 32 bytes generated on the fly by the client. The SKey itself is asymmetrically encrypted with UIDAI's public key. UIDAI's public key is provided in the developer portal. The key has a expiry date, and once it reaches the end of its validity period, it should be replaced with a fresh key that can be downloaded from the portal.

Digital Signature

A digital signature is a cryptographic technique used to verify the authenticity and integrity of digital messages, or documents. As the name suggests, a digital signature serves as a digital counterpart to a person's handwritten signature, and it can only be generated by an individual/organization who possesses the corresponding private key. It works by creating a unique digital fingerprint (hash) of the content and then encrypting that hash using a private key. Recipients can verify the signature using the sender's public key, ensuring that the data hasn't been tampered with and that it indeed came from the claimed sender. Know more here

Usage in service: In the Auth service, the generated Auth XML is signed with the AUA's private key. This signature is expected in a standard XML Signature format. Here is a sample description of the elements of a XML signature. For the Auth service, while I couldn't find the CanonicalizationMethod, Transforms and other algorithms expected by the service, I just took the algorithms used in the "Authentication API: Response Data Format" section (Section 3.4). Applying these gave a valid response to me in a previous version of the service

HMAC (Hash-based Message Authentication Code):

HMAC is a widely used cryptographic technique that enhances data integrity and authenticity. It is like a unique fingerprint for a message. It works by combining a secret key with a cryptographic hash function to create a unique code (the HMAC) for a given message or data. This code can be used to verify that the message has not been tampered with and that it was indeed generated by someone with knowledge of the secret key. Learn more about HMAC here.

Usage in service: The PID created in the service is hashed and encrypted using the session key to create the HMAC and added to the input XML in a Hmac tag. This HMAC will be verified by the service by decrypting it using the session key and then verifying the hash against the hash of the Pid block. Please note that this method is a bit different from the one discussed in the above video. The exact steps to create the HMAC is described in the Hmac element in Section 3.3.1

Encryption and Cryptography are vast fields and there are many sources that go in depth of what techniques can be used to secure data and how the algorithms that are used to do that work. But, as an overview, this playlist and this tutorial should suffice to understand the nitty gritties of the cryptography used in this service.

With that as a context, the code can be summarized to do the following steps:

1. Structure the data in XML format as expected by the API (xml.js buildXml)
2. Generate random 32 bytes and use it as the Session Key (encryptor.js getSessionKey)
3. Encrypt the session key using UIDAI's public key (encryptor.js encryptUsingSessionKey)
4. Sign the generated Auth XML using the AUA's public key (signer.js sign)
5. Send the signed XML to the service (xml.js testReq)

TODO

• Add service
• Add front-end
• Add other aadhaar apis
• Remove dependency on open-ssl by editing xml-signer
• Cleanup redundant crypto modules (pem, crypto)
• Add XSD verification
• Update README