Encryption

To protect sensitive data, our API support certain fields to be encrypted before transmission. This page explains how to encrypt data using RSA 2048-bit with OAEP padding and SHA-256.

1. Encryption Specification

• Algorithm: RSA

• Key size: 2048 bits

• Padding scheme: OAEP (Optimal Asymmetric Encryption Padding)

• Hash function: SHA-256 (used in OAEP)

• Input encoding: UTF-8

• Output encoding: Base64 (send this string in the request)

2. Public Key

You must use our RSA Public Key to encrypt the data. Zum Rails team will provide the public key. If you didn't receive it, please contact Zūm support.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----

3. Fields to Encrypt

When submitting requests, you may encounter fields such as:

• EncryptedNumber – Encrypted version of a sensitive number (e.g., card number).

You must send the Base64-encoded ciphertext in these fields. If an encrypted value is provided, the plaintext equivalent must be omitted.

4. Encryption Workflow

1. Convert the plaintext (e.g., card number) to a UTF-8 encoded byte array.

2. Encrypt the data with the RSA public key using OAEP + SHA-256.

3. Encode the resulting ciphertext in Base64.

4. Send the Base64 string in the Encrypted* field of the request.

5. Example Implementations

Node.js (using Web Crypto API)

import { webcrypto } from "crypto";
const { subtle } = webcrypto;

async function encryptData(plaintext, publicKeyPem) {
  // Convert PEM to CryptoKey
  const binaryDer = Buffer.from(
    publicKeyPem.replace(/-----(BEGIN|END) PUBLIC KEY-----/g, ""), 
    "base64"
  );

  const key = await subtle.importKey(
    "spki",
    binaryDer,
    { name: "RSA-OAEP", hash: "SHA-256" },
    false,
    ["encrypt"]
  );

  // Encrypt
  const encoded = new TextEncoder().encode(plaintext);
  const ciphertext = await subtle.encrypt({ name: "RSA-OAEP" }, key, encoded);

  // Return Base64
  return Buffer.from(ciphertext).toString("base64");
}

C# (.NET)

using System.Security.Cryptography;
using System.Text;

public static string EncryptData(string plaintext, string publicKeyPem)
{
    using var rsa = RSA.Create();
    rsa.ImportFromPem(publicKeyPem);

    byte[] data = Encoding.UTF8.GetBytes(plaintext);
    byte[] encrypted = rsa.Encrypt(
        data,
        RSAEncryptionPadding.OaepSHA256
    );

    return Convert.ToBase64String(encrypted);
}