C++ Library

Step-by-step instructions for protecting data in your C++ application

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.

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:

# 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

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+

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
# for development headers needed to build the library
sudo apt install libcurl4-openssl-dev libssl-dev

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:

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.

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
  • Call the encryption instance close 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
  • Call the decryption instance close 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());