ubiq

package module
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2023 License: MIT Imports: 29 Imported by: 0

README

Ubiq Security Go Library

The Ubiq Security Go library provides convenient interaction with the Ubiq Security Platform API for applications written Go. It includes a pre-defined set of functions and 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 library needs to be configured with your account credentials which are available in your Ubiq Dashboard credentials. The credentials can be set using environment variables, loaded from an explicitly specified file, or read from the default location (~/.ubiq/credentials).

Read credentials from a specific file and use a specific profile
credentials, err := ubiq.NewCredentials(
        "/path/to/credentials", "profile-name")
Read credentials from ~/.ubiq/credentials and use the default profile
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

credentials, err := ubiq.NewCredentials()
Explicitly set the credentials
credentials, err := ubiq.NewCredentials(
        "..." /* access key id */,
        "..." /* secret signing key */,
        "..." /* secret crypto access key */,
        "..." /* Ubiq API server, may omit this parameter */)
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...)

Documentation

Index

Constants

View Source 
const (
	// The Ubiq Go library version.
	Version = "0.0.3"
)

Variables

This section is empty.

Functions

func Decrypt 

func Decrypt(c Credentials, ciphertext []byte) ([]byte, error)

Decrypt decrypts a single ciphertext message. The credentials must be associated with the key used to encrypt the cipher text.

Upon success, error is nil, and the plain text is returned. If an error occurs, it will be indicated by the error return value.

func Encrypt 

func Encrypt(c Credentials, plaintext []byte) ([]byte, error)

Encrypt encrypts a single plain text message using a new key and the algorithm associated with the specified credentials.

Upon success, error is nil, and the cipher text is returned. If an error occurs, it will be indicated by the error return value.

func FPDecrypt added in v0.0.3 

func FPDecrypt(c Credentials, ffs, ct string, twk []byte) (string, error)

FPDecrypt performs a format preserving decryption of a ciphertext. The credentials must be associated with the key used to encrypt the ciphertext.

@ffs is the name of the format used to encrypt the data @twk may be nil, in which case, the default will be used. In either case it must match that used during encryption

Upon success, error is nil, and the plaintext is returned. If an error occurs, it will be indicated by the error return value.

func FPEncrypt added in v0.0.3 

func FPEncrypt(c Credentials, ffs, pt string, twk []byte) (string, error)

FPEncrypt performs a format preserving encryption of a plaintext using the supplied credentials and according to the format named by @ffs

@twk may be nil, in which case, the default will be used

Upon success, error is nil, and the ciphertext is returned. If an error occurs, it will be indicated by the error return value.

Types

type Credentials 

type Credentials struct {
	// contains filtered or unexported fields
}

Credentials holds the caller's credentials which are used to authenticate the caller to the Ubiq platform. Credentials must always be created/initialized via the NewCredentials function.

func NewCredentials 

func NewCredentials(args ...string) (Credentials, error)

NewCredentials creats a Credentials object and populates it with the caller's credentials according to the number of arguments passed to it.

If 0 arguments are passed to the function, the credentials will be loaded from the environmental variables UBIQ_ACCESS_KEY_ID, UBIQ_SECRET_SIGNING_KEY, UBIQ_SECRET_CRYPTO_ACCESS_KEY, and UBIQ_SERVER. The credentials associated with the "default" profile will be loaded from the default credentials file (~/.ubiq/credentials) and used to supplement any values missing from the environment.

If 1 or 2 arguments are passed, they are treated as the name of the file from which to load credentials and the name of the profile to use, respectively. If either argument is empty or missing, the value of the parameter as described in the case of 0 arguments will be used. Environmental variables are ignored except for UBIQ_SERVER which may still override credentials found in the file.

If 3 or 4 arguments are passed, they are treated as the ACCESS_KEY_ID, SECRET_SIGNING_KEY, SECRET_CRYPTO_ACCESS_KEY, and SERVER, respectively. If SERVER is not specified, it will be assigned the default value. The SERVER may specify http:// or https://. If neither is specified, the https:// prefix will be added.

type Decryption 

type Decryption struct {
	// contains filtered or unexported fields
}

Decryption holds the context of a piecewise decryption operation. Use NewDecryption() to create/initialize an Decryption object.

The caller should use the Begin(), Update()..., End() sequence of calls to decrypt data. When decryption is complete, the caller should call Close().

func NewDecryption 

func NewDecryption(c Credentials) (*Decryption, error)

NewDecryption creates a new Decryption object which holds the context of a decryption while it is in process.

func (*Decryption) Begin 

func (this *Decryption) Begin() ([]byte, error)

Begin starts a new decryption operation. The Decryption object must be newly created by the NewDecryption object, or the previous decryption performed by it must have been ended with the End() function.

error is nil upon success. No data is returned by this call; however, a slice is returned to maintain the same function signature as the corresponding Encryption call.

func (*Decryption) Close 

func (this *Decryption) Close() error

Close cleans up the Decryption object and resets it to its default values. An error returned by this function is a result of a miscommunication with the server, and the object is reset regardless.

func (*Decryption) End 

func (this *Decryption) End() ([]byte, error)

End completes the decryption of a cipher text message. For certain algorithms, message authenticity checks will be performed, and any remaining plain text will be returned.

error is nil upon success and the byte slice may or may not contain any remaining plain text. If error is non-nil, any previously decrypted plain text should be discarded.

func (*Decryption) Update 

func (this *Decryption) Update(ciphertext []byte) ([]byte, error)

Update passes cipher text into the Decryption object for decryption. Depending on how much data has been previously processed by Update and how much is passed by the current call, the function may or may not return any data.

error is nil on success and the slice may or may not contain plain text. If error is non-nil, the caller may call End() (which may also return an error) to reset the Decryption object for a new decryption.

Note that even though plain text may be returned by this function, it should not be trusted until End() has returned successfully.

type Encryption 

type Encryption struct {
	// contains filtered or unexported fields
}

Encryption holds the context of a piecewise encryption operation. Use NewEncryption() to create/initialize an Encryption object.

After creating an Encryption object, the caller should use the Begin(), Update()..., End() sequence of calls for as many separate encryptions need to be performed using the key associated with the Encryption object. When all encryptions are complete, call Close().

func NewEncryption 

func NewEncryption(c Credentials, uses uint) (*Encryption, error)

NewEncryption creates a new Encryption object with a new key that can be used, at most, the specified number of times. (The actual number may be less, depending on security settings at the server.)

func (*Encryption) Begin 

func (this *Encryption) Begin() ([]byte, error)

Begin starts a new encryption operation. The Encryption object must be newly created by the NewEncryption object, or the previous encryption performed by it must have been ended with the End() function.

error is nil upon success. Information about the encryption is returned on success and must be treated as part of the cipher text

func (*Encryption) Close 

func (this *Encryption) Close() error

Close cleans up the Encryption object and resets it to its default values. An error returned by this function is a result of a miscommunication with the server, and the object is reset regardless.

func (*Encryption) End 

func (this *Encryption) End() ([]byte, error)

End completes the encryption of a plain text message. For certain algorithms, message authenticity checks will be performed, and any remaining plain text will be returned.

error is nil upon success and the byte slice may or may not contain any remaining plain text. If error is non-nil, any previously decrypted plain text should be discarded.

func (*Encryption) Update 

func (this *Encryption) Update(plaintext []byte) ([]byte, error)

Update passes plain text into the Encryption object for encryption. Depending on how much data has been previously processed by Update and how much is passed by the current call, the function may or may not return any data.

error is nil on success and the slice may or may not contain cipher text.

type FPDecryption added in v0.0.3 

type FPDecryption fpeContext

Reusable object to preserve context across multiple decryptions using the same format

func NewFPDecryption added in v0.0.3 

func NewFPDecryption(c Credentials, ffs string) (*FPDecryption, error)

Create a new format preserving decryption object. The returned object can be reused to decrypt multiple ciphertexts using the format (and algorithm and key) named by @ffs

func (*FPDecryption) Cipher added in v0.0.3 

func (this *FPDecryption) Cipher(ct string, twk []byte) (
	pt string, err error)

Decrypt a ciphertext string using the key, algorithm, and format preserving parameters defined by the decryption object.

@twk may be nil, in which case, the default will be used. Regardless, the tweak must match the one used during encryption of the plaintext

type FPEncryption added in v0.0.3 

type FPEncryption fpeContext

Reusable object to preserve context across multiple encryptions using the same format

func NewFPEncryption added in v0.0.3 

func NewFPEncryption(c Credentials, ffs string) (*FPEncryption, error)

Create a new format preserving encryption object. The returned object can be reused to encrypt multiple plaintexts using the format (and algorithm and key) named by @ffs

func (*FPEncryption) Cipher added in v0.0.3 

func (this *FPEncryption) Cipher(pt string, twk []byte) (
	ct string, err error)

Encrypt a plaintext string using the key, algorithm, and format preserving parameters defined by the encryption object.

@twk may be nil, in which case, the default will be used

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.