| API Developer Portal

Client Data Encryption Key Get Open Banking

For security reasons, all requests to and responses from our Payments APIs as well as fields shared via our Account Validation API need to be encrypted. This page explains the process.

Endpoints Summary

post

/issued-device-administration/client-data-encryption-key/get

Get public key

The first step in the encryption process is to request a public key and its key ID from us and then securely store the information.

Post

/issued-device-administration/client-data-encryption-key/get

Try It

Request

Code Samples

Headers

Content-Type

string

Example

application/json

x-fapi-financial-id required

string

x-fapi-customer-last-logged-time

string

x-fapi-customer-ip-address

string

x-fapi-customer-user-agent

string

x-fapi-interaction-id

string

x-client-id

string

Authorization

string

x-request-id required

string

x-api-key

string

x-app-cat-id required

string

Body

Response

Table JSON

RetrieveClientKeyResponse { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

exceptionResult { . . .}

}

Generate content encryption key (CEK)

Next, you need to create a symmetric content encryption key (CEK) in 32 bytes and securely store the CEK.

Generate initialization vector (IV)

Create an initialization vector (IV) in 12 bytes and append “Additional Authenticated Data” (AAD) (AES-256-GCM).

Encrypt message

Now that you have your CEK and IV ready, let’s encrypt your payload:

Make sure the input message you want to encrypt is in string/text format.
- JSON object should be in JSON string.
- Default encoding should be UTF-8.
Select the symmetric CEK cipher algorithm AES-256-GCM.
Apply the encryption algorithm, CEK and IV to the input message to generate the encrypted message buffer.
Apply base64 encoding to the encrypted message buffer to generate ciphertext in string/text format.

Generate x-crypto-key header

Before you can share your encrypted payload, you need to generate your x-crypto-key header. The header will consist of up to 5 parts for AES-256-GCM with all parts concatenated to form the final header. Once generated, you will then pass the x-crypto-key in the header of your API requests along with the encrypted payload.

For part 1, apply base64 encoding on the key ID of the public key you retrieved from us earlier.
For part 2, encrypt the CEK you generated earlier using the public key. Make sure the padding is set to RSA_PKCS1_OAEP_PADDING (AES-256-GCM). Then apply base64 encoding to the encrypted CEK.
For part 3, hash your CEK using the SHA-256 algorithm. Then apply base64 encoding to the hashed CEK.
For part 4, apply base64 encoding to the IV you generated earlier. (AES-256-GCM)
For part 5, identify the padding mode used in the envelop encryption of the CEK. This part is optional.
For the final x-crypto-key header, concatenate all parts with “.” (single dot) as the delimiter.
- Example of final format if OAEP is used to encrypt the CEK: Base64(keyid).Base64(encrypted CEK).base64(hashed CEK).base64(IV).GCM
- Example of final format if SHA256 is used to encrypt CEK: Base64(keyid).Base64(encrypted CEK).base64(hashed CEK).base64(IV).GCM-256