1. Our APIs
  2. Payments
  3. Client data encryption key get open banking

Client Data Encryption Key Get Open Banking

swaggerSwagger

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. We support envelope encryption with AES-256-GCM. This page explains the process.

Endpoints Summary

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

Step 1: Get public key

The first step in the encryption process is to request a public key and its key ID from us. Then securely store the information and track the expiry of the key. Public keys expire after 120 days.

Here are a few things to note when submitting your request:

Mandatory headers
  • a) x-api-key – Use the API key we provided by email for the relevant environment.
  • b) x-fapi-financial-id – This is the unique identifier for BMO. It always needs to be 001.
  • c) x-request-id – This is the unique identifier of your request.
  • d) x-app-cat-id – Based on the table below, use the value based on the payment API you’re using. If you intend to use multiple payment APIs, then please choose only one of the applicable values.
Apix-app-cat-id
ACH Payments80613
Electronic Funds Transfer (EFT)87335
Wire Payments87102
Instant Payments87679
Data body
  • a) applicationCatalogueId – Use the same value you chose for the x-app-cat-id header above.
  • b) Key alias – Follow the format alias/EXT-ENC-{API KEY} where you use the API key for the relevant environment.
Post
/issued-device-administration/client-data-encryption-key/get
Try It arrow

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

body required
Request Body

Response

Table JSON

Step 2: Generate content encryption key (CEK)

Now it's time to create a symmetric content encryption key (CEK) in 32 bytes and securely store the CEK.

Step 3: Generate initialization vector (IV)

Create an initialization vector (IV) in 12 bytes. You may then append "Additional Authenticated Data" (AAD). AAD is optional for our environments and can be any fixed string.

Step 4: Encrypt your 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.
  • Apply Base64 encoding on AuthTag.
  • Append the Base64-encoded, encrypted payload and the Base64-encoded AuthTag with '|' as the delimiter (Base64{EncryptedPayload} + '|' + Base64{AuthTag}) and include this in the data section of your request payload.

Step 5: 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. We support SHA-1 and SHA-256 for the OAEP hash.
  • For part 3, hash your CEK using the SHA-256 algorithm. Then apply Base64 encoding to the hashed CEK.
  • For part 4, append the IV you generated earlier and the optional AAD. Then apply Base64 encoding.
  • 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.
    • a. Example of final format if OAEP hash (default hash or SHA-1) is used to encrypt the CEK: Base64(keyid).Base64(encrypted CEK).base64(hashed CEK).Base64(IV).GCM
    • b. Example of final format if OAEP hash SHA-256 is used to encrypt the CEK: Base64(keyid).Base64(encrypted CEK).base64(hashed CEK).Base64(IV).GCM-256

Step 6: Decrypt your response

Finally, it's time to decrypt our API response. Here's how:

  • We encrypt the response payload using AES‑256‑GCM with the same Content Encryption Key (CEK) and Initialization Vector (IV) that you used to encrypt your original request.
  • You can find the encrypted response in the data element. The value consists of two Base64‑encoded components separated by a pipe (|) delimiter
    • Ciphertext
    • AuthTag
  • Split the value at the pipe delimiter (|) to obtain the Ciphertext and AuthTag.
  • Decrypt the Ciphertext using AES‑GCM by supplying:
    • Original CEK
    • Original IV
    • Extracted AuthTag
    • Optional Associated Authentication Data (AAD), if required by the protocol