engine

Documentation

Overview

Package engine provides field encryption and blind index computation for CipherSweet.

Overview

The Engine wires a root key provider to a cryptographic backend. It derives per-field and per-index keys scoped to a table name, field name, and index name, then delegates all cryptographic operations (including key derivation) to the backend. The backend is responsible for implementing the key hierarchy as defined by paragonie/ciphersweet.

Key Features

• Authenticated encryption for field ciphertext.
• Deterministic blind index values for exact-match searching.
• Pluggable cryptographic backends.
• Concurrency-safe operation after construction.

Example:

kp, err := keyprovider.NewStringProvider(
    "84d269301777265c1915f44f9f9f36a34323fed7c6e0069bdbf03ea37ecb0880",
)
if err != nil {
    panic(err)
}

eng, err := engine.New(backend.NewNaCl(), kp)
if err != nil {
    panic(err)
}

ef := field.New(eng, "users", "email").
    AddBlindIndex(blindindex.New("email_index"))

ct, indexes, err := ef.PrepareForStorage("alice@example.com")
if err != nil {
    panic(err)
}

plaintext, err := ef.Decrypt(ct)
if err != nil {
    panic(err)
}

// Search value for an exact-match query:
idx, err := ef.GetBlindIndex("alice@example.com", "email_index")
if err != nil {
    panic(err)
}

_ = indexes
_ = plaintext
_ = idx

Architecture / Design

Engine is a thin coordinator. It uses a backend.Backend implementation to:

• derive an encryption key for (tableName, fieldName), then encrypt and decrypt values; and
• derive an index key for (tableName, fieldName, indexName), then compute blind indexes using either a fast or slow backend algorithm.

Security Notes

CipherSweet encryption is authenticated. If the ciphertext is tampered with, or if an incorrect root key is supplied, decryption fails.

Blind index values are deterministic for a given plaintext and index configuration, so they should be treated as sensitive.

Compatibility

With the NaCl backend (backend.NewNaCl, also referred to as ModernCrypto / "modern"), ciphertexts and blind index parameters are intended to be wire- compatible with Laravel CipherSweet implementations (magentron/ciphersweet-for-laravel and bjornvoesten/ciphersweet).

Project Information

Package name: engine Project description: Wires the CipherSweet root key to a backend and provides field encryption and blind index computation primitives. Key features:

• Field key derivation and encryption
• Blind index derivation and computation
• Backend pluggability via backend.Backend

Example usage: field.New(eng, table, field).AddBlindIndex(...) Special notes: Deterministic blind index values can be used to test for equality of plaintexts.

Index

• type Engine
  • func MustNew(b backend.Backend, kp keyprovider.KeyProvider) *Engine
  • func New(b backend.Backend, kp keyprovider.KeyProvider) (*Engine, error)
  • func (e *Engine) Backend() backend.Backend
  • func (e *Engine) BlindIndexFast(transformedValue string, tableName, fieldName, indexName string, ...) (string, error)
  • func (e *Engine) BlindIndexSlow(transformedValue string, tableName, fieldName, indexName string, ...) (string, error)
  • func (e *Engine) DecryptField(ciphertext, tableName, fieldName string, aad []byte) ([]byte, error)
  • func (e *Engine) EncryptField(plaintext []byte, tableName, fieldName string, aad []byte) (string, error)

Types

type Engine

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

Engine holds the root key and wires it to a Backend. Safe for concurrent use after construction.

func MustNew

func MustNew(b backend.Backend, kp keyprovider.KeyProvider) *Engine

MustNew is like New but panics on error.

func New

func New(b backend.Backend, kp keyprovider.KeyProvider) (*Engine, error)

New creates an Engine, eagerly fetching and caching the root key.

func (*Engine) Backend

func (e *Engine) Backend() backend.Backend

Backend returns the underlying Backend.

func (*Engine) BlindIndexFast

func (e *Engine) BlindIndexFast(
	transformedValue string,
	tableName, fieldName, indexName string,
	outputBits int,
) (string, error)

BlindIndexFast derives the index key then computes a BLAKE2b blind index.

func (*Engine) BlindIndexSlow

func (e *Engine) BlindIndexSlow(
	transformedValue string,
	tableName, fieldName, indexName string,
	outputBits int,
	cfg *argon.Config,
) (string, error)

BlindIndexSlow derives the index key then computes an Argon2id blind index.

func (*Engine) DecryptField

func (e *Engine) DecryptField(ciphertext, tableName, fieldName string, aad []byte) ([]byte, error)

DecryptField derives the field key then decrypts ciphertext.

func (*Engine) EncryptField

func (e *Engine) EncryptField(plaintext []byte, tableName, fieldName string, aad []byte) (string, error)

EncryptField derives the field key then encrypts plaintext. The key derivation follows the paragonie key hierarchy exactly.