Ubiq Security Java Library

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.

Ubiq Security Java Library

Documentation

See the Java API docs.

Installation

Requirements

Java 8 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

The following is a list of the JAR files required to compile, test, or deploy the ubiqsecurity library

Building from source:

Use following command to use maven to build the JAR file

#Linux / Mac
mvn clean compile package -DskipTests

# windows
mvn clean compile package -DskipTests

Requirements

OpenJDK 8 or later

Usage

The library needs to be configured with your account credentials which is
available in your Ubiq Dashboard credentials. The credentials can be set using environment variables, loaded from an explicitly specified file, or read from the default location (~~/.ubiq/credentials). A configuration can also be supplied to control specific behavior of the library. The configuration file can be loaded from an explicit file or read from the default location [~~/.ubiq/configuration]. See below for a sample configuration file and content description. The credentials object needs to be initialized using the configuration object and the credentials.init method. The credentials object only needs to be initialized one time, even if it is used to encrypt / decrypt many different object.

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.UbiqConfiguration;
import com.ubiqsecurity.UbiqDecrypt;
import com.ubiqsecurity.UbiqEncrypt;
import com.ubiqsecurity.UbiqFactory;

Read configuration from a specific file

UbiqConfiguration cfg = UbiqFactory.readConfigurationFromFile(file.getAbsolutePath());

Read credentials from a specific file and use a specific profile

UbiqCredentials credentials = UbiqFactory.readCredentialsFromFile("some-credential-file", "some-profile");

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

UbiqCredentials credentials = UbiqFactory.readCredentialsFromFile("", "default");

Read configuration from ~/.ubiq/configuration if it exists or use default values

UbiqConfiguration cfg = UbiqFactory.defaultConfiguration()

// Use the configuration to finish initalizing the credentials
credentials.init(configuration);

Use the following environment variables to set the credential values

UBIQ_ACCESS_KEY_ID
UBIQ_SECRET_SIGNING_KEY UBIQ_SECRET_CRYPTO_ACCESS_KEY

UbiqCredentials credentials = UbiqFactory.createCredentials(null, null, null, null, null, null);

Explicitly set the credentials

UbiqCredentials credentials = UbiqFactory.createCredentials("<yourAccessKey>", "<yourSigningKey>", "<yourCryptoKey>", null, null, null);

IDP integration

Ubiq currently supports both Okta and Entra IDP integration. Instead of using the credentials provided when creating the API Key, the username (email) and password will be used to authenticate with the IDP and provide access to the Ubiq platform.

Use the following environment variables to set the credential values

UBIQ_IDP_USERNAME
UBIQ_IDP_PASSWORD

UbiqCredentials credentials = UbiqFactory.createCredentials(null, null, null, null, null, null);

Explicitly set the credentials

UbiqCredentials credentials = UbiqFactory.createCredentials(null, null, null, null, "<your_idp_username>", "<your_idp_password>");

Runtime exceptions

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

Unstructured encryption of a simple block of data

Pass credentials and plaintext bytes into the unstructured 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);

Unstructured decryption of a simple block of data

Pass credentials and encrypted data into the unstructured 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);

Unstructured encryption of a large data element where data is loaded in chunks

Create an unstructured encryption object using the credentials.
Call the encryption instance initSession() method.
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)) {
                // Obtain an encryption session variable to manage state between calls to ensure
                // a threadsafe environment
                UbiqUnstructuredEncryptSession encryptSession = ubiqEncrypt.initSession();
                // start the encryption

                byte[] cipherBytes = ubiqEncrypt.begin(encryptSession);
                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(encryptSession, plainBytes, 0, bytesRead);
                    cipherStream.write(cipherBytes);
                }

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

Encrypt several objects using the same data encryption key (fewer calls to the server)

In this example, the same data encryption key is used to encrypt several different plain text objects, object1 .. objectn. In each case, a different initialization vector, IV, is automatically used but the ubiq platform is not called to obtain a new data encryption key, resulting in better throughput. For data security reasons, you should limit n to be less than 2^32 (4,294,967,296) for each unique data encryption key.

Create an encryption object using the credentials.
Call the encryption instance initSession method. This is passed into the begin, update, and end methods
Repeat following three steps as many times as appropriate

Call the encryption instance begin method
Call the encryption instance update method repeatedly until a single object's data is processed
Call the encryption instance end method

Call the encryption instance close method

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

      ...
      UbiqEncrypt ubiqEncrypt = new UbiqEncrypt(ubiqCredentials, 1);
      UbiqUnstructuredEncryptSession encryptSession = ubiqEncrypt.initSession();

      List<Byte> cipherBytes = new ArrayList<Byte>();

      // object1 is a full unencrypted object
      byte[] tmp = ubiqEncrypt.begin(encryptSession);
      cipherBytes.addAll(Bytes.asList(tmp))
      tmp = ubiqEncrypt.update(encryptSession, object1, 0, object1.length);
      cipherBytes.addAll(Bytes.asList(tmp))
      tmp = ubiqEncrypt.end(encryptSession);
      cipherBytes.addAll(Bytes.asList(tmp))
      // Do something with the encrypted data: cipherBytes

      // In this case, object2 is broken into two pieces, object2_part1 and object2_part2
      cipherBytes = new ArrayList<Byte>();
      tmp = ubiqEncrypt.begin(encryptSession);
      cipherBytes.addAll(Bytes.asList(tmp))
      tmp = ubiqEncrypt.update(encryptSession, object2_part1, 0, object2_part1.length);
      cipherBytes.addAll(Bytes.asList(tmp))
      tmp = ubiqEncrypt.update(encryptSession, object2_part2, 0, object2_part2.length);
      cipherBytes.addAll(Bytes.asList(tmp))
      tmp = ubiqEncrypt.end(encryptSession);
      cipherBytes.addAll(Bytes.asList(tmp))
      // Do something with the encrypted data: cipherBytes

      ...
      // In this case, objectb is broken into two pieces, object2_part1 and object2_part2
      cipherBytes = new ArrayList<Byte>();
      // objectn is a full unencrypted object
      tmp = ubiqEncrypt.begin(encryptSession);
      cipherBytes.addAll(Bytes.asList(tmp))
      tmp = ubiqEncrypt.update(encryptSession, objectn, 0, objectn.length);
      cipherBytes.addAll(Bytes.asList(tmp))
      tmp = ubiqEncrypt.end(encryptSession);
      cipherBytes.addAll(Bytes.asList(tmp))
      // Do something with the encrypted data: cipherBytes

      ubiqEncrypt.close()
}

Unstructured decryption of a large data element where data is loaded in chunks

Create a unstructured decryption object using the credentials.
Call the decryption instance initSession() method.
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)) {
                // Obtain an encryption session variable to manage state between calls to ensure
                // a threadsafe environment
                UbiqUnstructuredDecryptSession decryptSession = ubiqDecrypt.initSession();
                // start the decryption
                byte[] plainBytes = ubiqDecrypt.begin(decryptSession);
                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(decryptSession, cipherBytes, 0, bytesRead);
                    plainStream.write(plainBytes);
                }

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

Ubiq Structured Encryption

Requirements

Please follow the same requirements as described above for the unstructured encryption.

Usage

You will need to obtain account credentials in the same way as described above for unstructured encryption/decryption. When
you do this in your Ubiq Dashboard credentials, you'll need to use a structured dataset. The credentials can be set using environment variables, loaded from an explicitly specified file, or read from the default location (~/.ubiq/credentials).

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.UbiqStructuredEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;

Reading and setting credentials

The structured encryption 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 associated with a structured dataset

Encrypt a social security text field

Create an Encryption / Decryption object with the credentials and then allow repeatedly call encrypt
data using a structured dataset and the data. The encrypted data will be returned after each call

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqStructuredEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;

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

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

Decrypt a social security text field

Create an Encryption / Decryption object with the credentials and then repeatedly decrypt
data using a structured dataset and the data. The decrypted data will be returned after each call.

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqStructuredEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;

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

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

Encrypt / Decrypt / EncrypForSearch for Integer (32 bit) and Long (64 bit)

This requires pre-configuration of an Integer dataset with the corresponding length, either 32 or 64 bit.

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqStructuredEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;

String int32DatasetName = "Int32";
String int64DatasetName = "Int64";

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");
// Create single object but use many times
try (UbiqStructuredEncryptDecrypt ubiqEncryptDecrypt = new UbiqStructuredEncryptDecrypt(ubiqCredentials)) {
  // Can call encrypt / decrypt many times without creating new UbiqStructuredEncryptDecrypt object.

  // 32 Bit datasets can support unencrypted values
  // between -99,999,999 and 99,999,999
  // Encrypted result will be between -1,470,375,551 and 1,470,375,551
  int intVal = 9
  int int32 = ubiqEncryptDecrypt.encryptInt(int32DatasetName, intVal, null);
  int result32 = ubiqEncryptDecrypt.decryptInt(int32DatasetName, int32, null);
  int[] search32 = ubiqEncryptDecrypt.encryptIntForSearch(int32DatasetName, intVal, null);

  // 64 Bit datasets can support unencrypted values
  // between -9,999,999,999,999,999 and 9,999,999,999,999,999
  // Unencrypted value can be value between -9,999,999,999,999,999 and 9,999,999,999,999,999
  // Encrypted result will be between -2,032,385,242,251,560,000 and 2,032,385,242,251,560,000
  long longVal = -9;
  long int64 ubiqEncryptDecrypt.encryptLong(int64DatasetName, longVal, null);
  long result64 = ubiqEncryptDecrypt.decryptLong(int64DatasetName, int64, null);

  long[] search64 = ubiqEncryptDecrypt.encryptLongForSearch(int64DatasetName, longVal, null);
}

Encrypt / Decrypt / EncrypForSearch for DateTime (OffsetDateTime)

This requires pre-configuration of a DateTime dataset.

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqStructuredEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;
import java.time.ZonedDateTime;
import java.time.OffsetDateTime;
import java.time.ZoneId;
import java.time.temporal.ChronoUnit;

String datasetName = "datetime";

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");
// Create single object but use many times
try (UbiqStructuredEncryptDecrypt ubiqEncryptDecrypt = new UbiqStructuredEncryptDecrypt(ubiqCredentials)) {
  // Can call encrypt / decrypt many times without creating new UbiqStructuredEncryptDecrypt object.

  // Datetime values can support unencrypted values between
  // 1653-02-10 06:13:21 AM UTC and 11/20/2286 17:46:39 UTC
  // Encrypted result will be between 1/16/0018 11:01:21 and 12/16/3921 12:58:39
  OffsetDateTime dt = OffsetDateTime.now().truncatedTo(ChronoUnit.SECONDS),
  OffsetDateTime ct = ubiqEncryptDecrypt.encryptDateTime(datasetName, dt, null);
  OffsetDateTime result = ubiqEncryptDecrypt.decryptDateTime(datasetName, ct, null);
  OffsetDateTime[] searchCt = ubiqEncryptDecrypt.encryptDateTimeForSearch(datasetName, dt, null);
}

Encrypt / Decrypt / EncrypForSearch for Date (OffsetDateTime)

This requires pre-configuration of a Date dataset.

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqStructuredEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;
import java.time.ZonedDateTime;
import java.time.OffsetDateTime;
import java.time.ZoneId;
import java.time.temporal.ChronoUnit;

String datasetName = "datetime";

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");
// Create single object but use many times
try (UbiqStructuredEncryptDecrypt ubiqEncryptDecrypt = new UbiqStructuredEncryptDecrypt(ubiqCredentials)) {
  // Can call encrypt / decrypt many times without creating new UbiqStructuredEncryptDecrypt object.

  // Datetime values can support unencrypted values between
  // 1/1/0001 and 11/26/2738
  // Encrypted result will be between 1/1/0001 and 11/26/2738
  OffsetDateTime dt = OffsetDateTime.now().truncatedTo(ChronoUnit.DAYS),
  OffsetDateTime ct = ubiqEncryptDecrypt.encryptDate(datasetName, dt, null);
  OffsetDateTime result = ubiqEncryptDecrypt.decryptDate(datasetName, ct, null);
  OffsetDateTime[] searchCt = ubiqEncryptDecrypt.encryptDateForSearch(datasetName, dt, null);
}

Encrypt / Decrypt / EncrypForSearch for Token, either 64 characters or 128 characters

This requires pre-configuration of a Token dataset of the appropriate length

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqStructuredEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;


String datasetName64 = "token64";
String datasetName128 = "token128";

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");
// Create single object but use many times
try (UbiqStructuredEncryptDecrypt ubiqEncryptDecrypt = new UbiqStructuredEncryptDecrypt(ubiqCredentials)) {
  // Can call encrypt / decrypt many times without creating new UbiqStructuredEncryptDecrypt object.

  // Input can be any string less 40 characters
  // Output will string 64 characters long and base62 (A-Za-z0-9)
  String ct64 = ubiqEncryptDecrypt.encrypt(datasetName64, "abc", null);
  String result64 = ubiqEncryptDecrypt.decrypt(datasetName64, ct64, null);
  String[] search64 = ubiqEncryptDecrypt.encryptForSearch(datasetName64, "abc", null);

  // Input can be any string less 80 characters
  // Output will string 64 characters long and base62 (A-Za-z0-9)
  String ct128 = ubiqEncryptDecrypt.encrypt(datasetName128, "abc", null);
  String result128 = ubiqEncryptDecrypt.decrypt(datasetName128, ct128, null);
  String[] search128 = ubiqEncryptDecrypt.encryptForSearch(datasetName128, "abc", null);
}

Encrypt / Decrypt / EncrypForSearch for Generic string. Input is base32 or base64 encoded and padded if necessary to reach minimum length.

This requires pre-configuration of a Generic string dataset with the corresponding encoding and padding character

import ubiqsecurity.UbiqCredentials;
import ubiqsecurity.UbiqStructuredEncryptDecrypt;
import com.ubiqsecurity.UbiqFactory;


String datasetName32 = "generic32";
String datasetName64 = "generic64";

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");
// Create single object but use many times
try (UbiqStructuredEncryptDecrypt ubiqEncryptDecrypt = new UbiqStructuredEncryptDecrypt(ubiqCredentials)) {
  // Can call encrypt / decrypt many times without creating new UbiqStructuredEncryptDecrypt object.

  // Input can be any UTF-8 string.  Output string is defined during dataset configuration
  String ct32 = ubiqEncryptDecrypt.encrypt(datasetName32, "Ñáñ", null);
  String result32 = ubiqEncryptDecrypt.decrypt(datasetName32, ct64, null);
  String[] search32 = ubiqEncryptDecrypt.encryptForSearch(datasetName32, "Ñáñ", null);

  // Input can be any UTF-8 string.  Output string is defined during dataset configuration
  String ct64 = ubiqEncryptDecrypt.encrypt(datasetName64, "Ñáñ", null);
  String result64 = ubiqEncryptDecrypt.decrypt(datasetName64, ct64, null);
  String[] search64 = ubiqEncryptDecrypt.encryptForSearch(datasetName64, "Ñáñ", 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 (UbiqStructuredEncryptDecrypt ubiqEncryptDecrypt = new UbiqStructuredEncryptDecrypt(ubiqCredentials)) {
   ubiqEncryptDecrypt.addReportingUserDefinedMetadata("{\"some_meaningful_flag\" : true }")
   ....
   // Structured Encrypt and Decrypt operations
}

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

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");
UbiqStructuredEncryptDecrypt ubiqEncryptDecrypt = new UbiqStructuredEncryptDecrypt(ubiqCredentials);
String[] ct_arr = ubiqEncryptDecrypt.encryptForSearch(dataset_name, plainText, tweak);

Additional information on how to use these datasets in your own applications is available by contacting
Ubiq. You may also view some use-cases implemented in the unit test UbiqStructuredEncryptTest.java and the sample application UbiqSampleStructured.java source code

Loading the cache for a specific dataset

The library maintains a cache of the dataset information and data encryption keys. The cache will automatically be populated on first use of a dataset or a specific encryption key. There may be cases where it makes sense to load a cache ahead of time for a dataset and all of the dataset's data encryption keys. The example below shows how to explicitly load or refresh the cache for a specific dataset

String dataset_name = "SSN";

UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");
UbiqStructuredEncryptDecrypt ubiqEncryptDecrypt = new UbiqStructuredEncryptDecrypt(ubiqCredentials);
ubiqEncryptDecrypt.loadCache(dataset_name);

The loadCache function can take an array of dataset names. If the array is empty, it will load all datasets for the ApiKey used when creating the UbiqStructuredEncryptDecrypt object. See the examples below

// Load the cache for dataset1 and dataset2
String [] datasets = {"dataset1","dataset2"};
ubiqEncryptDecrypt.loadCache(datasets);

// Load the cache for all structured datasets associated with the credentials being used
UbiqCredentials ubiqCredentials = UbiqFactory.readCredentialsFromFile("path/to/file", "default");
UbiqStructuredEncryptDecrypt ubiqEncryptDecrypt = new UbiqStructuredEncryptDecrypt(ubiqCredentials);
ubiqEncryptDecrypt.loadCache(new String[0]);

Configuration File

A sample configuration file is shown below. The configuration is in JSON format.

Event Reporting

The event_reporting section contains values to control how often the usage is reported.

wake_interval indicates the number of seconds to sleep before waking to determine if there has been enough activity to report usage
minimum_count indicates the minimum number of usage records that must be queued up before sending the usage
flush_interval indicates the sleep interval before all usage will be flushed to server.
trap_exceptions indicates whether exceptions encountered while reporting usage will be trapped and ignored or if it will become an error that gets reported to the application
timestamp_granularity indicates the how granular the timestamp will be when reporting events. Valid values are
- "NANOS"
  // DEFAULT: values are reported down to the nanosecond resolution when possible
- "MILLIS"
  // values are reported to the millisecond
- "SECONDS"
  // values are reported to the second
- "MINUTES"
  // values are reported to minute
- "HOURS"
  // values are reported to hour
- "HALF_DAYS"
  // values are reported to half day
- "DAYS"
  // values are reported to the day

Key Caching

The key_caching section contains values to control how and when keys are cached.

ttl_seconds indicates how many seconds a cache element should remain before it must be re-retrieved. (default: 1800)
structured indicates whether keys will be cached when doing structured encryption and decryption. (default: true)
unstructured indicates whether keys will be cached when doing unstructured decryption. (default: true)
encrypt indicates if keys should be stored encrypted. If keys are encrypted, they will be harder to access via memory, but require them to be decrypted with each use. (default: false)

IDP specific parameters

provider indicates the IDP provider, either okta or entra
ubiq_customer_id The UUID for this customer. Will be provided by Ubiq.
idp_token_endpoint_url The endpoint needed to authenticate the user credentials, provided by Okta or Entra
idp_tenant_id contains the tenant value provided by Okta or Entra
idp_client_secret contains the client secret value provided by Okta or Entra

Proxy connection specific parameters

host indicates the address of the proxy server
port indicates the port number the proxy server is listening on

Java specific options

always_bubble_exceptions always bubble up exceptions rather than trap and return empty or null object. (default: false)

{
  "event_reporting": {
    "wake_interval": 1,
    "minimum_count": 2,
    "flush_interval": 2,
    "trap_exceptions": false,
    "timestamp_granularity" : "NANOS"
  },
  "key_caching" : {
     "structured" : true,
     "unstructured" : true,
     "encrypted" : false,
     "ttl_seconds" : 1800
  },
   "idp": {
    "provider": "okta",
    "ubiq_customer_id": "f6f.....08c5",
    "idp_token_endpoint_url": " https://dev-<domain>.okta.com/oauth2/v1/token",
    "idp_tenant_id": "0o....d7",
    "idp_client_secret": "yro.....2Db"
  },
  "proxy": {
    "host": "192.168.1.10",
    "port": 8080
  },
  "java_options": {
    "always_bubble_exceptions" : true
  }
}

Ubiq API Error Reference

Occasionally, you may encounter issues when interacting with the Ubiq API.

Status Code	Meaning	Solution
400	Bad Request	Check name of datasets and credentials are complete.
401	Authentication issue	Check you have the correct API keys, and it has access to the datasets you are using. Check dataset name.
426	Upgrade Required	You are using an out of date version of the library, or are trying to use newer features not supported by the library you are using. Update the library and try again.
429	Rate Limited	You are performing operations too quickly. Either slow down, or contact [email protected] to increase your limits.
500	Internal Server Error	Something went wrong. Contact support if this persists.
504	Internal Error	Possible API key issue. Check credentials or contact support.

Using the Ubiq Security Java Library with a Proxy

You can configure the Ubiq Java library to use a proxy for its API calls by including an optional section in the configuration file:

flowchart LR
  A[ubiq-java app] --> B[Proxy server]
  B --> C[Ubiq API endpoint]

{
  "proxy": {
    "host": "192.168.1.10",
    "port": 8080
  }
}

Running a local proxy with Docker

To quickly run a local proxy using Docker:

docker run --rm -it
  -p 8080:8080
  mitmproxy/mitmproxy
  mitmproxy --mode regular --listen-port 8080

Running mitmproxy without Docker

If you prefer to run it directly on your system without Docker:

mitmproxy --mode regular --listen-port 8080