tred

Documentation

Overview

Package tred provides a reference implementation for the Tamper Resistant Encrypted Data protocol.

Proper secure data management must support scenarios for in-transit and at-rest use cases. For network communications (i.e, in-transit) there are already well established and secure protocols available like TLS. The protocols available for secure data persistence (i.e., at-rest) on the other hand are not as reliable and/or robust for several reasons.

TRED introduces a secure, fast and easy-to-use mechanism to handle secure data persistence. The protocol uses a simple data structure that introduces very small overhead, prevent cipher text manipulation and greatly simplifies data integrity validation.

The original data is split into individual packets for optimum security and performance. Each packet is properly tagged and processed using an authentication encryption cipher. The final output prevent manipulation (tamper attempts) of the produced cipher text.

// output:
packet[...]

// packet:
// tag is calculated and validated by the AEAD cipher
header (16) | payload (1 byte - 64 KB) | tag (16)

// header:
version (1) | cipher (1) | payload length (2) | seq (4) | nonce (8)

Usage

To facilitate the integration of the protocol with higher level components and primitives this package introduces a 'Worker' component with a simple interface.

content := make([]byte, 1024*256)
rand.Read(content)

// Create a worker instance using the ChaCha20 cipher
conf, _ := DefaultConfig([]byte("super-secret-key"))
conf.Cipher = CHACHA20
w, _ := NewWorker(conf)

// Encrypt data
secure := bytes.NewBuffer([]byte{})
_, _ = w.Encrypt(bytes.NewReader(content), secure)
if bytes.Equal(content, secure.Bytes()) {
	panic("failed to encrypt original content")
}

// Decrypt data
verification := bytes.NewBuffer([]byte{})
_, _ = w.Decrypt(secure, verification)
if !bytes.Equal(content, verification.Bytes()) {
	panic("failed to decrypt data")
}

Index

• Constants
• Variables
• type Config
  • func DefaultConfig(k []byte) (*Config, error)
  • func (c *Config) Validate() error
• type Result
• type Worker
  • func NewWorker(c *Config) (*Worker, error)
  • func (w *Worker) Decrypt(input io.Reader, output io.Writer) (*Result, error)
  • func (w *Worker) Encrypt(input io.Reader, output io.Writer) (*Result, error)

Examples

• NewWorker

Constants

const (
	// Version10 provides the protocol version tag for 1.0.
	Version10 = 0x10

	// AES in GCM mode cipher code.
	AES = 0x00

	// CHACHA20 cipher code.
	CHACHA20 = 0x01
)

Variables

var (
	ErrInvalidSequenceNumber = "out of order packet"
	ErrInvalidPacketTag      = "invalid packet tag"
	ErrInvalidPayloadLen     = "invalid payload size"
	ErrUnsupportedCipher     = "unsupported cipher suite"
	ErrUnsupportedVersion    = "unsupported version code"
	ErrNoKey                 = "value for key is required"
	ErrRandomNonce           = "failed to read random nonce"
)

Common error values.

Types

type Config

type Config struct {
	// Protocol version
	Version byte

	// Cipher code
	Cipher byte

	// Secure cryptographic key to use
	Key []byte
	// contains filtered or unexported fields
}

Config provides all configuration parameters available when creating a new TRED worker agent.

func DefaultConfig

func DefaultConfig(k []byte) (*Config, error)

DefaultConfig generates sane default configuration parameters using the provided key value.

func (*Config) Validate

func (c *Config) Validate() error

Validate the configuration instance against common setup errors.

type Result

type Result struct {
	// Number of packets produced
	Packets uint32

	// Execution time
	Duration time.Duration
}

Result defines the output of a successful encrypt or decrypt operation.

type Worker

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

Worker provides a protocol agent.

func NewWorker

func NewWorker(c *Config) (*Worker, error)

NewWorker returns a usable protocol worker instance.

Example

Complete protocol usage. Error handling omitted for brevity.

// Get random content to encrypt
content := make([]byte, 1024*256)
rand.Read(content)

// Create a worker instance using the ChaCha20 cipher
conf, _ := DefaultConfig([]byte("super-secret-key"))
conf.Cipher = CHACHA20
w, _ := NewWorker(conf)

// Encrypt data
secure := bytes.NewBuffer([]byte{})
_, _ = w.Encrypt(bytes.NewReader(content), secure)
if bytes.Equal(content, secure.Bytes()) {
	panic("failed to encrypt original content")
}

// Decrypt data
verification := bytes.NewBuffer([]byte{})
_, _ = w.Decrypt(secure, verification)
if !bytes.Equal(content, verification.Bytes()) {
	panic("failed to decrypt data")
}

func (*Worker) Decrypt

func (w *Worker) Decrypt(input io.Reader, output io.Writer) (*Result, error)

Decrypt will open the secure 'input' content and send it to 'output'.

func (*Worker) Encrypt

func (w *Worker) Encrypt(input io.Reader, output io.Writer) (*Result, error)

Encrypt will secure the 'input' content and send it to 'output'.