# Encryption

### 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)

```javascript
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)

```csharp
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);
}

```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zumrails.com/api-reference/encryption.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.