Ubiq Security Ruby Library

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

Documentation

See the Ruby API docs.

Installation

To install using Bundler add the following to your project's Gemfile

gem ubiq-security

To manually install ubiq-security via Rubygems simply use gem to install it:

gem install ubiq-security

To build and install directly from a clone of the gitlab repository source:

git clone https://gitlab.com/ubiqsecurity/ubiq-ruby.git
cd ubiq-ruby
bundle install
gem build ubiq-security.gemspec
gem install ./ubiq-security*.gem

You may need to run the gem install commands above using sudo.

Usage

The library needs to be configured with your account credentials which is
available in your Ubiq Dashboard Credentials. The credentials can be
explicitly set, set using environment variables, loaded from an explicit file
or read from the default location [~/.ubiq/credentials]

require 'ubiq-security'
include Ubiq

Read credentials from a specific file and use a specific profile

credentials = ConfigCredentials.new( "some-credential-file", "some-profile").get_attributes

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

credentials = ConfigCredentials.new().get_attributes

Use the following environment variables to set the credential values

UBIQ_ACCESS_KEY_ID
UBIQ_SECRET_SIGNING_KEY
UBIQ_SECRET_CRYPTO_ACCESS_KEY

credentials = Credentials()

Explicitly set the credentials

credentials = Credentials(access_key_id = "...", secret_signing_key = "...", secret_crypto_access_key = "...")

Encrypt a simple block of data

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

require 'ubiq-security'
include Ubiq

encrypted_data = 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.

require 'ubiq-security'
include Ubiq

plaintext_data = 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
Call the encryption instance close method

require 'ubiq-security'
include Ubiq

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

# Rest of the program
....
   encryption = Encryption.new(credentials, 1)

   # Write out the header information
   encrypted_data = encryption.begin()
    
   # Loop until the end of the input file is reached
    until infile.eof?
      chunk = infile.read BLOCK_SIZE
      encrypted_data += encryption.update(chunk)
    end
    # Make sure any additional encrypted data is retrieved from encryption instance
    encrypted_data += encryption.end()
   
    # Make sure to release any resources used during the encryption process
    encryption.close()

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

require 'ubiq-security'
include Ubiq

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

# Rest of the program
....

    decryption = Decryption(credentials)

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

    # Loop until the end of the input file is reached
    until infile.eof?
      chunk = infile.read BLOCK_SIZE
      plaintext_data += decryption.update(chunk)
    end
    
    # Make sure an additional plaintext data is retrieved from decryption instance
    plaintext_data += decryption.end()
    
    # Make sure to release any resources used during the decryption process
    decryption.close()

require 'ubiq-security'
include Ubiq

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

# Rest of the program
....
   encryption = Encryption.new(credentials, 1)

   # Write out the header information
   encrypted_data = encryption.begin()
    
   # Loop until the end of the input file is reached
    until infile.eof?
      chunk = infile.read BLOCK_SIZE
      encrypted_data += encryption.update(chunk)
    end
    # Make sure any additional encrypted data is retrieved from encryption instance
    encrypted_data += encryption.end()
   
    # Make sure to release any resources used during the encryption process
    encryption.close()

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

require 'ubiq-security'
include Ubiq

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

# Rest of the program
....

    decryption = Decryption(credentials)

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

    # Loop until the end of the input file is reached
    until infile.eof?
      chunk = infile.read BLOCK_SIZE
      plaintext_data += decryption.update(chunk)
    end
    
    # Make sure an additional plaintext data is retrieved from decryption instance
    plaintext_data += decryption.end()
    
    # Make sure to release any resources used during the decryption process
    decryption.close()

Sample Application

Overview

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

Installation

Make sure to first install the ubiq-security Ruby Client Library if you have not done so yet:

gem install ubiq-security

Then from within the example directory using Bundler:

cd example
bundle install
ruby ubiq_sample.rb -h

Credentials file

Edit the API Key Credentials file with your account 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 example directory:

cd example
ruby ubiq_sample.rb -h

Usage: ubiq_sample [options]
    -h, --help            Show this help message and exit
    -V, --version         Show program's version number and exit
    -e                    Encrypt the contents of the input file and write the results to output file
    -d                    Decrypt the contents of the input file and write the results to output file
    -s,                   Use the simple encryption / decryption interfaces
    -p,                   Use the piecewise encryption / decryption interfaces
    -i, --infile INFILE
                          The input file containing the data to be encrypted/decrypted
    -o, --outfile OUTFILE
                          The output file containing the result after encryption/decryption
    -c, --credentials CREDENTIALS
                          The name of the credentials file from where keys will be loaded
    -P PROFILE, --profile PROFILE
                          Identify the profile within the credentials file (default: default)

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

ruby ubiq_sample.rb -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

ruby ubiq_sample.rb -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

ruby ubiq_sample.rb -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

ruby ubiq_sample.rb -i /tmp/readme.enc -o /tmp/README.out -d -p -c ./credentials