HCX Protocol
v0.9
v0.9
  • Summary*
  • Glossary*
  • Context
  • Introduction to HCX*
  • Technical Specifications
    • Open Protocol
      • Registries*
        • QR Code Specifications*
      • Claims Data Exchange (HCX) Protocol
        • Message Flows*
          • Primary Message Flow
          • Additional Message Flows
            • Redirect
            • Forward
            • Intra Cycle Communication*
              • Seeking Supporting Information
              • Seeking Beneficiary Consent
              • Seeking Account Information
            • Relay
            • Third party Information sharing
          • Notifications
            • Categories
            • List of key topics
        • Message Structure
        • API Specifications*
          • Registry APIs
          • Primary Flow APIs
          • Supporting APIs
          • Notification APIs
        • Error Handling
      • Data Security and Privacy
        • Transport Security
        • Message Security and Integrity
        • API Security*
      • Audit and Reporting
    • Digital Network Policies
  • Domain Specifications
    • Domain Data Models
      • Handling Attachments
      • Handling Processing Errors
    • Terminologies
    • Domain Specific Languages (DSLs)
    • FHIR Implementation Guide*
  • Business Policy Specifications
    • Access Control (Roles)*
    • Guidelines for Participant Onboarding*
      • Sandbox process
      • Production onboarding (Go live)*
      • Potential De-boarding scenarios
    • Guidelines for Grievance Redressal
      • Scope of disputes
      • Involved participants
      • Guideline process for dispute resolution
      • Guidelines for leveraging FTA
      • Next steps
    • Guidelines for SLAs and ecosystem satisfaction
    • Guidelines for Operating charges
    • Guidelines for Beneficiary Authentication by Providers/Payors
    • Guidelines for Event audits
    • Reference Templates
      • HCX - Terms of use
      • Payer-Provider addendum
      • Payer-Policyholder addendum
    • Next steps
  • Use cases*
    • OPD
      • Typical Workflows
        • Cashless
        • Reimbursement
      • Mapping to the HCX protocol
        • Cashless
        • Reimbursement
    • IPD
      • Typical Workflows
        • Cashless
        • Reimbursement
      • Mapping to the HCX protocol
        • Cashless
        • Reimbursement
    • Implementation Considerations
  • Contributing to the protocol
  • Future Focus Areas*
Powered by GitBook
On this page
  • Message Encryption
  • Message Decryption

Was this helpful?

Edit on GitHub
  1. Technical Specifications
  2. Open Protocol
  3. Data Security and Privacy

Message Security and Integrity

Use of JWE to ensure payload security and integrity

PreviousTransport SecurityNextAPI Security*

Last updated 1 year ago

Was this helpful?

TO ensure that sensitive information in the actual domain objects is not accessible even to the HCX, protocol requires the payload defined by the domain data specifications to be encrypted using a separate asymmetric encryption key of the final recipient established at the time of participant onboarding into the registry. API then carries the encrypted value of the payload. The payload encryption is expected to be performed using JSON web encryption as per algorithm and enclosed values fixed in the protected headers section above. At this point in time, no unprotected headers are envisioned in the HCX protocol. We also do not envision multiple recipient delivery in the current version of the HCX protocol.

Message Encryption

The high-level steps to encrypt the payload using the public key of the final recipient are:

  1. Find out the public key of the recipient through registry lookup on HCX.

  2. Let JWE protected header be = BASE64URL(UTF8((Registered JOSE headers) U (HCX Protocol Headers) U (HCX Domain Headers)). Please note that initial version of HCX protocol requires following JOSE headers: {"alg":"RSA-OAEP","enc":"A256GCM"}

  3. Generate a random Content Encryption Key (CEK) as per the encryption algorithm.

  4. Encrypt the CEK with the recipient's public key using the RSAES-OAEP algorithm to produce the JWE Encrypted Key.

  5. Base64url-encode the JWE Encrypted Key.

  6. Generate a random JWE Initialization Vector.

  7. Base64url-encode the JWE Initialization Vector.

  8. Let the Additional Authenticated Data encryption parameter be: ASCII(BASE64URL(UTF8(JWE Protected Header))).

  9. Perform authenticated encryption on the plaintext with the AES GCM algorithm using the CEK as the encryption key, the JWE Initialization Vector, and the Additional Authenticated Data value, requesting a 128-bit Authentication Tag output.

  10. Base64url-encode the ciphertext.

  11. Base64url-encode the Authentication Tag

  12. Assemble the final representation in flattened JSON serialization (Section 7.2.2 of ):

{
  "protected":"<integrity-protected header contents from step 2 above>",
  "encrypted_key":"<encrypted key contents from step 5 above>",
  "aad":"<additional authenticated data contents from step 8 above>",
  "iv":"<initialization vector contents from step 7 above>",
  "ciphertext":"<ciphertext contents from step 10 above>",
  "tag":"<authentication tag contents from step 11 above>"
}

Message Decryption

The high-level steps to decrypt and verify the integrity of the payload using the private key of the final recipient are:

  1. From the received JSON serialized JWE token, Base64url decode the encoded representations of the JWE Protected Header (protected), the JWE Encrypted Key (encrypted_key), the JWE Initialization Vector (iv), the JWE Ciphertext (ciphertext), the JWE Authentication Tag (tag), and the JWE AAD (aad), following the restriction that no line breaks, whitespace, or other additional characters have been used.

  2. Let the JOSE Header be the JWE Protected Header. Verify that the resulting JOSE Header does not contain duplicate Header Parameter names.

  3. Determine the Key Management Mode employed by the algorithm specified by the "alg" (algorithm) Header Parameter.

  4. Verify that the JWE uses a key known to the recipient.

  5. Decrypt the JWE Encrypted Key to produce the CEK. The CEK MUST have a length equal to that required for the content-encryption algorithm.

  6. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE Protected Header)). This protected header is (Registered JOSE headers) U (HCX Protocol Headers) U (HCX Domain Headers).

  7. Let the Additional Authenticated Data encryption parameter be ASCII(Encoded Protected Header).

  8. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization Vector, the Additional Authenticated Data value, and the JWE Authentication Tag (which is the Authentication Tag input to the calculation) using the specified content-encryption algorithm, returning the decrypted plaintext and validating the JWE Authentication Tag in the manner specified for the algorithm, rejecting the input without emitting any decrypted output if the JWE Authentication Tag is incorrect.

It is recommended to rotate these encryption keys once every year and mechanisms implemented for the providers/payers/HCX to intimate the ecosystem about the potential compromise of the keys.

Here is a sample of the set of libraries that you can explore:

  1. Bouncy castle

  2. Openssl

  3. NaCl

  4. Libgcrypt

  5. PyNaCl

  6. TweetNaCl

Following section provides details on the mechanism to secure API authentication and access.

Verify that the octet sequence resulting from decoding the encoded JWE Protected Header is a UTF-8-encoded representation of a completely valid JSON object conforming to ; let the JWE Protected Header be this JSON object.

Participating systems are expected to follow best practices guidelines as in to ensure the security of the payload.

RFC7516
RFC7516
RFC 7159
RFC8725