PHP Library
Step-by-step instructions for protecting data in your PHP application

Overview
The Ubiq Security PHP Library provides convenient interaction with the Ubiq Security Platform API from applications written in PHP. It includes a pre-defined set of functions and classes that will provide simple interfaces to encrypt and decrypt data.
Documentation
See the PHP API docs and below for examples.
Individual interfaces are documented in greater detail in the source code.
Installation
On Debian and Debian-like Linux systems:
sudo apt install php php-xml php-curl composer
Clone the PHP repository, and install dependencies:
git clone https://gitlab.com/ubiqsecurity/ubiq-php.git
cd ubiq-php
composer install
Requirements
The library has been tested with PHP 7.3.
To use the library in your code, simply:
require '/path/to/Ubiq.php';
Usage
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 set using environment variables, loaded from an explicitly specified 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 */
$credentials = new Ubiq\Credentials();
$credentials->load(
'/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 */
$credentials = new Ubiq\Credentials();
Use the following environment variables to set the 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 */
$credentials = new Ubiq\Credentials();
Explicitly set the credentials
/* This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!*/
$credentials = new Ubiq\Credentials();
$credentials->set(
'...' /* access key id */,
'...' /* secret signing key */,
'...' /* secret crypto access key */,
'...' /* Ubiq API server, may omit this parameter */
);
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.
$credentials = new Ubiq\Credentials();
$ct = Ubiq\encrypt($credentials, $pt);
Decrypt a single block of data
Pass credentials and encrypted data into the decryption function. The plaintext data will be returned.
$credentials = new Ubiq\Credentials();
$pt = Ubiq\decrypt($credentials, $ct);
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
Note that repeatedly calling the update method is not currently supported by the underlying PHP crypto library. However, the interface is present and can be used in cases where the caller wishes to reuse the encryption object for multiple encryptions.
- Call the encryption instance end method
$credentials = new Ubiq\Credentials();
$encryption = new Ubiq\Encryption($credentials, 1);
$pt = fread($infile, $filesize);
$ct = $encryption->begin();
$ct .= $encryption->update($pt);
$ct .= $encryption->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
Note that repeatedly calling the update method is not currently supported by the underlying PHP crypto library. However, the interface is present and can be used in cases where the caller wishes to reuse the decryption object for multiple decryptions.
- Call the decryption instance end method
$credentials = new Ubiq\Credentials();
$decryption = new Ubiq\Decryption($credentials, 1);
$ct = fread($infile, $filesize);
$pt = $decryption->begin();
$pt .= $decryption->update($ct);
$pt .= $decryption->end();
Sample Application
Overview
This sample application will demonstrate how to encrypt and decrypt data using the different APIs.
Documentation
See the PHP API docs.
Installation
Make sure PHP is installed on your system as described here.
Credentials file
Edit the credentials file with your account credentials created using the Ubiq dashboard
[default]
ACCESS_KEY_ID = ...
SECRET_SIGNING_KEY = ...
SECRET_CRYPTO_ACCESS_KEY = ...
Build the examples
Clone the PHP repository, and install dependencies
git clone https://gitlab.com/ubiqsecurity/ubiq-php.git
cd ubiq-php
composer install
Example for Unstructured Data
View Program Options
From the top level of the source directory:
php -f examples/ubiq_sample.php -- -h
Usage: examples/ubiq_sample.php -e|-d -i INFILE -o OUTFILE
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
-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 API interface to encrypt this README.md file and write the encrypted data to /tmp/readme.enc
php -f examples/ubiq_sample.php -- -i README.md -o /tmp/readme.enc -e -c ./credentials
Demonstrate using the simple API interface to decrypt the /tmp/readme.enc file and write the decrypted output to /tmp/README.out
php -f examples/ubiq_sample.php -- -i /tmp/readme.enc -o /tmp/README.out -d -c ./credentials
Updated 4 months ago