Data Encryption

TLS protects data in transit. ABDM also requires application-layer encryption for sensitive fields and health data. Aadhaar numbers and OTPs use RSA public-key encryption. HIP health data transfer uses ECDH on Curve25519 and AES-GCM.

What must be encrypted

If a request field is named otp, aadhaar, loginId, or similar in an identity flow, assume it must carry the Base64 of the RSA-encrypted value, not the raw digits.

Identity encryption scheme

ABDM uses RSA with OAEP padding. In JCE/Java notation:

RSA/ECB/OAEPWithSHA-1AndMGF1Padding

• Key: the RSA public key from ABDM's certificate (2048-bit).
• Padding: OAEP with SHA-1 digest and MGF1 mask generation.
• Output: raw ciphertext bytes, then Base64-encoded into the JSON field.

Step 1 — Fetch the public certificate

The certificate is fetched once (then cached) using your gateway bearer token. Different services publish their own certificate:

curl "https://abhasbx.abdm.gov.in/abha/api/v3/profile/public/certificate" \
-H "Authorization: Bearer $TOKEN" \
-H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
-H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)"

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
...base64 DER of the 2048-bit RSA public key...
-----END PUBLIC KEY-----

curl "https://apihspsbx.abdm.gov.in/v4/int/api/v1/auth/cert" \
-H "Authorization: Bearer $TOKEN"

The response body is a PEM-encoded public key (a -----BEGIN PUBLIC KEY ----- block). Cache it — it changes rarely — but refresh on a decryption error in case it rotated.

Step 2 — Encrypt the value

Load the PEM key, RSA-encrypt the UTF-8 bytes of the value with OAEP/SHA-1, and Base64-encode the result.

import crypto from "node:crypto";
 
/** publicKeyPem: the PEM string returned by the certificate endpoint. */
export function encryptForAbdm(value, publicKeyPem) {
  return crypto
    .publicEncrypt(
      {
        key: publicKeyPem,
        padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
        oaepHash: "sha1", // switch to "sha256" if the API requires it
      },
      Buffer.from(String(value), "utf8"),
    )
    .toString("base64");
}
 
// Usage:
// const encAadhaar = encryptForAbdm("999999990019", pem);
// const encOtp = encryptForAbdm("123456", pem);

Step 3 — Send the ciphertext

Put the Base64 string into the request field. For example, verifying an Aadhaar OTP during HPR ID creation:

curl -X POST "https://apihspsbx.abdm.gov.in/v4/int/v2/registration/aadhaar/verifyOTP" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "otp": "BASE64_RSA_ENCRYPTED_OTP",
  "txnId": "TXN_ID"
}'

{
"txnId": "TXN_ID",
"authResult": "success",
"message": "OTP verified"
}

Health data encryption scheme

Use this scheme when the HIP sends health data to an HIU. See the full flow in Milestone 2 data transfer.

The HIU sends its public key material in the health information request. The HIP then creates sender key material and encrypts the FHIR bundle.

{
  "cryptoAlg": "ECDH",
  "curve": "Curve25519",
  "dhPublicKey": {
    "expiry": "2026-08-11T15:06:33.000Z",
    "parameters": "Curve25519/32byte random key",
    "keyValue": "<base64-hip-public-key>"
  },
  "nonce": "<base64-hip-32-byte-nonce>"
}

Operational rules

• Cache the certificate, but key it by service and refresh on any decryption/padding failure — the key can rotate.
• One value per encryption — encrypt the Aadhaar and the OTP separately; don't concatenate them.
• RSA size limit — a 2048-bit key with OAEP/SHA-1 encrypts at most ~214 bytes. Aadhaar numbers and OTPs are tiny, so this is never a constraint, but don't try to RSA-encrypt large blobs.
• UTF-8 in, Base64 out — mismatched encodings are the most common cause of "invalid encrypted value" errors.
• No plaintext at rest — don't persist Aadhaar/OTP even briefly; encrypt in the same function that receives them.