Overview

The Ubiq Security C++ library provides a convenient interaction with the Ubiq Security Platform API from applications written in the C++ language. Included is a pre-defined set of functions and classes that will provide a simple interface 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

Using the package Manager

Packages are available for systems that can use .deb files. In that case, you don't need this source code unless you want to modify the libraries. If you just want to use the libraries, install the pre-built packages available from Releases:

# For debian based systems
# installs the runtime libraries, needed for running existing clients
$ sudo apt install ./libubiqclient_<version>_<arch>.deb
# installs the development headers, needed for building or modifying clients
$ sudo apt install ./libubiqclient-dev_<version>_<arch>.deb

# For rpm based systems
# installs the runtime libraries, needed for running existing clients
$ sudo yum install ./libubiqclient-<version>_<arch>.rpm
# installs the development headers, needed for building or modifying clients
$ sudo yum install ./libubiqclient-dev-<version>_<arch>.rpm

When building clients with gcc, use -lubiqclient++ to link against the C++ library.

Building from Source

To build and install directly from a clone of the Gitlab directory. Clone this repository, initialize the submodules, and build the client. The commands are the same on both Windows and Unix-like systems:

$ git clone https://gitlab.com/ubiqsecurity/ubiq-c-cpp.git
$ cd ubiq-c-cpp
$ git submodule update --init --recursive
$ mkdir build
$ cd build
$ cmake ..
$ cmake --build .

The package manager can be used to install the built packages using the commands described above.

Requirements

CMake 3.10+ is required for building on both Windows and Unix-like systems.

On Windows, the library has been tested to build with the Visual Studio 2017 CE compiler.

On Unix-like systems, the following libraries and development headers are required:

cURL 7.68+
OpenSSL 1.1+
GMP 10

On Debian-like systems, those packages can be installed with the following commands:

# On Debian-like systems, those packages can be installed with the following
# commands:
# for runtime libraries needed to use the library
$ sudo apt install cmake libcurl4 libssl1.1 libgmp10
# for development headers needed to build the library
$ sudo apt install libcurl4 openssl-dev libssl-dev libgmp-dev

# On Fedora-like systems, those packages can be installed with the following
# commands:
# for runtime libraries needed to use the library
$ sudo yum install cmake curl openssl-libs gmp
# for development headers needed to build the library
$ sudo yum install openssl-devel libcurl-devel gmp-devel gmp-c++

Usage

Initialization

Before the library can be used, it must be initialized:

/* C++
 *
 * Returns `void`, but throws an exception if the library
 * is not successfully initialized.
 */
ubiq::platform::init();

Conversely, the library should be shutdown/de-initialized when it is no longer needed:

/* C++ */
ubiq::platform::exit();

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].

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.

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 */
ubiq::platform::credentials credentials(
    "/path/to/credentials", "profile-name");

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 */
ubiq::platform::credentials credentials;

Use the following environment variables to set the API Key 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 */
ubiq::platform::credentials credentials;

Explicitly set the API Key Credentials

/* This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!*/
ubiq::platform::credentials credentials(
    "..." /* access key id */,
    "..." /* secret signing key */,
    "..." /* secret crypto access key */,
    "..." /* Ubiq API server, may be unspecified */);

Handling exceptions

Unsuccessful requests raise exceptions. In general, exceptions are of the type std::system_error and in the category std::generic_category. These exceptions carry error codes corresponding to error numbers. Common errors are:

-EACCES Access is denied, usually due to invalid credentials, but this can also be caused by failure to decrypt keys from the server
-EAGAIN: The library has not been initialized
-EBADMSG: The server rejected a message from the client or vice versa. This is usually an incompatibility between the client and server, but can also be caused by the clock being set incorrectly on the client side, causing authentication to fail. This error can also be caused by an invalid or unsupported data format during decryption
-ECONNABORTED: An error occurred on the server side
-EINPROGRESS: A piecewise encryption or decryption has already been started when one of the encryption or decryption begin() functions is called
-EINVAL: A function was called with an invalid value/parameter
-ENODATA: During encryption, no random data was available. During decryption, not enough data was supplied to complete the decryption
-ENOENT: The specified or default credentials could not be found or were incomplete
-ENOMEM: The system was unable to allocate memory from the heap
-ENOSPC, formerly -EDQUOT: The encryption key has already been used the maximum number of times
-EPROTO: A response from the server was not understood. This is a problem with the library and should be reported
-ESRCH, formerly -EBADFD: The functions associated with a piecewise encryption or decryption have been called in an incorrect order

Errors returned from external libraries are converted to INT_MIN where the failure is not specific or can't be converted to an error number. While it is possible that the error indicates a runtime issue, most likely it is a misuse of that external library by the Ubiq client and should be reported.

Unstructured Data Encryption

Configuration

Create a Dataset and obtain API Key Credentials using the Create Dataset Wizard with Unstructured selected for the Data Type.

Simple encryption and decryption

Encrypt a single block of data

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

#include <ubiq/platform.h>

ubiq::platform::credentials creds;
std::vector<std::uint8_t> ctbuf;
void * ptbuf;
size_t ptlen;

/* initialize ptbuf and ptlen */
...

ctbuf = ubiq::platform::encrypt(creds, ptbuf, ptlen);

Decrypt a single block of data

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

#include <ubiq/platform.h>

ubiq::platform::credentials creds;
std::vector<std::uint8_t> ptbuf;
void * ctbuf;
size_t ctlen;

/* initialize ctbuf and ctlen */
...

ptbuf = ubiq::platform::decrypt(creds, ctbuf, ctlen);

Piecewise encryption and decryption

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

#include <ubiq/platform.h>

/* Process 1 MiB of plaintext data at a time */
#define BLOCK_SIZE  (1024 * 1024)

ubiq::platform::credentials credentials;
ubiq::platform::encryption enc(credentials, 1);
std::vector<std::uint8_t> ctbuf, buf;

ctbuf = enc.begin();

while (!infile.eof()) {
    std::vector<char> ptbuf(BLOCK_SIZE);

    infile.read(ptbuf.data(), ptbuf.size());
    ptbuf.resize(infile.gcount());
    buf = enc.update(ptbuf.data(), ptbuf.size());
    ctbuf.insert(ctbuf.end(), buf.begin(), buf.end());
}

buf = enc.end();
ctbuf.insert(ctbuf.end(), buf.begin(), buf.end());

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

#include <ubiq/platform.h>

/* Process 1 MiB of plaintext data at a time */
#define BLOCK_SIZE  (1024 * 1024)

ubiq::platform::credentials credentials;
ubiq::platform::decryption dec(credentials);
std::vector<std::uint8_t> ptbuf, buf;

ptbuf = dec.begin();

while (!infile.eof()) {
    std::vector<char> ctbuf(BLOCK_SIZE);

    infile.read(ctbuf.data(), ctbuf.size());
    ctbuf.resize(infile.gcount());
    buf = dec.update(ctbuf.data(), ctbuf.size());
    ptbuf.insert(ptbuf.end(), buf.begin(), buf.end());
}

buf = dec.end();
ptbuf.insert(ptbuf.end(), buf.begin(), buf.end());

Structured Data Encryption

Requirements

Please follow the same requirements as described above for simple encryption and decryption.
When building clients with gcc, use -lubiqclient to link against the C library and -lubiqclient++ to link against the C++ library.

Configuration

Create a Dataset and obtain API Key Credentials using the Create Dataset Wizard with Structured selected for the Data Type.

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.

#include <ubiq/platform.h>

std::string ffs_name("SSN");
std::string pt("123-45-6789");
std::string ct;

ubiq::platform::credentials creds;
ubiq::platform::init();
ct = ubiq::platform::fpe::encrypt(creds, ffs_name, pt);
...

ubiq::platform::exit();

Decrypt a social security text field - simple interface

Pass credentials, the name of a Field Format Specification, FFS, and data into the decrypt function. The plain text data will be returned.

#include <ubiq/platform.h>

std::string ffs_name("SSN");
std::string ct( "7\"c-`P-fGj?");
std::string pt;

ubiq::platform::init();
ubiq::platform::credentials creds;
pt = ubiq::platform::fpe::decrypt(creds, ffs_name, ct);
...

ubiq::platform::exit();

Encrypt a social security text field - bulk interface

Create an fpe_enc_dec 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.

#include <ubiq/platform.h>

std::string ffs_name("ALPHANUM_SSN");
std::vector<std::string> pt = {"123-45-6789", "987-65-4321","123-45-6789","123-45-6789","123-45-6789"};
std::string ct;

try {
   ubiq::platform::credentials creds;
   ubiq::platform::init();
   ubiq::platform::fpe::encryption enc(creds);

   // loop through a vector of plain text elements to encrypt
   for(auto itr : pt) {
     ct = enc.encrypt(ffs_name, itr);
     ...
   }
}
catch (const std::exception& e) {
  std::cerr << "Error: " << e.what() << std::endl;
}

ubiq::platform::exit();

Decrypt a social security text field - bulk interface

Create an fpe_enc_dec object with Pass credentials and then allow repeated calls to encrypt / decrypt data using a Field Format Specification and the data. Depending upon the call, either cipher text or plain text will be returned.

#include <ubiq/platform.h>

std::string ffs_name("ALPHANUM_SSN");
std::vector<std::string> ct = {"7\"c-`P-fGj?", "7$S-27-9D4A"};
std::string pt;

try {
   ubiq::platform::credentials creds;
   ubiq::platform::init();
   ubiq::platform::fpe::decryption dec(creds);

   // loop through a vector of plain text elements to encrypt
   for(auto itr : ct) {
     pt = dec.decrypt(ffs_name, itr);
     ...
   }  
}
catch (const std::exception& e) {
  std::cerr << "Error: " << e.what() << std::endl;
}
ubiq::platform::exit();

Sample Application

Overview

This sample application will demonstrate how to encrypt and decrypt data using the different APIs.

Dockerized samples

Pre-built versions of the samples can be run in a docker container as described here.

Installation

Install or build the software as described here.

Credentials file

Edit the API Key Credentials file with your account API Key Credentials created using the Ubiq Dashboard.

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

Build the examples

If you installed the libraries and development headers via the .deb packages, then you can build the examples directly from the installation (note that these commands will only work on a Linux system where the package files have been installed):

mkdir ~/ubiq_sample
cd ~/ubiq_sample
cmake /usr/share/doc/libubiqclient-dev/examples
cmake --build . --target all

If you built the software yourself, the examples are built automatically as part of a complete build.

On Windows, the DLL files can be found in build\src\Debug or build\src\Release, depending on your CMake configuration. The sample executables can be found in build\src\examples\Debug or build\src\examples\Release, again depending on your CMake configuration.
On Unix-like systems, the libraries and executables are produced in build/src and build/src/example, respectively.

To run the examples below, copy the libraries/DLL's and executables into the src/examples directory (where the example source code is located).

Example for Unstructured Data

View program options

From within the directory where your executables are located, you can execute/test the following commands. On Linux, you may need to set the LD_LIBRARY_PATH environment variable to include the directory where your libraries are located in order for the executables to work properly. On Windows, you may need to create the C:\Temp directory.

The examples below show both Unix and Windows syntax:

Linux / Mac / Unix

./ubiq_sample-c++ -h

Windows

.\ubiq_sample-c++.exe -h

Encrypt or decrypt files using the Ubiq service

  -h                       Show this help message and exit
  -V                       Show program's version number and exit
  -e                       Encrypt the contents of the input file and write
                             the results to the output file
  -d                       Decrypt the contents of the input file and write
                             the results to the output file
  -s                       Use the simple encryption / decryption interfaces
  -p                       Use the piecewise encryption / decryption interfaces
  -i INFILE                Set input file name
  -o OUTFILE               Set output file name
  -c CREDENTIALS           Set the file name with the API credentials
                             (default: ~/.ubiq/credentials)
  -P PROFILE               Identify the profile within the credentials file

Demonstrate using the simple (-s / --simple) API interface to encrypt the README file

Linux / Mac / Unix

./ubiq_sample-c++ -i README.md -o /tmp/readme.enc -e -s -c credentials

Windows

.\ubiq_sample-c++.exe -i README.md -o C:\Temp\readme.enc -e -s -c credentials

Demonstrate using the simple (-s / --simple) API interface to decrypt the README file

Linux / Mac / Unix

./ubiq_sample-c++ -i README.md -o /tmp/readme.enc -e -p -c credentials

Windows

.\ubiq_sample-c++.exe -i README.md -o C:\Temp\readme.enc -e -p -c credentials

Demonstrate using the piecewise (-p / --piecewise) API interface to encrypt the README file

Linux / Mac / Unix

./ubiq_sample-c++ -i README.md -o /tmp/readme.enc -e -p -c credentials

Windows

.\ubiq_sample-c++.exe -i README.md -o C:\Temp\readme.enc -e -p -c credentials

Demonstrate using the piecewise (-p / --piecewise) API interface to decrypt the README file

Linux / Mac / Unix

./ubiq_sample-c++ -i /tmp/readme.enc -o /tmp/README.out -d -p -c credentials

Windows

.\ubiq_sample-c++.exe -i C:\Temp\readme.enc -o C:\Temp\README.out -d -p -c credentials

Example for Structured Data

Documentation for ubiq_sample_fpe.c and ubiq_sample_fpe.cpp

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 C++ API docs.

Installation

Install or build the library as described here.

Build the Examples

If you installed the libraries and development headers via the .deb or .rpm packages, then you can build the examples directly from the installation(note that these commands will only work on a Linux system where the package files have been installed):

$ mkdir ~/ubiq_sample
$ cd ~/ubiq_sample
$ cmake /usr/share/doc/libubiqclient-dev/examples
$ cmake --build . --target all

View Program Options

$ ./ubiq_sample_fpe-c++ -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

$ ./ubiq_sample_fpe-c++ -e '123-45-6789' -n ALPHANUM_SSN -s

Demonstrate decrypting a social security number and returning the plain text

$ ./ubiq_sample_fpe-c++ -d 'W#]-iV-`,"j' -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.

/* C++ - Encrypting a SSN value using all previously used data keys */

    std::string dataset_name("SSN");
    std::string pt("123-45-6789");
    std::vector<std::string> ct_arr;
    ubiq::platform::credentials creds;

    ubiq::platform::init();

    enc = ubiq::platform::fpe::encryption(creds);
    ct_arr = enc.encrypt_for_search(dataset_name, pt);
    ...

    ubiq::platform::exit();

Overview

Installation

Using the package Manager

Building from Source

Requirements

Usage

Initialization

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).

B. Development Use

Read credentials from a specific file and use a specific profile

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

Use the following environment variables to set the API Key Credential values

Explicitly set the API Key Credentials

Handling exceptions

Unstructured Data Encryption

Configuration

Simple encryption and decryption

Encrypt a single block of data

Decrypt a single block of data

Piecewise encryption and decryption

Encrypt a large data element where data is loaded in chunks

Decrypt a large data element where data is loaded in chunks

Structured Data Encryption

Requirements

Configuration

Encrypt a social security text field - simple interface

Decrypt a social security text field - simple interface

Encrypt a social security text field - bulk interface

Decrypt a social security text field - bulk interface

Sample Application

Overview

Dockerized samples

Installation

Credentials file

Build the examples

Example for Unstructured Data

View program options

Linux / Mac / Unix

Windows

Demonstrate using the simple (-s / --simple) API interface to encrypt the README file

Linux / Mac / Unix

Windows

Demonstrate using the simple (-s / --simple) API interface to decrypt the README file

Linux / Mac / Unix

Windows

Demonstrate using the piecewise (-p / --piecewise) API interface to encrypt the README file

Linux / Mac / Unix

Windows

Demonstrate using the piecewise (-p / --piecewise) API interface to decrypt the README file

Linux / Mac / Unix

Windows

Example for Structured Data

Documentation for ubiq_sample_fpe.c and ubiq_sample_fpe.cpp

Installation

Build the Examples

View Program Options

Demonstrate encrypting a social security number and returning a cipher text

Demonstrate decrypting a social security number and returning the plain text

Encrypt For Search

❗️
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).