HCX instances are expected to log each API call received along with the non encrypted details (domain headers, sig/enc algorithm details, sender & recipient details) and status of signature verification.

Key Requirements:

• HCX instances should provide reports against the audit logs for different actors - payors, providers, beneficiaries, regulators, observers. Each HCX instance shall publish the list of reports supported by that instance and also define the level/details of information in each report.

• The audit information stored should be made available through an API, so that the participating systems can query the audit log related to them.

• Each HCX instance shall define an archival policy for retention & deletion of audit logs. The policy shall also define the process for accessing the logs after archival, if the HCX instance has support for it.

• It is recommended for HCX instances to have a configuration to control the amount of information that gets stored in the audit logs.

Questions for Consultation

Question 1

Apart from the list mentioned here, what other audit and reporting requirements would you expect HCX to fulfil?

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 RFC7516 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))).

1. 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.

2. Base64url-encode the ciphertext.

3. Base64url-encode the Authentication Tag

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

{
  "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. 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 RFC 7159; let the JWE Protected Header be this JSON object.

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

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

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

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

7. 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).

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

9. 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.

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

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

Questions for Consultation

Question 1

This section suggests JSON Web Encryption as per RFC7516 as the mechanism for payload security and integrity. Which alternative mechanism for payload security and privacy would you explore for HCX? Kindly provide the pros and cons of the alternative mechanism.

Question 2

In addition to the best practices mentioned in RFC8725, which other best practices/guidelines would you suggest to HCX participants for data security and privacy?

The protocol defines an API key-based security for authentication and authorization of the API calls between the participating systems and the HCX gateway. HCX instances have to generate the API keys in the form of JWT tokens (RFC7519) and shall mandatorily set an expiry time for all the generated tokens.

In future versions, HCX instances may support JWTs issued by other system identity providers, e.g. Health Facility Registry’s IDP.

Securing HCX Gateway APIs

All participant systems (e.g.: providers, payers) should obtain an API key from the HCX gateway with which it identifies itself to the gateway. When calling any API on the HCX gateway, the participant system should pass the API key as part of the 'Authorization' http header.

Steps to obtain the API key:

After a successful verification and onboarding of a participant system onto the participant registry, the HCX instance managing the registry shall share the following details via email, SMS, or both with the participant system:

• client_id: this is the identifier of the participant in the participant registry.

• client_secret: a unique secret is generated for the participant by the HCX instance. The client_secret value shall be stored in the participant registry in an encrypted format and shall not be sent in the registry APIs.

The participant system can call ‘/token/generate’ API along with the client_id and client_secret they have received to obtain the API key.

POST /token/generate
Content-Type: application/json
Request-Body:
 {
   "client_id": "client_id received by the participant",
   "client_secret": "client_secret received by the participant"
 }

HCX instance would respond with the API token upon successful validation of the client_id and client_secret values:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
Response-Body:
 {
   "access_token": "the API key, a JWT access token",
   "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
   "token_type": "Bearer",
   "expires_in": 300
 }

JWT Token Structure:

API keys are expected to be in JWT format and signed as per JSON web signature (RFC7515). The API key should have three elements separated by periods (.): BASE64URL(UTF8(JOSE Header)), BASE64URL(JWS Payload), and BASE64URL(JWS Signature).

• JOSE Header should be a JSON with the following values:

{
  "typ":"JWT",
  "alg":"HS256"
}

• JWS Payload should be a claim set containing the mandatory claims jti, iss, sub, iat and exp.

  • jti - unique identifier for the JWT

  • iss - HCX instance identifier

  • sub - client_id of the participant

  • iat - unix timestamp at which the JWT is issued

  • exp - the expiration time after which the JWT must not be accepted for processing

• JWS Signature must be computed in the manner defined for HS256 algorithm over the input ASCII(BASE64URL(UTF8(JOSE Header)) || '.' || BASE64URL(JWS Payload)) using the client_secret value of the participant.

Revoking API Keys

HCX instances can revoke the API key of a participant by generating a new client_secret and updating it in the participant registry. The participant system has to generate a new API key by calling the ‘/token/generate’ API with the new client_secret value.

Securing Participant System APIs

HCX instances while making the calls to the participant system will use a self-generated JWT token with the following elements:

• JOSE Header should be a JSON with the following values:

{
  "typ":"JWT",
  "alg":"RS256"
}

• JWS Payload should be a claim set containing the mandatory claims jti, iss, sub, iat and exp.

  • jti - unique identifier for the JWT

  • iss - HCX instance identifier

  • sub - same as iss claim, HCX instance identifier

  • iat - unix timestamp at which the JWT is issued

  • exp - the expiration time after which the JWT must not be accepted for processing

• JWS Signature must be computed in the manner defined for RS256 algorithm over the input ASCII(BASE64URL(UTF8(JOSE Header)) || '.' || BASE64URL(JWS Payload)) using the private key of the HCX instance.

Participant systems should validate the API key signature using the public key of the HCX instance.

Questions for Consultation

Question 1

This section suggests JSON Web Tokens as per RFC7519 as the mechanism for API security. Which alternative mechanism for API security would you explore for HCX? Kindly provide the pros and cons of the alternative mechanism.

All communications between health claims exchange(s) and participating entities are expected to be done using Transport Layer Security. Therefore all APIs are expected to work only as HTTPS in the production environments.

Given the sensitive nature of the information involved during claims processing - personal details, health-related information, etc., it is imperative that the data is kept secure during the exchange process (security if data while stored at sender and receiver is expected to be as per the prevailing data security regulation of the data storage).

There are many language specific libraries available that can help you implement the required encryption/signing/verification that is described above.

In order to achieve this, various approaches are defined in the subsequent sections.