Download the PHP package itxshakil/aadhaar-offline without Composer

Aadhaar Offline for PHP

Read and verify Aadhaar Offline e-KYC files and Aadhaar Secure QR codes in any PHP application, with no framework required. It opens the share-code-protected ZIP, checks UIDAI's digital signature locally against certificates you pin, and gives you a typed object with the resident's name, date of birth, gender, address and photo. It can also confirm a mobile number or email against the hashes in the file, and it never needs the full Aadhaar number.

Don't trust the XML, verify it. Many integrations accept whatever XML a KYC vendor returns, or whatever ZIP a user uploads, without checking the signature. Anyone can edit an XML file. This package checks the signature against UIDAI's public certificate before you rely on any of the data.

Using Laravel? Install itxshakil/laravel-aadhaar-offline. It builds on this package and adds a facade, validation rules, Artisan commands, events, an upload form and a test fake.

Status: 0.x. The test suite uses synthetic, self-signed fixtures. The Offline e-KYC ZIP path has also been checked against a real 2026 UIDAI download and UIDAI's published uidai_offline_publickey_2026.cer. Secure QR follows UIDAI's published layout and well-maintained open-source decoders, but has not yet been checked against a real card. Please open an issue if anything differs.

Features

• 🔐 Local signature verification against certificates you pin. The key is never read from the document, so a forged file can't bring its own key.
• 📷 Secure QR codes from Aadhaar letters, PVC cards and e-Aadhaar PDFs, legacy and V2/V3/V5 layouts, including the photo.
• 🗜️ Share-code ZIPs (AES-256 and ZipCrypto) with zip-bomb, size and entry-count guards.
• 🧾 Typed result: OfflineKyc with name, date of birth, Gender, Address, Photo and generation time.
• 📱 Mobile/email matching with UIDAI's iterated SHA-256 scheme.
• ⏱️ Freshness rules, separate for downloaded XML (default 3 days) and printed QR codes (off by default).
• 🙈 Privacy-safe by default: only the last four digits are exposed, and toArray(), JSON and dumps leave out hashes, share codes and raw payloads.
• 🛡️ XXE-hardened XML parsing.
• 🧪 Test helpers that build signed synthetic payloads, so tests never need real Aadhaar data.
• 🔍 PHPStan max level with strict rules, and no runtime dependency beyond robrichards/xmlseclibs.

Requirements

Quick Start

Download uidai_offline_publickey_2026.cer from UIDAI and check its fingerprint first; see docs/installation.md.

Reading Payloads

Every reader returns an unverified OfflineKyc. Call verify(), or use the verify* shortcuts.

What you get

Verification

verify() runs two checks and throws on the first failure:

1. Signature. For XML, the document must contain exactly one enveloped signature, directly under the root, with a single reference covering the whole document (URI=""). For Secure QR codes, the 256-byte RSA signature must cover every byte before it. Either way, the signature is checked against your configured certificates only, never a key embedded in the file.
2. Freshness. The timestamp in the reference ID must be within maxAgeDays for XML (default 3) or qrMaxAgeDays for QR codes (off by default, because printed cards are old).

For audit logs, pass onVerified and onRejected callbacks to create(). Log referenceId(), maskedAadhaar() and the exception class, never the payload itself.

How it works in detail: docs/verification.md

Matching Mobile and Email

The file doesn't contain the mobile number or email, only hashes. Ask the user for their number and check it:

For Offline e-KYC XML the hash is SHA-256 of value + shareCode, repeated N times, where N is the last digit of the Aadhaar number (0 and 1 both mean once). Matching needs the share code, so pass it to fromXml() when you use vendor XML. Legacy Secure QR codes use the same scheme without the share code; version 2 and later carry only mobileLastFourDigits().

Only trust a match after verify(). A forged file can contain any hash.

Privacy

• The full Aadhaar number is never part of the result; only the last four digits are.
• toArray(), json_encode(), var_dump() and stack traces leave out the share code, hashes and raw payloads.
• Exception messages contain no personal data.
• The photo stays in memory. If you store it, use private storage and a random file name.
• Store Aadhaar numbers masked, with maskedAadhaar() or Shakil\AadhaarOffline\Support\AadhaarNumber::mask().

For format-only checks, use AadhaarNumber::isValid() and Verhoeff::validate() from Shakil\AadhaarOffline\Support.

More: docs/privacy.md

Testing

Never use real Aadhaar data in tests. Shakil\AadhaarOffline\Testing\Fixtures builds signed synthetic ZIPs, XML and Secure QR codes with a key generated at runtime, and OfflineKycFactory builds OfflineKyc objects directly.

Full testing guide: docs/testing.md

Error Handling

Every exception extends Shakil\AadhaarOffline\Exceptions\AadhaarOfflineException.

Contributing

Contributions are welcome. See CONTRIBUTING.md. Report security issues privately as described in SECURITY.md.

Never commit real Aadhaar data, Offline e-KYC files or private keys. The test suite generates its own keys and synthetic payloads.

License

The MIT License (MIT). See LICENSE.md.

This package is not affiliated with or endorsed by UIDAI. "Aadhaar" is used only to describe compatibility.