Description

This node SDK is designed to help developers easily integrate Onqlave Encryption As A Service into their node backend.

Table of Contents

• Description
• Table of Contents
  • Features
  • Installation
    • Requirements
    • Configuration
    • Usage
    • Encrypt
    • Decrypt
    • Encrypt Stream
    • Decrypt Stream
  • Reporting a Vulnerability

Features

• Encrypt/Decrypt piece of information
• Encrypt/Decrypt stream of data

Installation

Requirements

• Node 7.6.0 and above

Configuration

npm install onqlave-node

Usage

To use this SDK, you firstly need to obtain credential to access an Onqlave Arx by signing up to Onqlave and following instruction to create your 1st Onqlave Arx.

The Onqlave Node module is used to perform operations on the configured ARX such as encrypting, and decrypting for an Onqlave_ARX. example:

To use this module, the Onqlave client must first be initialized as follows.

const { Encryption, withCredential, withRetry, withArx, Credential, RetrySettings } = require('onqlave-node');
const { createReadStream, createWriteStream } = require('fs');

Or using ES modules

import { Encryption, withCredential, withRetry, withArx, Credential, RetrySettings }  from 'onqlave-node';
import { createReadStream, createWriteStream } from 'fs';

const arxOption = withArx("<arx_url>"); //This is the Arx URL retruned of the API Key created during setup. Keep in in a safe place.
const apiKey = "<api_access_key>"       //This is the API Access Key returned of the API Key created during setup. Keep in in a safe place.
const signingKey = "<api_signing_key>"  //This is the API Signing Key retruned of the API Key created during setup. Keep in in a safe place.
const secretKey = "<api_secret_key>"    //This is the API Secret Key retruned of the API Key created during setup. Keep in in a safe place.
const credentialOption = withCredential(new Credential(apiKey, signingKey, secretKey));
const retryOption = withRetry(new RetrySettings(2, 400, 2000));

const service = new Encryption(arxOption, credentialOption, retryOption);

All Onqlave APIs must be invoked using a Encryption instance.

Encrypt

To encrypt data, use the Encrypt(plainData, associatedData) method of the Encryption service. The plainText parameter is the Buffer representation of data you are wishing to encrypt. The associatedData parameter the Buffer representation of associated data which can be used to improve the authenticity of the data (it is not mandatory), as shown below.

//Initilise the new encryption service using configurations as per [Usage]
const service = new Encryption(arxOption, credentialOption, retryOption);

const plainData = Buffer.from("This is the plain data");
const additionalData = Buffer.from("This is to authenticated not to encrypt"); //This can be an arbitrary piece of information you can use to for added security purpose.
cipherData := await service.Encrypt(plainData, associatedData)

Decrypt

To encrypt data, use the Decrypt(cipherData, associatedData) method of the Encryption service. The cipherData parameter is the Buffer representation of data you are wishing to decrypt (previousely encrypted). The associatedData parameter the Buffer representation of associated data which can be used to improve the authenticity of the data (it is not mandatory), as shown below.

//Initilise the new encryption service using configurations as per [Usage]
const service = new Encryption(arxOption, credentialOption, retryOption);

const cipherData := Buffer.from("this data is already encrypted using `Encrypt` method")
const additionalData = Buffer.from("This is to authenticated not to encrypt"); //This can be an arbitrary piece of information you can use to for added security purpose.
plainData := await service.Decrypt(cipherData, associatedData)

Encrypt Stream

To encrypt stream of data, use the encryptStream(plainStream, cipherStream, associatedData) method of the Encryption service. The plainStream parameter is the ReadStream stream of data you are wishing to encrypt. The cipherStream parameter is the WriteStream stream you are wishing to write the cipher data to. The associatedData parameter the Buffer representation of associated data which can be used to improve the authenticity of the data (it is not mandatory), as shown below.

//Initilise the new encryption service using configurations as per [Usage]
const service = new Encryption(arxOption, credentialOption, retryOption);

const plainStream = createReadStream("<file or network stream you are wishing to encrypt>", { highWaterMark: 64 * 1024 });
const cipherStream = createWriteStream("<file or network stream you are whishing to stream the encrypted data to>", { encoding: 'binary' });
const associatedData := Buffer.from("this data needs to be authenticated, but not encrypted") //This can be an arbitrary piece of information you can use to for added security purpose.
await service.encryptStream(plainStream, cipherStream, additionalData);
plainStream.close();
cipherStream.close();

Decrypt Stream

To encrypt data, use the decryptStream(cipherStream, plainStream, associatedData) method of the Encryption service. The cipherStream parameter is the ReadStream stream of data you are wishing to decrypt and it was originally encrypted using EncryptStream. The plainStream parameter is the WriteStream stream you are wishing to write the plain data back to. The associatedData parameter the Buffer representation of associated data which can be used to improve the authenticity of the data (it is not mandatory), as shown below.

//Initilise the new encryption service using configurations as per [Usage]
const service = new Encryption(arxOption, credentialOption, retryOption);

const cipherStream = createReadStream("<file or network stream you are wishing to decrypt>", { encoding: 'binary' });
const plainStream = createWriteStream("<file or network stream you are whishing to stream the decrypted data to>", { highWaterMark: 64 * 1024 });
const associatedData := Buffer.from("this data needs to be authenticated, but not encrypted") //This can be an arbitrary piece of information you can use to for added security purpose.
await service.decryptStream(cipherStream, plainStream, additionalData);
plainStream.close();
cipherStream.close();

Reporting a Vulnerability

If you discover a potential security issue in this project, please reach out to us at [email protected]. Please do not create public GitHub issues or Pull Requests, as malicious actors could potentially view them.