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 .debfiles. 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 How to Use API Key Credentials. 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();