Node.js Library
Step-by-step instructions for protecting data in your JavaScript application

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 Client Library needs to be configured with your API Key Credentials which are available in the Ubiq Dashboard when you create a Dataset. 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>')
Unstructured Data Encryption
Configuration
Create a Dataset and obtain API Key Credentials using the Create Dataset Wizard with Unstructured selected for the Data Type.
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()
});
Structured Data Encryption
Requirements
- This library has dependencies on the ubiqsecurity-fpe library available for download in the Ubiq GitHub/GitLab repository.
Configuration
Create a Dataset and obtain API Key Credentials using the Create Dataset Wizard with Structured selected for the Data Type.
Require the Security Client module in your JS class.
const ubiq = require('ubiq-security')
Encrypt a social security text field - simple interface
Pass credentials, the name of a Field Format Specification, FFS, and data into the encryption function. The encrypted data will be returned.
const FfsName = "SSN";
const plainText = "123-45-6789";
const ubiqCredentials = new ubiq.ConfigCredentials('./credentials', 'default');
const encrypted_data = await ubiq.fpeEncryptDecrypt.Encrypt({
ubiqCredentials,
ffsname: FfsName,
data: plainText});
console.log('ENCRYPTED ciphertext= ' + encrypted_data + '\n');
Decrypt a social security text field - simple interface
Pass credentials, the name of a Field Format Specification, FFS, and data into the decryption function. The decrypted data will be returned.
const FfsName = "SSN";
const cipher_text = "300-0E-274t";
const ubiqCredentials = new ubiq.ConfigCredentials('./credentials', 'default');
const decrypted_text = await ubiq.fpeEncryptDecrypt.Decrypt({
ubiqCredentials,
ffsname: FfsName,
data: cipher_text});
console.log('DECRYPTED decrypted_text= ' + decrypted_text + '\n');
Encrypt a social security text field - bulk interface
Create an FpeEncryptDecrypt object with credentials and then allow repeated calls to encrypt / decrypt
data using a Field Format Specification and the data. Cipher text will be returned.
const FfsName = "SSN";
const plainText = "123-45-6789";
const ubiqCredentials = new ubiq.ConfigCredentials('./credentials', 'default');
const ubiqEncryptDecrypt = new ubiq.fpeEncryptDecrypt.FpeEncryptDecrypt({ ubiqCredentials });
const encrypted_data = await ubiqEncryptDecrypt.EncryptAsync(
FfsName,
plainText
);
console.log('ENCRYPTED ciphertext= ' + encrypted_data + '\n');
Decrypt a social security text field - bulk interface
Create an Encryption / Decryption object with the credentials and then repeatedly decrypt data using a Field Format Specification, FFS, and the data. The decrypted data will be returned after each call.
Note that you would only need to create the "ubiqEncrFpeEncryptDecryptyptDecrypt" object once for any number of EncryptAsync and DecryptAsync calls, for example when you are bulk processing many such encrypt / decrypt operations in a session.
const cipher_text = "300-0E-274t";
const ubiqCredentials = new ubiq.ConfigCredentials('./credentials', 'default');
const ubiqEncryptDecrypt = new ubiq.fpeEncryptDecrypt.FpeEncryptDecrypt({ ubiqCredentials });
const decrypted_text = await ubiqEncryptDecrypt.DecryptAsync(
FfsName,
cipher_text
);
console.log('DECRYPTED decrypted_text= ' + decrypted_text + '\n');
Additional information on how to use these FFS models in your own applications is available by contacting
Ubiq. You may also view some use-cases implemented in the unit test UbiqSecurityFpeEncryptDecrypt.test.js and the sample application UbiqSampleFPE.js source code.
Sample Application
Overview
This sample application will demonstrate how to encrypt and decrypt data using the different APIs.
Installation
First clone the sample source code the Ubiq repository and change directory to the sample application git clone (repository)
cd ubiq-node/example
Continue with the existing Installation Commands [npm] or [yarn]:
cd example
npm install
#or
yarn install
Credentials file
Edit the credentials file with your account API Key Credentials created using the Ubiq Dashboard:
[default]
ACCESS_KEY_ID = ...
SECRET_SIGNING_KEY = ...
SECRET_CRYPTO_ACCESS_KEY = ...
Example for Unstructured Data
View program options
From within the example directory:
cd example
node ubiq_sample.js -h
Demonstrate using the simple (-s) API interface to encrypt this README.md file and write the encrypted data to /tmp/readme.enc
node ubiq_sample.js -i ./README.md -o /tmp/readme.enc -e -s -c ./credentials
Demonstrate using the simple (-s) API interface to decrypt the /tmp/readme.enc file and write the decrypted output to /tmp/README.out
node ubiq_sample.js -i /tmp/readme.enc -o /tmp/README.out -d -s -c ./credentials
Demonstrate using the piecewise (-p) API interface to encrypt this README.md file and write the encrypted data to /tmp/readme.enc
node ubiq_sample.js -i ./README.md -o /tmp/readme.enc -e -p -c ./credentials
Demonstrate using the piecewise (-p / --piecewise) API interface to decrypt the /tmp/readme.enc file and write the decrypted output to /tmp/README.out
node ubiq_sample.js -i /tmp/readme.enc -o /tmp/README.out -d -p -c ./credentials
Example for Structured Data
This library also incorporates support for structured data encryption which is a form of embedded Format Preserving Encryption (eFPE). eFPE allows encrypting so that the output cipher text is in the same format as the original plaintext. This includes preserving special characters and control over what characters are permitted in the cipher text. For example, consider encrypting a social security number '123-45-6789'. The cipher text will maintain the dashes and look something like: 'W$+-qF-oMMV'.
See the Node.js API docs.
Installation
Install or build the library as described here.
Build the examples
$ cd example
$ npm install
#or
$ yarn install
View Program Options
$ node ./ubiq_sample_fpe.js -h
Encrypt or decrypt data using the Ubiq eFPE service
-h Show this help message and exit
-V Show program's version number and exit
-e INPUT Encrypt the supplied input string
escape or use quotes if input string
contains special characters
-d INPUT Decrypt the supplied input string
escape or use quotes if input string
contains special characters
-s Use the simple eFPE encryption / decryption interfaces
-b Use the bulk eFPE encryption / decryption interfaces
-n FFS Use the supplied Field Format Specification
-c CREDENTIALS Set the file name with the API credentials
(default: ~/.ubiq/credentials)
-P PROFILE Identify the profile within the credentials file
Demonstrate encrypting a social security number and returning a cipher text
$ node ./ubiq_sample_fpe.js -c ./credentials -P default -s -n SSN -e 123-45-6789
Demonstrate decrypting a social security number and returning the plain text
$ node ./ubiq_sample_fpe.js -c ./credentials -P default -s -n SSN -d 400-13-vTQB
Encrypt For Search
The same plaintext data will result in different cipher text when encrypted using different data keys. The Encrypt For Search function will encrypt the same plain text for a given dataset using all previously used data keys. This will provide a collection of cipher text values that can be used when searching for existing records where the data was encrypted and the specific version of the data key is not known in advance.
const credentials = new ubiq.ConfigCredentials('./credentials', 'default');
const dataset_name = "SSN";
const plainText = "123-45-6789";
const ubiqEncryptDecrypt = new ubiq.fpeEncryptDecrypt.FpeEncryptDecrypt({ ubiqCredentials: credentials });
const searchText = await ubiqEncryptDecrypt.EncryptForSearchAsync(
dataset_name,
plainText,
[]);
Updated about 12 hours ago