Encryption

This guide provides detailed instructions on how to send and receive data securely using encryption keys.

Encryption Overview

We prioritize the security of your data. To ensure this, we employ encryption for the data transmitted through our Public API and Webhooks.

Encryption Key

An encryption key is provided on the "Application" page of your account. This key is essential for encrypting and decrypting data exchanged between your application and our services.

Sending Data to Our Public API

You have the option to send data to our Public API either encrypted or unencrypted, depending on your preference and security requirements.

• Encrypted Data: To send encrypted data, use the encryption key provided on the "Application" page. Encrypt your data before sending it to our API.The encrypted data should be included in the payload as follows:

{
  "data": "encryptedString"
}

• Unencrypted Data: If you prefer, you can also send data without encryption. This option is available for clients who may not require the added security layer.

Receiving Data from Public API and Webhooks

All data sent to you via our Public API or Webhooks is encrypted using the same encryption key found on the "Application" page. Ensure you decrypt the incoming data using this key to access the information.

Steps for Integration

1. Access Your Encryption Key: Log in to your account and navigate to the "Application" page to retrieve your encryption key.

2. Encrypt Your Data (optional): If you choose to encrypt your data, use the provided key to encrypt your JSON payloads.

3. Send Data to Public API:

   • Encrypted: Send your encrypted data to our Public API endpoint.

{
  "data": "encryptedString"
}

• Unencrypted: Send your plain JSON data to our Public API endpoint.

1. Receive and Decrypt Data: When receiving data from our Public Api or Webhooks, decrypt the incoming payload using the encryption key.

Example Code Snippets

Here are some example code snippets to help you get started with encryption and decryption using your key:

Encrypting Data:

const crypto = require('crypto');
const key = 'your-encryption-key';
const algorithm = 'aes-256-cbc';

function encrypt(text) {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv(algorithm, Buffer.from(key, 'hex'), iv);
  let encrypted = cipher.update(text);
  encrypted = Buffer.concat([encrypted, cipher.final()]);
  return iv.toString('hex') + ':' + encrypted.toString('hex');
}

const data = JSON.stringify({ key: 'value' });
const encryptedData = encrypt(data);
const payload = { data: encryptedData };
console.log(payload);

Decrypting Data:

const crypto = require('crypto');

function decryptData(encryptedTextWithIv: string, key: string): string {
    const keyBuff = Buffer.from(key, 'hex');
    const iv = Buffer.from(encryptedTextWithIv.slice(0, 32), 'hex');
    const encryptedText = encryptedTextWithIv.slice(32);
    const decipher = crypto.createDecipheriv('aes-256-cbc', keyBuff, iv);
    let decrypted = decipher.update(encryptedText, 'hex', 'utf8');
    decrypted += decipher.final('utf8');

    return decrypted;
}

const aes256cbc = `*************`; // Your crypt key from application page

const encryptedDataString = '... Encrypted data in Base64 ...';
const decryptedDataString = decryptData(aes256cbc, encryptedDataString);

console.log('Decrypted data object:', JSON.parse(decryptedDataString));

Decrypting Stream Files

In addition to handling encrypted data through our Public API and Webhooks, you may also need to decrypt stream files received from our services. Below are the steps and code snippets to help you decrypt these stream files effectively.

Steps for Decrypting Stream Files

1. Retrieve Initialization Vector (IV): The IV for the decryption process is provided in the response headers of the stream file. You can retrieve it using the following code:

   const iv = Buffer.from(response.headers['x-initialization-vector'], 'hex');

2. Decrypt Stream Data:

   • Use the IV and the encryption key to decrypt the incoming stream file data.

   • The length of the IV is 16 bytes.

Example Code Snippet

Here's an example of how to decrypt a stream file:

const crypto = require('crypto');
const fs = require('fs');
const http = require('http');
const { promisify } = require('util');
const { pipeline } = require('stream');

const pipelineAsync = promisify(pipeline);

async function downloadAndDecryptFile(url, outputPath, encryptionKey) {
  try {
    const response = await new Promise((resolve, reject) => {
      const request = http.get(url, {
        headers: {
          'X-Private-App-Key': 'string',
        },
      }, (response) => {
        if (response.statusCode !== 200) {
          reject(new Error(`Failed to get '${url}' (${response.statusCode})`));
        } else {
          resolve(response);
        }
      });

      request.on('error', (err) => {
        reject(err);
      });
    });

    // Retrieve the IV from the headers
    const iv = Buffer.from(response.headers['x-initialization-vector'], 'hex');
    if (!iv || iv.length !== 16) {
      throw new Error('Invalid or missing initialization vector (IV)');
    }

    const keyBuff = Buffer.from(encryptionKey, 'hex');
    // Create a decipher for decryption
    const decipher = crypto.createDecipheriv('aes-256-cbc', keyBuff, iv);

    // Create a write stream for the output file
    const writeStream = fs.createWriteStream(outputPath);

    // Pipe the encrypted stream through the decipher and into the write stream
    await pipelineAsync(response, decipher, writeStream);
    console.log('File downloaded and decrypted successfully.');
  } catch (err) {
    console.error('Error downloading or decrypting file:', err);
  }
}