> For the complete documentation index, see [llms.txt](https://docs.emudhradigital.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.emudhradigital.com/api-reference/conventions-and-security.md).

# Conventions and Security

These rules apply to the eSign v2, eSign v3 and Remote Key Storage APIs (CCA specifications).

## Transport and format

* HTTPS only (TLS 1.2+); `Content-Type: application/xml` for API calls.
* Browser hand-offs use auto-submitting HTML forms (`application/x-www-form-urlencoded`).
* All APIs are stateless; correlate with `txn` and `resCode`.

## Message signing

| Direction     | Rule                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------- |
| ASP → eMudhra | Every request XML carries a W3C XML-DSig `<Signature>` made with the ASP certificate mapped to the `aspId`. |
| eMudhra → ASP | Every response XML is signed by eMudhra. **Verify it before using the response.**                           |

## Common attributes

| Attribute | Rule                                                                                                      |
| --------- | --------------------------------------------------------------------------------------------------------- |
| `ts`      | ISO 8601 timestamp in IST; must be within ±30 minutes of eMudhra server time.                             |
| `txn`     | ASP transaction ID; unique per ASP (v3 / Remote: per ASP–ESP pair per calendar day). Echoed in responses. |
| `aspId`   | Issued by eMudhra at onboarding.                                                                          |
| `resCode` | eMudhra response code; constant for a transaction. Store it for audit.                                    |

## Document hashes

* Compute **SHA-256** of the document on your server and send it as a hex string in `<InputHash>`.
* For PDFs, hash the `/ByteRange` of a prepared signature placeholder, then embed the returned CMS in `/Contents`.
* `docInfo` (≤ 50 characters) is shown to the signer; the document itself is never sent.

## Signature types (`responseSigType`)

| Value                         | Returned signature                                     |
| ----------------------------- | ------------------------------------------------------ |
| `raw` / `rawrsa` / `rawecdsa` | Raw PKCS#1 or ECDSA signature                          |
| `PKCS7`                       | CMS SignedData with signer certificate                 |
| `PKCS7pdf`                    | CMS with chain, CRL/OCSP and timestamp — for PDF (LTV) |
| `PKCS7complete`               | CMS with all issuer certificates and revocation data   |

## Security checklist

* Keep the ASP signing key in an HSM or secure keystore — never in a browser or mobile app.
* Validate eMudhra's response signature and `txn` match.
* Make `responseUrl` handlers idempotent.
* Never collect or log Aadhaar numbers, OTPs, PINs, AuthPINs or biometrics.