Home

Python Library

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

Overview

The Ubiq Security Python library provides convenient interaction with the Ubiq Platform API from applications written in the Python language. It includes a pre-defined set of classes that will provide simple interfaces to encrypt and decrypt data.

Installation

Using the package manager:

You don't need this source code unless you want to modify the package. If you just want to use the package, install from PyPi using pip3, a package manager for Python3.

pip3 install --upgrade ubiq-security

Installing from source:

From within the cloned git repository directory. Install from source with:

git clone https://gitlab.com/ubiqsecurity/ubiq-python.git
cd ubiq-python
python3 setup.py install

Note: You may need to run the python3 commands above using sudo.

Requirements

  • Python 3.5+

Usage

Initialize

import ubiq_security as ubiq

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
credentials = ubiq.configCredentials(config_file = "some-credential-file", profile = "some-profile")

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 = ubiq.configCredentials()

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
credentials = ubiq.credentials()

Explicitly set the API Key Credentials

# This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!
credentials = ubiq.credentials(access_key_id = "...", secret_signing_key = "...", secret_crypto_access_key = "...")

Handling exceptions

Unsuccessful requests raise exceptions. The class of the exception will reflect the sort of error that occurred. Please see the API Reference for a description of the error classes you should handle, and for information on how to inspect these errors.

Unstructured Data Encryption

Configuration

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

Encrypt a simple block of data

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

import ubiq_security as ubiq

encrypted_data = ubiq.encrypt(credentials, plaintext_data)

Decrypt a simple block of data

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

import ubiq_security as ubiq

plaintext_data = ubiq.decrypt(credentials, encrypted_data)

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
import ubiq_security as ubiq

# Process 1 MiB of plaintext data at a time
BLOCK_SIZE = 1024 * 1024

# Rest of the program
....

   encryption = ubiq.encryption(credentials, 1)

   # Write out the header information
   encrypted_data = encryption.begin()
    
   # Loop until the end of the input file is reached
   while True:
       data = infile.read(BLOCK_SIZE)
       encrypted_data += encryption.update(data)
       if (len(data) != BLOCK_SIZE):
          break

   # Make sure any additional encrypted data is retrieved from encryption instance
   # and resources are freed
   encrypted_data += 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
  • Call the decryption instance end method
import ubiq_security as ubiq

# Process 1 MiB of encrypted data at a time
BLOCK_SIZE = 1024 * 1024

# Rest of the program
....

    decryption = ubiq.decryption(creds)

    # Start the decryption and get any header information
    plaintext_data = decryption.begin()

    # Loop until the end of the input file is reached
    while True:
    	data = infile.read(BLOCK_SIZE)
        plaintext_data += decryption.update(data)
        if (len(data) != BLOCK_SIZE):
            break

    # Make sure an additional plaintext data is retrieved and
    # release any allocated resources
    plaintext_data += decryption.end()

Structured Data Encryption

This library incorporates Ubiq Format Preserving Encryption (eFPE).

Requirements

  • Please follow the same requirements as described above for the non-eFPE functionality.
  • This library has dependencies on ubiqsecurity-fpe library available for download in the Ubiq GitHub/GitLab repository.

Usage

You will need to obtain account credentials in the same way as described above for conventional encryption/decryption. When you do this in your Ubiq Dashboard credentials, you'll need to enable the eFPE option. The credentials can be set using environment variables, loaded from an explicitly specified file, or read from the default location (~/.ubiq/credentials).

Require the Security Client module in your Python class.

import ubiq_security as ubiq
import ubiq_security.fpe as ubiqfpe

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.

ffs_name = "SSN";
plain_text = "123-45-6789";

credentials = ubiq.ConfigCredentials('./credentials', 'default');

encrypted_data = ubiqfpe.Encrypt(
        credentials,
        ffs_name,
        plain_text);
        
print('ENCRYPTED ciphertext= ' + encrypted_data + '\n');

Decrypt a social security text field - simple interface

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

ffs_name = "SSN";
cipher_text = "300-0E-274t";

credentials = ubiq.ConfigCredentials('./credentials', 'default');

decrypted_text = ubiqfpe.Decrypt(
        credentials,
        ffs_name,
        cipher_text);
        
print('DECRYPTED decrypted_text= ' + decrypted_text + '\n');

Additional information on how to use these FFS models in your own applications is available by contacting Ubiq.

Sample Application

Overview

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

Installation

Make sure to first install the ubiq-security library

pip3 install --upgrade ubiq-security

Credentials File

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

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

Example for Unstructured Data

View program options

From within the examples directory 

cd examples
python3 ubiq_sample.py -h


Optional arguments:

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

Demonstrate using the simple (-s / --simple) API interface to encrypt this README.md file and write the encrypted data to /tmp/readme.enc

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

Demonstrate using the simple (-s / --simple) API interface to decrypt the /tmp/readme.enc file and write the decrypted output to /tmp/README.out

python3 ubiq_sample.py -i /tmp/readme.enc -o /tmp/README.out -d -s -c ./credentials

Demonstrate using the piecewise (-p / --piecewise) API interface to encrypt this README.md file and write the encrypted data to /tmp/readme.enc

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

Demonstrate using the piecewise (-p / --piecewise) API interface to decrypt the /tmp/readme.enc file and write the decrypted output to /tmp/README.out

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

Updated 4 months ago

© 2023 Ubiq Security, Inc. All rights reserved.