Encrypted Requests

Encrypted payload requests and responses offer an additional layer of security for sensitive data being transmitted over the internet. A payer or aggregator can be configured to use envelope encryption to encrypt the data in the request and response of any API call. Interchecks will provide a payer dedicated Public RSA Key that will be used to encrypt the data sent to Interchecks. Interchecks will use the payer provided Public RSA Key to encrypt data sent to the payer. The presence of an http header, X-ENCRYPTED, will be used to identify encrypted requests.

Envelope Encryption

Envelope encryption is a pattern for sending data over the internet using a mix of AES and RSA encryption. Using this pattern, the data is encrypted using AES encryption and the AES key is encrypted using RSA encryption. Both the encrypted data and encrypted key are sent as the payload instead of the plaintext payload. The receiving party uses their RSA Private Key to decrypt the AES key, which is then used to decrypt the data into its original plaintext format.

Supported Encryption Algorithms

1. RSA Algorithms
   1. RSA/ECB/OAEPPadding with SHA-256 OAEP and MGF1 Padding
2. AES Algorithms
   1. AES/GCM/NoPadding
   2. AES/CBC/PKCS5Padding

Interchecks will use AES/GCM/NoPadding for encrypting and decrypting the payload unless otherwise specified. To use AES/CBC/PKCS5Padding, add a header of X-AES-MODE : CBC_PKCS5PADDING to the request. To explicitly specify AES/GCM/NoPadding, add a header of X-AES-MODE : GCM_NOPADDING to the request.

Sending Encrypted Payload To Interchecks

1. Add Http Header X-ENCRYPTED : <Payer ID>
2. Payload Encryption
   1. Use AES with an initialization vector (IV) for payload encryption.
   2. Use cipher algorithm "AES/GCM/NoPadding" (or development language equivalent).
      1. To use AES/CBC/PKCS5Padding, add Http Header X-AES-MODE : CBC_PKCS5PADDING
   3. Convert byte array to Base64Encoded string prior to sending.
3. Key and IV Encryption
   1. Encrypt both the Key and IV using the Interchecks provided RSA Public Key.
      1. Public Key can be provided in PEM or JsonWebKey (JWK) format
      2. RSA Public Key will be generated using a 4026 Modulus.
   2. Encrypt using a cipher algorithm of “RSA/ECB/OAEPPadding” with the following padding specifications.
      1. OAEP Padding: SHA-256
      2. MGF1 Padding: SHA-256
         • note that some languages/libraries default to SHA-1
         • Ex: “RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING” using Java’s Default Crypto Libraries will result in a SHA-1 MGF1 padding while the BouncyCastle library will use SHA-256.
   3. Convert byte array to a hexadecimal string prior to sending.
4. GET Requests
   1. Since a GET request does not have a body, the presence of the X-ENCRYPTED header will cause the response payload to be encrypted.

Receiving Encrypted Payload From Interchecks

1. Payload Decryption
   1. Interchecks will use AES with an initialization vector (IV) for payload encryption.
   2. Interchecks will use Cipher Algorithm "AES/GCM/NoPadding" (or development language equivalent).
      1. If the Http Header X-AES-MODE : CBC_PKCS5PADDING is present, "AES/CBC/PKSC5Padding" will be used.
   3. Interchecks will send payload as a Base64Encoded string.
2. Key and IV Decryption
   1. Use PrivateKey or Key Management System to decrypt the AES Key and IV.
      1. Interchecks will provide a KeyId (kid) to identify the PublicKey used to encrypt the AES Key and IV.
      2. Decrypt using RSA Cipher Algorithm of “RSA/ECB/OAEPPadding” with the following padding specifications.
         1. OAEP Padding: SHA-256
         2. MGF1 Padding: SHA-256
            • note that some languages/libraries default to SHA-1
            • Ex: “RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING” using Java’s Default Crypto Libraries will result in a SHA-1 MGF1 padding while the BouncyCastle library will use SHA-256.
   2. Interchecks will send the AES Key and IV as a hexadecimal string.

Encrypted Payload Format

An encrypted request or response will have a body in the following json format.

{
  "encryptedText": "base64Encoded String",
  "key": "Hexidecimal String",
  "kid": "String",
  "ivSpec": "Hexidecimal String"
}

When Interchecks receives a request with the X-ENCRYPTED header, we will attempt to convert the body into the above encrypted request object. If the body does not map to an encrypted request, Interchecks will respond with a 422 Error Code and a plaintext/unencrypted response that contains the expected format.

{
    "http_status": 422,
    "error_code": "ERR_PAYLOAD_ENCRYPTION_ERROR",
    "error_message": "Error Encountered. Expected: [encryptedText, key, kid, ivSpec]."
}