Field Level Encryption

Field Level Encryption (FLER) is a security feature that ensures sensitive data is protected when transmitted to and 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. Choose your response protection method (redaction vs encryption)
2. Get API credentials and share public keys with Banked
3. Fetch Banked's public keys from the JWKS endpoint
4. Generate RSA key pairs and manage encryption keys
5. Encrypt sensitive data fields before sending requests
6. Handle encrypted or redacted responses appropriately

Prerequisites:

• Valid Banked account with API access

Implementation StepsCopy URL

The implementation can be broken down into the following steps:

Step 1. Choose Response Protection MethodCopy URL

Before starting integration, decide how you want to handle sensitive data in responses:

Step 2. Get API CredentialsCopy URL

Contact your Banked representative to receive:

• For Partner integrations: New OAuth credentials for generating tokens
• For all integrations: Basic Auth credentials
• For response encryption: Share your RSA public key

Step 3. Get Banked's Public KeysCopy URL

Banked provides public keys for encryption via a JWKS (JSON Web Key Set) endpoint:

GET https://api.banked.com/.well-known/jwks.json

Response FormatCopy URL

{
  "keys": [
    {
      "kty": "RSA",
      "use": "enc",
      "alg": "RSA-OAEP-256",
      "kid": "1654876509",
      "n": "jbNTpPiCVdm4D-0UEcM9NkbKJk6Ro9eVfgdK8yC0IzBL2k6D6ebB_QyI5dwFiLT3ZZUp1-zQta3o...GB5R3XqD",
      "e": "AQAB",
      "bknd.exp": 1666797757,
      "bnkd.iat": 1664205757
    }
  ]
}

Step 4. Generate and Manage KeysCopy URL

RSA Public Key (for Response Encryption)Copy URL

An RSA public key is a cryptographic key used in asymmetric encryption. It consists of two parts:

• A public key that can be shared with others
• A private key that must be kept secure

In the context of FLER:

• You generate and keep the private key
• You share the public key with Banked
• Banked uses your public key to encrypt responses
• You use your private key to decrypt the responses

Generating RSA KeysCopy URL

Generate an RSA key pair using OpenSSL:

# Generate a 2048-bit RSA private key
openssl genrsa -out private.pem 2048

# Extract the public key
openssl rsa -in private.pem -pubout -out public.pem

Key RequirementsCopy URL

• Key size: 2048 bits minimum
• Format: PEM
• Algorithm: RSA
• Public exponent: 65537 (0x10001)

Content Encryption Keys (CEK)Copy URL

A Content Encryption Key is a symmetric key used to encrypt the actual data payload.

For each sensitive data object:

1. Generate a new CEK
2. Encrypt the CEK using Banked's public key
3. Use the CEK to encrypt the sensitive data
4. Never reuse CEKs between requests

Step 5. Encrypt Sensitive DataCopy URL

1. Identify fields requiring encryption (see Fields Requiring Encryption)
2. Encrypt each sensitive field using the process above
3. Prefix encrypted field names with encrypted_

Example RequestCopy URL

// Original
{
  "payee": {
    "name": "John Doe",
    "account_number": "12345678",
    "sort_code": "123456"
  }
}

// Encrypted
{
  "encrypted_payee": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiMTY1NDg3NjUwOSJ9..."
}

Step 6. Handle ResponsesCopy URL

Redacted ResponseCopy URL

{
  "payee": {
    "name": "[REDACTED]",
    "account_number": "[REDACTED]",
    "sort_code": "[REDACTED]"
  }
}

Encrypted ResponseCopy URL

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

API ReferenceCopy URL

Fields Requiring EncryptionCopy URL

Payment Sessions APICopy URL

Bank Accounts APICopy URL

Mandates APICopy URL

Error ResponsesCopy URL

Invalid Encryption KeyCopy URL

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
    "errors": [
        {
            "code": "invalid",
            "source": "encryption key",
            "title": "invalid encryption key"
        }
    ]
}

Code ExamplesCopy URL

Go ImplementationCopy URL

package main

import (
    "crypto/rsa"
    "fmt"
    "log"

    "github.com/lestrrat/go-jwx/jwk"
    "gopkg.in/square/go-jose.v2"
)

// Get Banked's public key
func GetJWK() (jwk.Key, *rsa.PublicKey, error) {
    set, err := jwk.Fetch("https://api.banked.com/.well-known/jwks.json")
    if err != nil {
        return nil, nil, err
    }

    key := set.Keys[0]
    r, err := key.Materialize()
    if err != nil {
        return nil, nil, err
    }

    rk, ok := r.(*rsa.PublicKey)
    if !ok {
        return nil, nil, fmt.Errorf("not an RSA Public Key")
    }

    return key, rk, nil
}

// Encrypt sensitive data
func Encrypt(b []byte) ([]byte, error) {
    k, r, err := GetJWK()
    if err != nil {
        return nil, err
    }

    encrypter, err := jose.NewEncrypter(
        jose.A256GCM,
        jose.Recipient{
            Algorithm: jose.RSA_OAEP_256,
            Key: r,
            KeyID: k.KeyID(),
        },
        nil,
    )
    if err != nil {
        return nil, err
    }

    encrypted, err := encrypter.Encrypt(b)
    if err != nil {
        return nil, err
    }

    return []byte(encrypted.CompactSerialize()), nil
}

Best PracticesCopy URL

1. Generate new CEK for each sensitive data object
2. Do not reuse CEKs between requests
3. Cache public keys and refresh before expiry
4. Handle key rotation gracefully
5. Implement proper error handling for encryption/decryption failures