Overview

The Ubiq Security Ruby Client 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.

Installation

Installing from Bundler

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

gem ubiq-security

Manual Install

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

gem install ubiq-security

Installing from Source

To build and install directly from a clone of the Gitlab directory:

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

Initialize

require 'ubiq-security'
include Ubiq

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
credentials = ConfigCredentials.new( "some-credential-file", "some-profile").get_attributes

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 = ConfigCredentials.new().get_attributes

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

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()