Health Data Flow

Once an HIU holds a granted consent artefact, it can request the covered records. This page walks the full data flow, including the encryption scheme.

End-to-end sequence

sequenceDiagram
  participant HIU
  participant GW as Gateway
  participant CM as HIE-CM
  participant HIP
  HIU->>GW: health-information request (artefact id, keys, dataPushUrl)
  GW->>CM: validate consent
  CM->>GW: forward to HIP
  GW->>HIP: health-information request
  HIP->>HIP: build FHIR bundles, encrypt
  HIP-->>HIU: POST encrypted data to dataPushUrl (direct)
  HIP->>GW: data transfer notification
  HIU->>GW: notify (TRANSFERRED / FAILED)

Steps:

1. HIU request — includes the consent artefact ID, requested date range, its ephemeral public key material, a nonce, and an HTTPS dataPushUrl.
2. Validation — the CM checks the artefact is still valid (not expired or revoked) and matches the requested range.
3. HIP prepares data — collects records for the consented care contexts and HI types, as FHIR R4 bundles.
4. Direct push — the HIP encrypts each bundle and POSTs to the HIU's dataPushUrl, chunked into pages with a transactionId.
5. Notifications — both sides notify the gateway of transfer status (health-information notify), which powers audit and retry visibility.

For HIP API steps, see Milestone 2 data transfer.

Encryption scheme

ABDM uses ECDH key agreement on Curve25519 with AES-GCM payload encryption (the "ECDH sender keys" model, based on the DHIS2/FIDELIUS reference implementation):

1. Both HIP and HIU generate ephemeral X25519 key pairs and 32-byte nonces.
2. The HIU sends its public key + nonce in the data request; the HIP returns its own in the data push (keyMaterial).
3. Each side derives the shared secret via ECDH, then derives the AES key using HKDF over the combined nonces.
4. Bundles are encrypted with AES-GCM; the HIU decrypts with the same derived key.

{
  "cryptoAlg": "ECDH",
  "curve": "Curve25519",
  "dhPublicKey": {
    "expiry": "2025-01-16T10:00:00Z",
    "parameters": "Curve25519/32byte random key",
    "keyValue": "BASE64_PUBLIC_KEY"
  },
  "nonce": "BASE64_32_BYTE_NONCE"
}

HIP-side checklist

• Validate the consent artefact ID and date range on every request
• Paginate large record sets (entries with content or link per page)
• Push within the expected SLA, then send the data-transfer notification
• Handle re-requests idempotently (same transactionId)

HIU-side checklist

• Host a reliable dataPushUrl endpoint (TLS, auth by transaction context)
• Decrypt, then validate checksums / integrity before use
• Send notify with TRANSFERRED / ERRORED status per transaction
• Store data only as permitted (accessMode), and purge at dataEraseAt