Response Message Level Encryption

API Response Message Level Encryption (MLE), when enabled is a security feature that ensures sensitive data is protected when transmitted from Banked's APIs. This feature is particularly important for handling personal and financial information, providing an additional layer of security beyond standard TLS encryption.

OverviewCopy URL

The process involves:

1. Generate an RSA key pair
2. Share your public key with Banked
3. Deccrypt the response messages with your private key

Prerequisites:

• Valid Banked account with API access
• OpenSSL or SSH keygen available for key generation
• Development environment with cryptographic libraries
• Understanding of RSA asymmetric encryption/decryption

Encryption Algorithm The encryption algorithm used is RSA-OAEP-256 – RSAES using Optimal Asymmetric Encryption Padding with a hash function of SHA-256 and a mask generation function of MGF1 with SHA-256

Implementation StepsCopy URL

Step 1. Generating RSA Key PairCopy URL

You can generate the key pair using any method that suits your environment. Banked supports any RSA key length, though we recommend following NIST guidelines with a minimum key length of 2048 bits.

Here is an example approach:

Using OpenSSL (recommended):

# Generate private key (2048-bit minimum, 4096-bit recommended)
openssl genrsa -out private_key.pem 4096

# Extract public key
openssl rsa -in private_key.pem -RSAPublicKey_out -out public_key.pem

Using SSH keygen:

ssh-keygen -t rsa -b 4096 -m PEM -f banked_key

Step 2. Share Your Public Key with BankedCopy URL

Email your public key to your Banked Solution Architect or to the Banked Support Team support@banked.com

What PKCS#1 PEM format looks like:

-----BEGIN RSA PUBLIC KEY-----
MIICCgKCAgEA...
[base64 encoded key data]
...
-----END RSA PUBLIC KEY-----

Encrypted ResponseCopy URL

• Content-Type: application/jose
• Format: JWE (JSON Web Encryption)
• Algorithm: RSA-OAEP-256
• Encoding: A256GCM

Signing Key RotationCopy URL

API Clients are responsible for managing their key lifecycles. To rotate keys:

1. Generate a new RSA key pair
2. Share the new public key with Banked via support@banked.com
3. Wait for a new set of API credentials to be sent to you from Banked.
4. Switch your application to use the new private key
5. Notify Banked to deprecate the old key

Code ExmpleCopy URL

import pkg from 'node-jose';
const {JWE} = pkg;
const {JWK} = pkg;

//Replace this with the JWE token from the Banked API responses.
let jweToken = "<place JWE from response body here>";

const keyDataBase64String =
"-----BEGIN PRIVATE KEY-----\n" +
"<Place RSA-OAEP-256 private key in PEM format here>"
"-----END PRIVATE KEY-----";

//generate JWK from keyDataBase64String
const key = await JWK.asKey(keyDataBase64String, 'pem');
async function decrypt(encrypted) {
if (!encrypted) throw new Error('Missing encrypted data.')
return JWE.createDecrypt(key).decrypt(encrypted);
}
let decryptedData = await decrypt(jweToken);
console.log(decryptedData.plaintext.toString());