Overview

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

This library also incorporates Ubiq 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'.

Installation

Requirements

Java 11 or later

Gradle Users

Add this dependency to your project's build file:

implementation group: 'com.ubiqsecurity', name: 'ubiqsecurity', version: 'latest.release'

Maven users

Add this dependency to your project's POM, where X.Y.Z represents the appropriate version number:

<dependency>
  <groupId>com.ubiqsecurity</groupId>
  <artifactId>ubiqsecurity</artifactId>
  <version>X.Y.Z</version>
</dependency>

Others

You'll need to manually install the following JARs:

The Ubiq Security JAR from appropriate version in https://repo1.maven.org/maven2/com/ubiqsecurity/ubiqsecurity/

Building from source:

Use following command to use [gradlew] to build the JAR file

Linux / Mac / Unix

./gradlew assemble build

Windows

.\gradlew assemble build

Requirements

OpenJDK 11 or later
This library has dependencies on ubiq-fpe-java library available for download in the Ubiq GitHub/GitLab repository.

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 hardcoded into your application, specified with environment variables, loaded from an explicit file, or loaded from a file in your home directory [~/.ubiq/credentials].

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.

Referencing the Ubiq Security library

Make sure your source files import these public types from the ubiqsecurity library:

import com.ubiqsecurity.UbiqCredentials;
import com.ubiqsecurity.UbiqDecrypt;
import com.ubiqsecurity.UbiqEncrypt;
import com.ubiqsecurity.UbiqFactory;

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
UbiqCredentials credentials = UbiqFactory.readCredentialsFromFile("some-credential-file", "some-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
UbiqCredentials credentials = UbiqFactory.readCredentialsFromFile("", "default");

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
UbiqCredentials credentials = UbiqFactory.createCredentials(null, null, null, null);

Explicitly set the credentials

// This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!
UbiqCredentials credentials = UbiqFactory.createCredentials("<yourAccessKey>", "<yourSigningKey>", "<yourCryptoKey>", null);

Runtime exceptions

Unsuccessful requests raise exceptions. The exception object will contain the error details.

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 plaintext bytes into the encryption function. The encrypted data
bytes will be returned.

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqEncrypt;

UbiqCredentials credentials = ...;
byte[] plainBytes = ...;
byte[] encryptedBytes = UbiqEncrypt.encrypt(credentials, plainBytes);

Decrypt a simple block of data

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

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqDecrypt;

UbiqCredentials credentials = ...;
byte[] encryptedBytes = ...;
byte[] plainBytes = UbiqDecrypt.decrypt(credentials, encryptedBytes);

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.

Here's the example code from the reference source:

static void piecewiseEncryption(String inFile, String outFile, UbiqCredentials ubiqCredentials)
        throws IOException, IllegalStateException, InvalidCipherTextException {
    try (FileInputStream plainStream = new FileInputStream(inFile)) {
        try (FileOutputStream cipherStream = new FileOutputStream(outFile)) {
            try (UbiqEncrypt ubiqEncrypt = new UbiqEncrypt(ubiqCredentials, 1)) {
                // start the encryption
                byte[] cipherBytes = ubiqEncrypt.begin();
                cipherStream.write(cipherBytes);

                // process 128KB at a time
                var plainBytes = new byte[0x20000];

                // loop until the end of the input file is reached
                int bytesRead = 0;
                while ((bytesRead = plainStream.read(plainBytes, 0, plainBytes.length)) > 0) {
                    cipherBytes = ubiqEncrypt.update(plainBytes, 0, bytesRead);
                    cipherStream.write(cipherBytes);
                }

                // finish the encryption
                cipherBytes = ubiqEncrypt.end();
                cipherStream.write(cipherBytes);
            }
        }
    }
}

Decrypt a large data element where data is loaded in chunks

Create a decryption object using the credentials.
Call the decryption instance begin() method.
Call the decryption instance update() method repeatedly until all data is processed.
Call the decryption instance end() method

Here's the example code from the reference source:

static void piecewiseDecryption(String inFile, String outFile, UbiqCredentials ubiqCredentials)
        throws FileNotFoundException, IOException, IllegalStateException, InvalidCipherTextException {
    try (FileInputStream cipherStream = new FileInputStream(inFile)) {
        try (FileOutputStream plainStream = new FileOutputStream(outFile)) {
            try (UbiqDecrypt ubiqDecrypt = new UbiqDecrypt(ubiqCredentials)) {
                // start the decryption
                byte[] plainBytes = ubiqDecrypt.begin();
                plainStream.write(plainBytes);

                // process 128KB at a time
                var cipherBytes = new byte[0x20000];

                // loop until the end of the input file is reached
                int bytesRead = 0;
                while ((bytesRead = cipherStream.read(cipherBytes, 0, cipherBytes.length)) > 0) {
                    plainBytes = ubiqDecrypt.update(cipherBytes, 0, bytesRead);
                    plainStream.write(plainBytes);
                }

                // finish the decryption
                plainBytes = ubiqDecrypt.end();
                plainStream.write(plainBytes);
            }
        }
    }
}

Structured Data Encryption

Requirements

Requires an additional library called ubiq-fpe-java 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.

Referencing the Ubiq Security library

Make sure your source files import these public types from the ubiqsecurity library:

import com.ubiqsecurity.UbiqCredentials;
import com.ubiqsecurity.UbiqFPEEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;

Reading and setting credentials

The eFPE functions work with the credentials file and/or environmental variables in the same way as described earlier in this document. You'll only need to make sure that the API keys you pull from the Ubiq dashboard are enabled for eFPE capability.

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.

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqFPEEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;

String FfsName = "SSN";
String plainText = "123-45-6789";

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");

String cipher = UbiqFPEEncryptDecrypt.encryptFPE(ubiqCredentials, FfsName, plainText, null);
System.out.println("ENCRYPTED cipher= " + cipher + "\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 plain text data will be returned.

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqFPEEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;

String FfsName = "SSN";
String cipherText = "7\"c-`P-fGj?";

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");

String plainText = UbiqFPEEncryptDecrypt.decryptFPE(ubiqCredentials, FfsName, cipherText, null);
System.out.println("DECRYPTED plain text= " + plainText + "\n");

Encrypt a social security text field - bulk interface

Create an Encryption / Decryption object with the credentials and then allow repeatedly call encrypt data using a Field Format Specification, FFS, and the data. The encrypted data will be returned after each call.

Note that you would only need to create the "ubiqEncryptDecrypt" object once for any number of encryptFPE and decryptFPE calls, for example when you are bulk processing many such encrypt / decrypt operations in a session.

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqFPEEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;

String FfsName = "SSN";
String plainText = "123-45-6789";

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");
// Create single object but use many times
try (UbiqFPEEncryptDecrypt ubiqEncryptDecrypt = new UbiqFPEEncryptDecrypt(ubiqCredentials)) {
  // Can call encryptFPE / decryptFPE many times without creating new UbiqFPEEncryptDecrypt object.
  String cipherText = ubiqEncryptDecrypt.encryptFPE(FfsName, plainText, null);
}

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.

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqFPEEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;

String FfsName = "SSN";
String cipherText = "7\"c-`P-fGj?";

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");
// Create single object but use many times
try (UbiqFPEEncryptDecrypt ubiqEncryptDecrypt = new UbiqFPEEncryptDecrypt(ubiqCredentials)) {
  // Can call encryptFPE / decryptFPE many times without creating new UbiqFPEEncryptDecrypt object.
  String plainText = ubiqEncryptDecrypt.encryptFPE(FfsName, cipherText, null);
}

Custom Metadata for Usage Reporting

There are cases where a developer would like to attach metadata to usage information reported by the application. Both the structured and unstructured interfaces allow user_defined metadata to be sent with the usage information reported by the libraries.

The addReportingUserDefinedMetadata function accepts a string in JSON format that will be stored in the database with the usage records. The string must be less than 1024 characters and be a valid JSON format. The string must include both the { and } symbols. The supplied value will be used until the object goes out of scope. Due to asynchronous processing, changing the value may be immediately reflected in subsequent usage. If immediate changes to the values are required, it would be safer to create a new encrypt / decrypt object and call the addReportingUserDefinedMetadata function with the new values.

Examples are shown below.

...
try (UbiqFPEEncryptDecrypt ubiqEncryptDecrypt = new UbiqFPEEncryptDecrypt(ubiqCredentials)) {
   ubiqEncryptDecrypt.addReportingUserDefinedMetadata("{\"some_meaningful_flag\" : true }")
   ....
   // FPE Encrypt and Decrypt operations
}

...
try (UbiqEncrypt ubiqEncrypt = new UbiqEncrypt(ubiqCredentials, 1)) {
   ubiqEncrypt.addReportingUserDefinedMetadata("{\"some_key\" : \"some_value\" }")
   ....
   // Unstructured Encrypt operations
}

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 UbiqFPEEncryptTest.java and the sample application UbiqSampleFPE.java source code

Sample Application

Overview

Provided are two sample applications. One called "UbiqSample.java" demonstrates how to encrypt and decrypt typical data that you might encounter in your own applications. The other sample application called "UbiqSampleFPE.java" demonstrates how to encrypt and decrypt using format preserving encryption (FPE).

Documentation for UbiqSample.java

See the Java API docs.

Installation

Install or build the library as described here.

Build From Source

Use gradlew to compile the sample application

Linux / Mac / Unix

cd example
./gradlew assemble build

Windows

cd example
.\gradlew assemble build

Credentials file

Edit the credentials file with your account 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, use the java command to execute the sample application

Linux / Mac / Unix

java -cp "./build/libs/ubiq-sample.jar:./build/deps/lib/*"  UbiqSample -h

Windows

java -cp "./build/libs/ubiq-sample.jar;./build/deps/lib/*"  UbiqSample -h

Usage: Ubiq Security Example [options]
  Options:
    --creds, -c
      Set the file name with the API credentials
    --decrypt, -d
      Decrypt the contents of the input file and write the results to output 
      file 
      Default: false
    --encrypt, -e
      Encrypt the contents of the input file and write the results to output 
      file 
      Default: false
    --help, -h
      Print app parameter summary
  * --in, -i
      Set input file name
  * --out, -o
      Set output file name
    --piecewise, -p
      Use the piecewise encryption / decryption interfaces
      Default: false
    --profile, -P
      Identify the profile within the credentials file
      Default: default
    --simple, -s
      Use the simple encryption / decryption interfaces
      Default: false
    --version, -v
      Print the app version
      Default: false

Demonstrate using the simple (-s / --simple) API interface to encrypt this README.md file and write the encrypted data to readme.enc

Linux / Mac / Unix

java -cp "./build/libs/ubiq-sample.jar:./build/deps/lib/*"  UbiqSample -i README.md -o readme.enc -e -s -c credentials

Windows

java -cp "./build/libs/ubiq-sample.jar;./build/deps/lib/*"  UbiqSample -i README.md -o readme.enc -e -s -c credentials

Demonstrate using the simple (-s / --simple) API interface to decrypt the readme.enc file and write the decrypted output to README.out

Linux / Mac / Unix

java -cp "./build/libs/ubiq-sample.jar:./build/deps/lib/*"  UbiqSample -i readme.enc -o README.out -d -s -c credentials

Windows

java -cp "./build/libs/ubiq-sample.jar;./build/deps/lib/*"  UbiqSample -i readme.enc -o README.out -d -s -c credentials

Demonstrate using the piecewise (-p / --piecewise) API interface to encrypt this README.md file and write the encrypted data to readme.enc

Linux / Mac / Unix

java -cp "./build/libs/ubiq-sample.jar:./build/deps/lib/*"  UbiqSample -i README.md -o readme.enc -e -p -c credentials

Windows

java -cp "./build/libs/ubiq-sample.jar;./build/deps/lib/*"  UbiqSample -i README.md -o readme.enc -e -p -c credentials

Demonstrate using the piecewise (-p / --piecewise) API interface to decrypt the readme.enc file and write the decrypted output to README.out

Linux / Mac / Unix

java -cp "./build/libs/ubiq-sample.jar:./build/deps/lib/*"  UbiqSample -i readme.enc -o README.out -d -p -c credentials

Windows

java -cp "./build/libs/ubiq-sample.jar;./build/deps/lib/*"  UbiqSample -i readme.enc -o 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 Java API docs.

Installation

Install or build the library as described here.

Build the Example

Use gradlew to compile the sample application

Linux / Mac / Unix

cd example
./gradlew clean assemble build --refresh-dependencies

Windows

cd example
.\gradlew clean assemble build --refresh-dependencies

Credentials file

Edit the credentials file with your account credentials created using the Ubiq dashboard. Do make sure that you have the FPE option enabled in the Ubiq dashboard.

[default]
ACCESS_KEY_ID = ...
SECRET_SIGNING_KEY = ...
SECRET_CRYPTO_ACCESS_KEY = ...

View Program Options

From within the example directory, use the java command to execute the sample application

Linux / Mac / Unix

java -cp "./build/libs/ubiq-sample.jar:./build/deps/lib/*"  UbiqSampleFPE  -h

Windows

java -cp "./build/libs/ubiq-sample.jar;./build/deps/lib/*"  UbiqSampleFPE  -h

Usage: Ubiq Security Example [options]
  Options:
    --bulk, -b
      Use the bulk encryption / decryption interfaces
    --creds, -c
      Set the file name with the API credentials
    --decrypttext, -d
      Set the cipher text value to decrypt and will return the decrypted text.
    --encrypttext, -e
      Set the field text value to encrypt and will return the encrypted cipher 
      text. 
  * --ffsname, -n
      Set the ffs name, for example SSN.
    --help, -h
      Print app parameter summary
    --profile, -P
      Identify the profile within the credentials file
      Default: default
    --simple, -s
      Use the simple encryption / decryption interfaces
    --version, -V
      Show program's version number and exit

Demonstrate encrypting a social security number and returning a cipher text

Linux / Mac / Unix

java -cp "./build/libs/ubiq-sample.jar:./build/deps/lib/*"  UbiqSampleFPE  -e '123-45-6789' -c credentials -n 'ALPHANUM_SSN' -s

Windows

java -cp "./build/libs/ubiq-sample.jar;./build/deps/lib/*"  UbiqSampleFPE  -e '123-45-6789' -c credentials -n 'ALPHANUM_SSN' -s

Demonstrate decrypting a social security number and returning the plain text

Linux / Mac / Unix

java -cp "./build/libs/ubiq-sample.jar:./build/deps/lib/*"  UbiqSampleFPE  -d 'W$+-qF-oMMV' -c credentials -n 'ALPHANUM_SSN' -s

Windows

java -cp "./build/libs/ubiq-sample.jar;./build/deps/lib/*"  UbiqSampleFPE  -d 'W$+-qF-oMMV' -c credentials -n 'ALPHANUM_SSN' -s

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.

String dataset_name = "SSN";
String plainText = "123-45-6789";
final byte[] tweak = null;

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");
UbiqFPEEncryptDecrypt ubiqEncryptDecrypt = new UbiqFPEEncryptDecrypt(ubiqCredentials);
String[] ct_arr = ubiqEncryptDecrypt.encryptForSearch(dataset_name, plainText, tweak);