UIDAI Stub

1. Preparation & Hardware

• Install a UIDAI-certified RD Service (Mantra, Morpho, etc.) on the client machine.
• Ensure the device reachability via http://localhost:11100 (standard RD port).
• Cryptography: This stub uses real RSA/AES encryption. Keys are located in /keys.
• Rotate Keys: To generate new keys, run php generate_keys.php.

2. Frontend Workflow (Capture PID)

The frontend must call the RD Service to capture biometric data. This results in an encrypted PID block.

// Example JS to call RD Service
fetch('http://localhost:11100/rd/capture', {
    method: 'CAPTURE',
    body: '<PidOptions ver="1.0">...</PidOptions>'
}).then(res => res.text()).then(xml => {
    // Send this PID XML to your backend
});

3. Backend Workflow (Build Auth XML)

Construct the official Auth v2.5 XML. This is the core document that identifies the resident.

4. e-KYC Transformation (The "Rad" Step)

To request e-KYC data, you do not call the Auth endpoint directly. Instead, you wrap the Auth XML inside a Kyc request.

// PHP Example
$fullAuthXml = "<Auth...>...</Auth>"; 
$base64Rad = base64_encode($fullAuthXml);

$kycRequest = '<Kyc ver="2.5" ra="F" rc="Y" lr="N" de="N" pfr="Y">
  <Rad>' . $base64Rad . '</Rad>
</Kyc>';

5. Handling the Response

The stub returns a <Resp> block. Inside the textContent is the Base64-encoded KycRes.

// 1. Decode the outer Resp payload
$kycResXml = base64_decode($respContent);

// 2. Parse KycRes to get User Data
// Payload contains: <Poi> (Name/DOB), <Poa> (Address), <Pht> (Photo)

// Call the Vault Endpoint
$payload = json_encode(["aadhaar" => "999988887777"]);
$response = curl_post("/uidai/vault", $payload);
// Output: {"reference_key": "4e1a-8b2c-..."}

1. Health Check

Verify the stub is alive and responding.

curl -X GET https://agribid.auction/index.php/health

2. Aadhaar Vault (Tokenize)

Exchange a raw Aadhaar number for a secure Reference Key.

curl -X POST https://agribid.auction/index.php/uidai/vault \
-H "Content-Type: application/json" \
-d '{"aadhaar": "999988887777"}'

3. Aadhaar Vault (Retrieve)

Retrieve the original Aadhaar number using a Reference Key.

curl -X POST https://agribid.auction/index.php/uidai/vault/retrieve \
-H "Content-Type: application/json" \
-d '{"reference_key": "YOUR_REFERENCE_KEY"}'

4. Biometric Auth (v2.5)

Test the core authentication logic with a sample XML payload.

curl -X POST https://agribid.auction/index.php/uidai/auth \
-H "Content-Type: text/xml" \
-d '<?xml version="1.0" encoding="UTF-8"?><Auth uid="999988887777" tid="registered" ac="public" sa="public" ver="2.5" txn="STUB_TXN_001" lk="STUB_LK"><Uses pi="y" pa="y" pfa="n" bio="y" bt="FMR" otp="n" pin="n"/><Meta udc="device123" pip="127.0.0.1" lot="P" lov="18.52,73.85"/><Skey ci="20251222">BASE64_SKEY</Skey><Data type="X">BASE64_PID</Data><Hmac>BASE64_HMAC</Hmac><Signature>EXISTENCE_CHECK_ONLY</Signature></Auth>'

🚀 Step 1: Hide your Keys (ENV Setup)

Think of keys as your ATM PIN. You don't write them in your code; you put them in a "Secret Folder" called .env.

# Your .env file
UIDAI_PRIVATE_KEY_PATH="/var/www/keys/stub_private.pem"
UIDAI_CERT_PATH="/var/www/keys/stub_public.crt"
REDIS_URL="redis://127.0.0.1:6379"

🔄 Step 2: The "Translator" (JSON to XML)

Apps speak JSON (Simple), but UIDAI speaks XML (Complex). Your backend acts as the translator.

🧠 Step 3: The "Short-term Memory" (Redis)

Getting data from UIDAI is slow/expensive. Once you get the XML response, decrypt it and save it in Redis for 10-15 minutes.

• Why? If the user refreshes the page, you don't have to ask UIDAI again!
• How? Store it with a key like kyc_999988887777.

🏁 Step 4: Back to Simple (Final JSON)

Finally, take that complex XML result, turn it back into a simple JSON list (Name, Gender, Photo URL), and send it to your Mobile App.

💡 The Complete Flow Summary:

App (JSON) ⇢ Backend (Convert to XML) ⇢ Encrypt ⇢ UIDAI Stub (Process) ⇢ Receive XML ⇢ Decrypt ⇢ Save to Redis ⇢ Return JSON to App

Auth API Errors (<Info err="">)

e-KYC Response Errors (<Resp err="">)