DigiLocker HMAC and Issuer Signature Checks
Distinguish DigiLocker download integrity from independent issuer signatures. Plan exact-byte checks, safe parsing, and result labels your application can use.
A DigiLocker download can carry a message authentication code for the response body. A separate issuer signature can provide evidence about the document itself. Record the checks your integration actually runs.
The requester specification describes a Base64 HMAC calculated with SHA-256 and the client secret. Use the bytes received in the applicable response body for that check. Requester v2.4 specification
Separate the checks in your evidence record
| Check | Input | Evidence to record |
|---|---|---|
| Source | Approved endpoint, issuer, and document metadata | Which configured source provided the document |
| Response integrity | Response bytes, HMAC header, and the configured secret | Whether the bytes matched the provider's MAC |
| Issuer signature | Signed document and approved issuer trust material | Whether an independent signature check passed, failed, or was skipped |
| Validity | Dates and relevant period in the verified response | Whether the document covers the reference date |
| Business decision | Evidence plus the policy for the intended use | Which action the application permits |
The last row belongs to your application. Define a review path when the evidence is incomplete.
Check the response before parsing
- Read the response with a size limit.
- Obtain the expected MAC from the documented header.
- Compute the MAC over the original response bytes.
- Compare the expected and calculated values with a constant-time comparison.
- Stop processing if the check fails.
- Parse the approved document format with a restricted parser.
Keep this sequence tied to the endpoint and contract. If the body wraps a Base64 document, check the documented outer bytes before decoding. Reformatting XML or changing a line ending can change the MAC even when the visible fields look identical.
Test distinct failure modes
Use a synthetic fixture containing a document and a test secret. Change one byte in the body while keeping the old MAC. The integrity check should fail.
Then use an unmodified response with a valid test MAC and a document without a signature your verifier can validate. The integrity result can pass. Record issuer signature as unverified if your application does not run that check. If your acceptance policy requires that signature, send the case for review.
Keep secrets and document contents out of diagnostic events. A check type, request reference, and bounded failure code are enough for the first investigation. DigiLocker troubleshooting guide.
Review evidence requirements with NamoID
The controlled NamoID driving licence preview checks download integrity and reports issuer signatures as not_verified. Share the checks your application requires. The team can help you map each requirement to evidence and identify where an independent check belongs. Message the NamoID team in Slack