Government ID Masking: How to Build It

How to use this page

This page walks you through building one thing: making sure a government identity number stops existing in your systems once you no longer need it, while the document it came from remains usable.

Every other product guide on this site is about collecting something. This one is about getting rid of it. That inversion changes the whole shape of the work — there is no conversion funnel to optimise and no revenue attached, and the failure is invisible until somebody looks.

Masking and vaulting are two different duties

Two separate duties, frequently confused, with different sources and different failure modes:

What this is not:

• Not an OCR project. Detection is a solved problem and the least of your difficulties. Steps 4 to 8 are the work.
• Not only about Aadhaar. PAN, passport, voter ID and driving licence numbers are personal data under the DPDP framework even without a dedicated vault rule.
• Not finished when the pipeline ships. The number is already in places nobody listed. Step 6.

The whole journey, in one table

Steps 1 and 2 — what you hold, and what you may keep

Step 1 — Find out where the number already is

Start with an inventory, not an architecture. In every organisation that has been operating for more than a year, the answer is longer than the application diagram suggests.

The places to look, in roughly the order teams are surprised by them:

• The obvious ones: the customer table, the KYC document store, the onboarding database.
• Application logs. A request body logged at debug level, an error trace with the payload attached, a third-party logging service that has been retaining it for two years.
• The support system. Customers send their Aadhaar as an attachment; agents paste numbers into ticket notes. This is almost always the largest uncontrolled store.
• Email. Documents sent to an operations mailbox, sitting in an archive.
• Analytics and monitoring, where a form field was captured as an event property.
• Backups and data warehouses, which hold every version of the table you are about to clean.
• Video KYC recordings, where the customer held the card up to the camera.

Step 2 — Decide what you are entitled to keep

The cheapest number to protect is the one you never stored. Before building a vault, work through what you actually need.

Do you need the number, or do you need the verification? For most onboarding journeys the answer is the second: you need to know the identity was verified, not to retain the identifier afterwards. Where that is true, store the verification result and the reference, and discard the number entirely.

Do you need the document image, or the extracted fields? Name, date of birth and address often suffice, in which case the image can go.

What is your retention period, and who set it? “Indefinite” is a decision, usually one nobody made. Under the DPDP framework personal data is not to be kept beyond the purpose it was collected for, and there is no legitimate-interest basis in India to fall back on.

Steps 3 to 5 — mask, tokenise, vault

Steps 3 to 5 — Mask, tokenise, vault

from dataclasses import dataclass

# STEP 3. MASK AT CAPTURE. THE VISIBLE LAYER.
# The requirement is specific: the first EIGHT digits, and the QR code, which
# encodes the full number and is the part teams forget. Last four stay
# visible; name, date of birth, gender and address stay visible.

def mask_document(image):
    regions = detect(image)                    # number, QR, and any repeats
    assert regions["qr"], "QR not located — do not store this image"
    out = image
    for r in regions["number"]:                # a card may show it twice
        out = redact(out, r, keep_last=4)
    out = redact(out, regions["qr"], keep_last=0)
    verify = extract_digits(out)               # read your own output back
    assert not verify["full_number_visible"], "masking did not take"
    return out

# STEP 4. TOKENISE. THIS IS THE ACTUAL PRODUCT.
# UIDAI Circular No. 14 of 2025: every business system stores a REFERENCE KEY
# instead of the number. The actual number must not be stored in any business
# database other than the Aadhaar Data Vault.
#
# The reference key must not computationally permit working back to the
# number. So: a random token, not a hash of the number, and not a derivation
# from it -- a hash is guessable across a 12-digit space.

@dataclass
class Reference:
    key: str            # random, opaque, stored everywhere
    created_at: str

def tokenise(aadhaar, vault):
    assert len(aadhaar) == 12 and aadhaar.isdigit()
    existing = vault.lookup_by_number(aadhaar)     # inside the vault only
    if existing:
        return existing
    ref = Reference(key=random_token(32), created_at=now_ist())
    vault.store(aadhaar=aadhaar, reference=ref)    # the ONLY place both meet
    return ref

# Everything downstream stores ref.key. Nothing downstream stores aadhaar.
def create_customer(db, profile, ref):
    assert "aadhaar" not in profile, "number reached the business layer"
    return db.insert({**profile, "id_reference": ref.key})

# STEP 5. THE VAULT.
VAULT_REQUIREMENTS = {
    "separate_store": True,        # not a column on an existing table
    "single_logical_instance": True,
    "encryption": "AES-256_or_higher",
    "keys_in_hsm": True,           # and the HSM is not shared with anyone else
    "network": "restricted_zone_isolated_from_other_internal_zones",
    "access": "internal_systems_only",
    "ha_dr": True,
    "access_logged": True,
}

# WHAT TO CHECK
# [ ] the QR is masked, not just the digits. It encodes the whole number
# [ ] read your own masked output back and assert the number is gone. A
#     redaction that draws a box without removing the underlying pixels is
#     not a redaction, and some libraries do exactly that
# [ ] the reference key is RANDOM. A hash of a 12-digit number is brute
#     forceable in seconds
# [ ] assert at the boundary that no business write contains the number.
#     Make it fail the request, not log a warning
# [ ] the HSM is not shared with another legal entity. Where a group shares
#     one, each entity needs logical isolation and its own crypto keys
# [ ] the vault is one logical instance, not one per service

THE finding, and it is the reason this page exists: masking the image is the visible tenth of the obligation. The requirement is that the number stops existing in your business systems.

UIDAI's framework has been in place since a first circular in July 2017 and was substantially revised by Circular No. 14 of 2025, dated 18 July 2025, with updated FAQs on 3 November 2025. Its central instruction is unambiguous: all systems requiring storage of Aadhaar numbers should maintain only the reference key, and the actual number should not be stored in any business database other than the Aadhaar Data Vault.

Alongside it: the vault as a single logical instance per entity, encryption at AES-256 or higher, encryption keys held in an HSM that is not shared with any other legal entity, the whole thing in a restricted network zone isolated from other internal zones, accessible through internal systems only, with high availability and disaster recovery.

Note also what belongs in the vault: not only the number, but the e-KYC XML, the Aadhaar PDF returned in an e-KYC response, and the related demographic data. A team that vaults the number and leaves the e-KYC response in object storage has moved the problem rather than solved it.

Steps 6 to 8 — purge, serve back, prove

Steps 6 to 8 — Purge, serve back, prove

# STEP 6. PURGE WHERE IT ALREADY LEAKED. THE UNGLAMOROUS ONE.
# A clean pipeline from today does nothing about the last three years.

PURGE_TARGETS = [
    "application_logs", "error_traces", "third_party_log_retention",
    "support_tickets", "ticket_attachments", "operations_mailbox",
    "analytics_event_properties", "data_warehouse", "backups",
    "vcip_recordings", "developer_laptops_and_exports",
]

def purge_plan(target, scanner):
    hits = scanner.find_id_numbers(target)      # pattern + checksum, not regex alone
    return {
        "target": target,
        "found": len(hits),
        # Deleting a support ticket may break an audit trail you are separately
        # required to keep. Redact IN PLACE where the record must survive.
        "action": "redact_in_place" if target in ("support_tickets", "vcip_recordings")
                  else "delete",
        "backups_note": "a purge that skips backups restores the problem on the "
                        "next restore -- schedule it against the retention cycle",
    }

# STEP 7. SERVE IT BACK, FOR THE FEW CASES THAT NEED IT.
def resolve(reference_key, purpose, actor, vault):
    # Every de-tokenisation is an event with a reason and a name attached.
    assert purpose in ("regulatory_filing", "authentication", "lawful_request")
    entry = vault.read(reference_key, actor=actor, purpose=purpose)
    vault.log_access(reference_key, actor, purpose, at=now_ist())
    return entry            # held in memory, never written downstream

# STEP 8. PROVE IT.
def evidence(period, vault, scanner):
    return {
        "access_log": vault.accesses(period),        # who, what, why, when
        "unresolved_scan_hits": scanner.sweep(PURGE_TARGETS),
        "retention_expiries_actioned": vault.expired_and_deleted(period),
        "hsm_key_rotation": vault.key_events(period),
        "masking_sample_reverified": sample_and_recheck(period, n=50),
    }

# WHAT TO CHECK
# [ ] run the scanner against your OWN systems on a schedule, not once. New
#     leaks appear with every feature that logs a request body
# [ ] validate with the checksum, not the pattern. Any 12 digits matches a
#     naive regex, and a phone number plus two digits is not an Aadhaar
# [ ] purge backups against the retention cycle, or the next restore undoes
#     the work
# [ ] every de-tokenisation is logged with an actor and a purpose. An access
#     log with no purpose column cannot answer the question that gets asked
# [ ] re-verify a sample of masked documents periodically. Pipelines drift,
#     and a model update can change what gets detected
# [ ] timestamp everything in IST. An access log in UTC is read by a
#     regulator in IST, and a five-and-a-half hour offset on an access
#     timestamp is exactly the detail that turns a routine question awkward

The second finding, and the one that costs the most: a clean pipeline from today does nothing about the last three years. The number is already in your logs, your support tickets, your operations mailbox, your warehouse and your backups, and it got there through ordinary engineering decisions that nobody would call a mistake at the time.

Two details that decide whether the purge works. Validate with the checksum rather than the pattern — a naive twelve-digit regex matches phone numbers, order ids and timestamps, and a scan that returns thousands of false positives is a scan nobody finishes. And schedule the backup purge against the retention cycle, because a restore from an unpurged backup puts everything back.

What it costs

Three versions you could build

Do not store it at all

Build: verify identity → keep the verification result and a reference → discard the number and, where you can, the image.

You get: the obligation reduced to almost nothing. This is the correct answer far more often than it is chosen, and the reason it is not chosen is usually that nobody asked whether the number was needed after onboarding.

Mask and tokenise

Build: masking at capture including the QR → random reference key → encrypted vault with HSM-held keys in an isolated zone → a boundary assertion that fails any business write containing the number → a scheduled scan across logs, tickets and warehouse.

Trade: real infrastructure and a real retrofit, against an obligation that is not optional if you are regulated.

The full estate

Build: the above, plus the historical purge including backups, frame-level redaction on V-CIP recordings, de-tokenisation logged with actor and purpose, retention expiry actioned automatically, and periodic re-verification of masked output.

It breaks when: the project is scoped as the pipeline and the estate is treated as a later phase. The estate is the project; the pipeline is the part that stops it getting worse.

What goes wrong

Where to go next

Sources

Every figure, rule and date on this page, and where to check it. Entries are typed so you can see which are primary-sourced and which are industry reporting.