The Ubiq Developer Hub

Welcome to the Ubiq developer hub. You'll find comprehensive guides and documentation to help you start working with Ubiq as quickly as possible, as well as support if you get stuck. Let's jump right in!

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

You don't need this source code unless you want to modify the library. 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, use -lubiqclient to link against the C library

Building from Source

To build and install directly from a clone of the Gitlab directory: Clone the repository, initialize the submodules, and build the packages:

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 . --target package

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

Requirements

# 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:

#include <ubiq/platform.h>
/* C
 *
 * Returns an `int` equal to 0 if the library is successfully
 * initialized and a negative value, otherwise.
 */
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 is 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].

Read credentials from a specific file and use a specific profile

struct ubiq_platform_credentials * credentials;

ubiq_platform_credentials_create_specific(
    "/path/to/credentials", "profile-name", &credentials);

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

struct ubiq_platform_credentials * credentials;

ubiq_platform_credentials_create(&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

struct ubiq_platform_credentials * credentials;

ubiq_platform_credentials_create(&credentials);

Explicitly set the API Key Credentials

struct ubiq_platform_credentials * credentials;

ubiq_platform_credentials_create_explicit(
    "..." /* access key id */,
    "..." /* secret signing key */,
    "..." /* secret crypto access key */,
    "..." /* Ubiq API server, may be NULL */,
    &credentials);

Handling exceptions

Unsuccessful functions return non-zero values. In general, these values are negative error numbers which indicate the nature of the error/failure. More common errors include:

  • -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
  • -EBADFD:
    The functions associated with a piecewise encryption or decryption have
    been called in an incorrect order
  • -EBADMSG:
    The server rejected a message from the client or vice versa. This is
    usually an incompatibility betweer 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
  • -EDQUOT:
    The encryption key has already been used the maximum number of times
  • -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
  • -EPROTO:
    A response from the server was not understood. This is a problem with the
    library and should be reported.

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>

struct ubiq_platform_credentials * creds = NULL;
void * ptbuf = NULL, * ctbuf = NULL;
size_t ptlen = 0, ctlen = 0;

/* initialize ptbuf and ptlen */
...

ubiq_platform_credentials_create(&creds);
ubiq_platform_encrypt(creds, ptbuf, ptlen, &ctbuf, &ctlen);
free(ctbuf);
ubiq_platform_credentials_destroy(creds);

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>

struct ubiq_platform_credentials * creds = NULL;
void * ptbuf = NULL, * ctbuf = NULL;
size_t ptlen = 0, ctlen = 0;

/* initialize ctbuf and ctlen */
...

ubiq_platform_credentials_create(&creds);
ubiq_platform_decrypt(creds, ctbuf, ctlen, &ptbuf, &ptlen);
free(ptbuf);
ubiq_platform_credentials_destroy(creds);

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)

struct ubiq_platform_credentials * credentials = NULL;
struct ubiq_platform_encryption * enc = NULL;
void * ctbuf = NULL, * buf = NULL;
size_t ctlen = 0, len = 0;

ubiq_platform_credentials_create(&credentials);
ubiq_platform_encryption_create(credentials, 1, &enc);

ubiq_platform_encryption_begin(enc, &buf, &len);
ctbuf = realloc(ctbuf, ctlen + len);
memcpy(ctbuf + ctlen, buf, len);
ctlen += len;
free(buf);

while (!feof(infp)) {
    char ptbuf[BLOCK_SIZE];
    size_t ptsize;

    ptsize = fread(ptbuf, 1, BLOCK_SIZE, infp);
    ubiq_platform_encryption_update(enc, ptbuf, ptsize, &buf, &len);
    ctbuf = realloc(ctbuf, ctlen + len);
    memcpy(ctbuf + ctlen, buf, len);
    ctlen += len;
    free(buf);
}

ubiq_platform_encryption_end(enc, &buf, &len);
ctbuf = realloc(ctbuf, ctlen + len);
memcpy(ctbuf + ctlen, buf, len);
ctlen += len;
free(buf);

ubiq_platform_encryption_destroy(enc);
ubiq_platform_credentials_destroy(credentials);

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)

struct ubiq_platform_credentials * credentials = NULL;
struct ubiq_platform_decryption * dec = NULL;
void * ptbuf = NULL, * buf = NULL;
size_t ptlen = 0, len = 0;

ubiq_platform_credentials_create(&credentials);
ubiq_platform_decryption_create(credentials, &dec);

ubiq_platform_decryption_begin(dec, &buf, &len);
ptbuf = realloc(ptbuf, ptlen + len);
memcpy(ptbuf + ptlen, buf, len);
ptlen += len;
free(buf);

while (!feof(infp)) {
    char ctbuf[BLOCK_SIZE];
    size_t ctsize;

    ctsize = fread(ctbuf, 1, BLOCK_SIZE, infp);
    ubiq_platform_decryption_update(dec, ctbuf, ctsize, &buf, &len);
    ptbuf = realloc(ptbuf, ptlen + len);
    memcpy(ptbuf + ptlen, buf, len);
    ptlen += len;
    free(buf);
}

ubiq_platform_decryption_end(dec, &buf, &len);
ptbuf = realloc(ptbuf, ptlen + len);
memcpy(ptbuf + ptlen, buf, len);
ptlen += len;
free(buf);

ubiq_platform_decryption_destroy(dec);
ubiq_platform_credentials_destroy(credentials);

Updated a day ago

C Library


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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.