Go Library

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

Overview

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

Documentation

See the Go API docs and below for examples.

Individual interfaces are documented in greater detail in the source code which can be viewed using the go doc tool.

Building from source:

Import the Ubiq Go library in your source files:

import "gitlab.com/ubiqsecurity/ubiq-go"

Available symbols are in the ubiq namespace/package.

Requirements

The library has been tested with Go 1.10; however, it may work with older versions.

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, err := ubiq.NewCredentials(
        "/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, err := ubiq.NewCredentials()

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, err := ubiq.NewCredentials()

Explicitly set the credentials

/* This example is for development use only - Storing Ubiq API Key Credentials in source code is INSECURE!*/
credentials, err := ubiq.NewCredentials(
        "..." /* 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.

var pt []byte = ...
credentials, err := ubiq.NewCredentials()
ct, err := 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.

var ct []byte = ...
credentials, err := ubiq.NewCredentials()
pt, err := 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
  • Call the encryption instance end method
var pt []byte = make([]byte, 128*1024)

credentials, _ := ubiq.NewCredentials()
encryption, _ := ubiq.NewEncryption(credentials, 1)
defer encryption.Close()

ct, _ := encryption.Begin()
for {
        n, e := infile.Read(pt)
        if e == io.EOF {
                break
        }
        t, _ := encryption.Update(pt[:n])
        ct = append(ct, t...)
}
t, _ := encryption.End()
ct = append(ct, t...)

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
var ct []byte = make([]byte, 128*1024)

credentials, _ := ubiq.NewCredentials()
decryption, _ := ubiq.NewDecryption(credentials)
defer decryption.Close()

pt, _ := decryption.Begin()
for {
        n, e := infile.Read(ct)
        if e == io.EOF {
                break
        }
        t, _ := decryption.Update(ct[:n])
        pt = append(pt, t...)
}
t, _ := decryption.End()
pt = append(pt, t...)



Sample Application

Overview

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

Installation

Make sure Go is installed on your system.

On Debian and Debian-like Linux systems:

sudo apt install golang

For MacOS, Windows, and other Linux systems, see the Go installation page.

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

Create a local directory and compile the example application:

git clone https://gitlab.com/ubiqsecurity/ubiq-go.git
cd ubiq-go/examples
go get
go build ubiq_sample.go

Older versions of Go may produce a message like the following:

go get: no install location for directory /path/to/ubiq-go/examples outside GOPATH
	For more details see: 'go help gopath'

This can be safely ignored for the purpose of building the example.

Example for Unstructured Data

View Program Options

From within the examples directory:

./ubiq_sample -h
Usage: ./ubiq_sample -e|-d -s|-p -i INFILE -o OUTFILE
Encrypt or decrypt files using the Ubiq service

  -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 the output file
  -d, -decrypt            Decrypt the contents of the input file and write
                            the results to the 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

./ubiq_sample -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

./ubiq_sample -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

./ubiq_sample -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

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