Overview

The Ubiq Security Node.js library provides convenient interaction with the Ubiq Security Platform API from applications written in the JavaScript language. It includes a pre-defined set of classes that will provide simple interfaces to encrypt and decrypt data.

Installation

Using the npm or yarn package managers

You may want to make sure you are running the latest version of npm or yarn by first executing:

npm install -g npm
# or
npm install -g yarn

Install the ubiq-security package with:

npm install ubiq-security
# or
yarn add ubiq-security

Installing from Source

To build and install directly from a clone of the gitlab repository:

git clone https://gitlab.com/ubiqsecurity/ubiq-node.git
cd ubiq-node
npm install

Requirements

Node.js v12 or higher
All other dependencies are pre-required in the module itself.

Usage

Credentials

The library needs to be configured with API Key Credentials which are available from the Ubiq Dashboard. The credentials can be explicitly set, set using environment variables, loaded from an explicit file or read from the default location [~/.ubiq/credentials.json].
##A. Production and Production-Like Use

❗️

In a production deployment, it is critical to maintain the secrecy of Ubiq API Key Credentials (SECRET_CRYPTO_ACCESS_KEY and SECRET_SIGNING_KEY) and API tokens (ACCESS_KEY_ID).

These items SHOULD be stored in a secrets management server or password vault. They should NOT be stored in a standard data file, embedded in source code, committed to a source code repository, or insecurely used in environmental variables.

After API Key Credentials are obtained from the security server or vault by the client application, the Ubiq API Key Credential values can then be passed to the Credentials() function as strings.

B. Development Use

During initial development of an application, it may be desirable to use a simpler, insecure mechanism to store Ubiq API Key Credentials. The sections below provide some examples.

Require the Security Client module in your JS class:

const ubiq = require('ubiq-security')

Read credentials from a specific file and use a specific profile:

// This example is for development use only - Storing Ubiq API Key Credentials in a file is not recommended
const credentials = new ubiq.ConfigCredentials(credentials_file, profile)

Read credentials from ~/.ubiq/credentials and use the default profile:

// This example is for development use only - Storing Ubiq API Key credentials in a file is not recommended
const credentials = new ubiq.ConfigCredentials()

Use the following environment variables to set the credential values:

UBIQ_ACCESS_KEY_ID
UBIQ_SECRET_SIGNING_KEY
UBIQ_SECRET_CRYPTO_ACCESS_KEY

// This example is for development use only - Storing Ubiq API Key Credentials in environmental variables is not generally recommended
const credentials = new ubiq.Credentials()

Explicitly set the credentials:

// This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!
const credentials = new Credentials('<access_key_id>', '<secret_signing_key>', '<secret_crypto_access_key>')

Encrypt a simple block of data

Pass credentials and data into the encryption function. The encrypted data will be returned:

const ubiq = require('ubiq-security')

const encrypted_data = await ubiq.encrypt(credentials, plainntext_data)

Decrypt a simple block of data

Pass credentials and encrypted data into the decryption function. The plaintext data will be returned:

const ubiq = require('ubiq-security')

const plainttext_data = await ubiq.decrypt(credentials, encrypted_data)

Encrypt a large data element where data is loaded in chunks

• Create an encryption object using the credentials
• Call the encryption instance begin method
• Call the encryption instance update method repeatedly until all the data is processed
• Call the encryption instance end method
• Call the encryption instance close method

const ubiq = require('ubiq-security')

// Process 1 MiB of plaintext data at a time
const BLOCK_SIZE = 1024 * 1024

//Rest of the program
...
  var readStream = fs.createReadStream(input_file,{ highWaterMark: BLOCK_SIZE  });

  let enc = await new ubiq.Encryption(credentials, 1);
  // Write out the header information
  let encrypted_data = enc.begin()
  
  readStream.on('data', function(chunk) {
    encrypted_data += enc.update(chunk)
  }).on('end', function() {
      encrypted_data += enc.end()
      enc.close()
  });

Decrypt a large data element where data is loaded in chunks

• Create an instance of the decryption object using the credentials
• Call the decryption instance begin method
• Call the decryption instance update method repeatedly until all the data is processed
• Call the decryption instance end method
• Call the decryption instance close method

const ubiq = require('ubiq-security')

// Process 1 MiB of plaintext data at a time
const BLOCK_SIZE = 1024 * 1024

  let dec = new ubiq.Decryption(credentials)
  let plainttext_data = dec.begin()

  readStream.on('data', async function(chunk) {
    readStream.pause()
    await dec.update(chunk).then(function(response){
    if(response){
        plainttext_data += response
      }
    })
    readStream.resume()
  }).on('end', async function() {
      plainttext_data += dec.end()
      dec.close()
  });