Encrypting / Decrypting Request

All requests sent to the ENSC API are secured by encrypting payloads using AES-256-GCM and signing them with Ed25519. The client encrypts and signs outgoing requests, while the server decrypts and verifies the signature before processing the request.

Ed25519 Example:

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error. Below is a TypeScript code snippet that demonstrates how to sign a plaintext message with Ed25519. This signature is later verified by the ENSC API server to ensure data integrity.

Typescript

import * as crypto from 'crypto';

/**
 * Signs a plaintext message using Ed25519.
 *
 * @param message - The plaintext message to sign.
 * @param privateKey - The PEM-formatted private key.
 * @returns The signature as a base64-encoded string.
 */
function signMessage(message: string, privateKey: string): string {
  const signature = crypto.sign(null, Buffer.from(message, 'utf8'), {
    key: privateKey,
    format: 'pem',
  });
  return signature.toString('base64');
}

// Example usage:
const message = 'Hello ENSC!';
const privateKey = `-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_CONTENT
-----END PRIVATE KEY-----`;

const signature = signMessage(message, privateKey);
console.log('Signature (base64):', signature);

AES Example:

This example shows how to encrypt and decrypt a payload using AES-256-GCM. The ENSC API client encrypts the JSON payload before sending it, and the server decrypts it using the shared encryption key.

Typescript

import * as crypto from 'crypto';

/**
 * Encrypts a plaintext payload using AES-256-GCM.
 *
 * @param payload - The data to encrypt (JSON-stringified).
 * @param encryptionKey - The base64-encoded encryption key.
 * @param privateKey - The PEM-formatted private key for signing.
 * @returns An object containing the base64-encoded encrypted data, IV, authTag, and signature.
 */
function encryptPayload(payload: any, encryptionKey: string, privateKey: string) {
  const plaintext = JSON.stringify(payload);
  const iv = crypto.randomBytes(12);
  const keyBuffer = Buffer.from(encryptionKey, 'base64');

  // Encrypt the plaintext using AES-256-GCM
  const cipher = crypto.createCipheriv('aes-256-gcm', keyBuffer, iv);
  let encrypted = cipher.update(plaintext, 'utf8');
  encrypted = Buffer.concat([encrypted, cipher.final()]);
  const authTag = cipher.getAuthTag();

  // Sign the plaintext using Ed25519
  const signature = crypto.sign(null, Buffer.from(plaintext, 'utf8'), {
    key: privateKey,
    format: 'pem',
  });

  return {
    encryptedData: encrypted.toString('base64'),
    iv: iv.toString('base64'),
    authTag: authTag.toString('base64'),
    signature: signature.toString('base64'),
  };
}

/**
 * Decrypts an AES-256-GCM encrypted payload.
 *
 * @param encryptedPayload - An object containing base64-encoded encryptedData, iv, and authTag.
 * @param encryptionKey - The base64-encoded encryption key.
 * @returns The decrypted plaintext string.
 */
function decryptPayload(
  encryptedPayload: { encryptedData: string; iv: string; authTag: string },
  encryptionKey: string,
): string {
  const keyBuffer = Buffer.from(encryptionKey, 'base64');
  const ivBuffer = Buffer.from(encryptedPayload.iv, 'base64');
  const encryptedBuffer = Buffer.from(encryptedPayload.encryptedData, 'base64');
  const authTagBuffer = Buffer.from(encryptedPayload.authTag, 'base64');

  const decipher = crypto.createDecipheriv('aes-256-gcm', keyBuffer, ivBuffer);
  decipher.setAuthTag(authTagBuffer);
  let decrypted = decipher.update(encryptedBuffer, undefined, 'utf8');
  decrypted += decipher.final('utf8');
  return decrypted;
}

// Example usage:
const payload = { userId: 'user123', amount: 100, assetSymbol: 'ENSC' };
const encryptionKey = 'YOUR_BASE64_ENCRYPTION_KEY';
const clientPrivateKey = `-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_CONTENT
-----END PRIVATE KEY-----`;

const encryptedPayload = encryptPayload(payload, encryptionKey, clientPrivateKey);
console.log('Encrypted payload:', encryptedPayload);

// To decrypt (server side):
const decryptedText = decryptPayload(encryptedPayload, encryptionKey);
console.log('Decrypted text:', decryptedText);