encryption

Documentation

Overview

Package encryption provides KeyProvider implementations for mfx:"encrypted" struct fields. The two bundled implementations are EnvKeyProvider (keys from environment variables) and VaultKeyProvider (HashiCorp Vault Transit engine).

Envelope format produced by EnvKeyProvider:

[ version:1 ][ keyIDLen:2 BE ][ keyID:N ][ nonce:12 ][ gcmCiphertext:M ]

Stored in the DB as the string "enc:<base64(envelope)>". The "enc:" prefix lets the framework distinguish already-encrypted values from legacy plaintext when a model is being migrated to encryption.

Index

• type EnvKeyProvider
  • func (p *EnvKeyProvider) Decrypt(_ context.Context, envelope []byte) ([]byte, error)
  • func (p *EnvKeyProvider) Encrypt(_ context.Context, keyID string, plaintext []byte) ([]byte, error)
  • func (p *EnvKeyProvider) HMAC(_ context.Context, keyID string, data []byte) ([]byte, error)
  • func (p *EnvKeyProvider) KeyIDOf(envelope []byte) (string, error)
• type VaultKeyProvider
  • func (v *VaultKeyProvider) Decrypt(ctx context.Context, envelope []byte) ([]byte, error)
  • func (v *VaultKeyProvider) Encrypt(ctx context.Context, keyID string, plaintext []byte) ([]byte, error)
  • func (v *VaultKeyProvider) HMAC(ctx context.Context, keyID string, data []byte) ([]byte, error)
  • func (v *VaultKeyProvider) KeyIDOf(envelope []byte) (string, error)

Types

type EnvKeyProvider

type EnvKeyProvider struct {
	// Prefix is prepended to the keyID when building the env var name.
	// Default: "MFX_KEY".
	Prefix string
}

EnvKeyProvider loads AES-256-GCM keys from environment variables.

The env var name is built as: {Prefix}_{KEYID_UPPER} where hyphens in keyID are replaced with underscores and everything is uppercased. For example:

Prefix "MFX_KEY" + keyID "patient-pii"  →  MFX_KEY_PATIENT_PII
Prefix "MFX_KEY" + keyID "default"      →  MFX_KEY_DEFAULT

Each env var must contain a base64-encoded 32-byte (256-bit) key. Generate one with:

openssl rand -base64 32

Usage:

server := maniflex.New(maniflex.Config{
    KeyProvider: &encryption.EnvKeyProvider{Prefix: "MYAPP_KEY"},
})

func (*EnvKeyProvider) Decrypt

func (p *EnvKeyProvider) Decrypt(_ context.Context, envelope []byte) ([]byte, error)

Decrypt decrypts an envelope produced by Encrypt. It reads the keyID from the envelope, loads the corresponding env var key, and decrypts with AES-256-GCM.

func (*EnvKeyProvider) Encrypt

func (p *EnvKeyProvider) Encrypt(_ context.Context, keyID string, plaintext []byte) ([]byte, error)

Encrypt encrypts plaintext with AES-256-GCM and returns a binary envelope. The envelope is self-describing: it embeds the keyID so that Decrypt never needs the caller to supply a key name.

func (*EnvKeyProvider) HMAC

func (p *EnvKeyProvider) HMAC(_ context.Context, keyID string, data []byte) ([]byte, error)

HMAC returns HMAC-SHA256 of data using the named key. Used to enforce UNIQUE constraints on encrypted fields without storing plaintext.

func (*EnvKeyProvider) KeyIDOf

func (p *EnvKeyProvider) KeyIDOf(envelope []byte) (string, error)

KeyIDOf extracts the keyID from an envelope without decrypting it.

type VaultKeyProvider

type VaultKeyProvider struct {
	// Address is the Vault server URL. Required.
	Address string
	// Token is the Vault authentication token. Required.
	Token string
	// Mount is the Transit secrets engine path. Default: "transit".
	Mount string
	// Client is the HTTP client used for Vault calls. Defaults to http.DefaultClient.
	Client *http.Client
}

VaultKeyProvider encrypts and decrypts via HashiCorp Vault's Transit secrets engine. The keyID maps to a Transit key name (e.g. "patient-pii").

Vault manages key material, versioning, and rotation internally. This provider stores a thin envelope in the DB:

[ version:1 ][ keyIDLen:2 BE ][ keyID:N ][ vaultCiphertext:M ]

The vaultCiphertext is the Vault-returned string (e.g. "vault:v1:..."), which embeds Vault's own key version, so decryption after a Vault key rotation is transparent — Vault handles both old and new key versions automatically.

Authentication uses a static token. For production, wrap this provider and refresh the token from AppRole/Kubernetes auth before each operation.

Usage:

server := maniflex.New(maniflex.Config{
    KeyProvider: &encryption.VaultKeyProvider{
        Address: "http://vault:8200",
        Token:   os.Getenv("VAULT_TOKEN"),
    },
})

func (*VaultKeyProvider) Decrypt

func (v *VaultKeyProvider) Decrypt(ctx context.Context, envelope []byte) ([]byte, error)

Decrypt decrypts a Vault envelope. It reads the keyID and Vault ciphertext from the envelope and sends them to the Vault Transit decrypt endpoint.

func (*VaultKeyProvider) Encrypt

func (v *VaultKeyProvider) Encrypt(ctx context.Context, keyID string, plaintext []byte) ([]byte, error)

Encrypt encrypts plaintext via Vault Transit and returns a binary envelope.

func (*VaultKeyProvider) HMAC

func (v *VaultKeyProvider) HMAC(ctx context.Context, keyID string, data []byte) ([]byte, error)

HMAC returns a Vault-keyed HMAC of data using the Transit HMAC endpoint. Vault's HMAC uses the named key so the digest is tied to key ownership.

func (*VaultKeyProvider) KeyIDOf

func (v *VaultKeyProvider) KeyIDOf(envelope []byte) (string, error)

KeyIDOf extracts the Vault Transit key name from an envelope without decrypting.