fieldsec

Documentation

Overview

Package fieldsec provides field-level encryption for Go structs using hybrid encryption.

Index

• Constants
• Variables
• func Decrypt(model any, fields []string, privateKey *rsa.PrivateKey, keyIDField string) (any, error)
• func DecryptWithKeyPair(model any, fields []string, keyPair *KeyPair, expectedKeyID, keyIDField string) (any, error)
• func DecryptWithStore(model any, fields []string, store *KeyStore, keyID, keyIDField string) (any, error)
• func Encrypt(model any, fields []string, publicKey *rsa.PublicKey, keyID, keyIDField string) (any, error)
• func ParsePublicKeyBundle(bundle PublicKeyBundle) (*rsa.PublicKey, error)
• type KeyPair
  • func (kp *KeyPair) ExportPublicBundle() (PublicKeyBundle, error)
  • func (kp *KeyPair) IsExpired() bool
• type KeyStore
  • func NewKeyStore() *KeyStore
  • func (ks *KeyStore) Delete(id string)
  • func (ks *KeyStore) DeleteExpired() int
  • func (ks *KeyStore) GenerateKeyPair(validity time.Duration) (*KeyPair, error)
  • func (ks *KeyStore) Get(id string) (*KeyPair, bool)
  • func (ks *KeyStore) StartCleanupRoutine(interval time.Duration, stop <-chan struct{})
• type PublicKeyBundle

Constants

const CryptoAlgorithm = "RSA-OAEP-256+AES-256-GCM"

CryptoAlgorithm is the algorithm identifier for the hybrid encryption scheme.

This uses a combination of two algorithms:

• RSA-OAEP-256: Asymmetric encryption for key exchange (encrypts the AES key)
• AES-256-GCM: Symmetric encryption for data (encrypts the actual sensitive data)

Why hybrid encryption?

• RSA alone can only encrypt up to 214 bytes (for RSA-2048)
• AES alone requires secure key sharing between sender and receiver
• Hybrid approach: AES encrypts unlimited data (fast), RSA securely transmits the AES key

AES-256-GCM provides authenticated encryption, ensuring both confidentiality and integrity.

Variables

var (
	// ErrKeyNotFound indicates the requested key does not exist in the store.
	ErrKeyNotFound = errors.New("encryption key not found")

	// ErrKeyExpired indicates the key has expired and cannot be used.
	ErrKeyExpired = errors.New("encryption key expired")

	// ErrKeyMismatch indicates the provided key ID does not match the expected key.
	ErrKeyMismatch = errors.New("encryption key ID mismatch")

	// ErrDecryptionFailed indicates the decryption operation failed.
	ErrDecryptionFailed = errors.New("decryption failed")

	// ErrInvalidPublicKey indicates the public key format is invalid.
	ErrInvalidPublicKey = errors.New("invalid public key format")

	// ErrInvalidPath indicates the JSON path format is invalid.
	ErrInvalidPath = errors.New("invalid field path")

	// ErrFieldNotFound indicates the field was not found at the given path.
	ErrFieldNotFound = errors.New("field not found at path")
)

Encryption-related errors.

Functions

func Decrypt

func Decrypt(model any, fields []string, privateKey *rsa.PrivateKey, keyIDField string) (any, error)

Decrypt decrypts specified fields in a struct using hybrid decryption. The model can be any struct that is JSON-serializable. Fields are specified as dot-separated JSON paths (e.g., "source.ssh.privateKey"). Returns a new struct of the same type with decrypted fields.

Parameters:

• model: any JSON-serializable struct with encrypted fields
• fields: list of dot-separated JSON paths to decrypt
• privateKey: RSA private key for decryption
• keyIDField: JSON path where the keyID is stored (will be cleared after decryption)

Example:

fields := []string{"source.ssh.privateKey", "destination.minio.secretKey"}
decrypted, err := Decrypt(model, fields, privKey, "encryptionKeyId")

func DecryptWithKeyPair

func DecryptWithKeyPair(model any, fields []string, keyPair *KeyPair, expectedKeyID, keyIDField string) (any, error)

DecryptWithKeyPair validates the key pair and decrypts the model. It checks for key expiration and ID mismatch before decryption.

Parameters:

• model: any JSON-serializable struct with encrypted fields
• fields: list of dot-separated JSON paths to decrypt
• keyPair: the key pair containing the private key
• expectedKeyID: the key ID that was used for encryption
• keyIDField: JSON path where the keyID is stored

func DecryptWithStore

func DecryptWithStore(model any, fields []string, store *KeyStore, keyID, keyIDField string) (any, error)

DecryptWithStore retrieves the key from the store and decrypts the model. After successful decryption, the key is automatically deleted (one-time use).

Parameters:

• model: any JSON-serializable struct with encrypted fields
• fields: list of dot-separated JSON paths to decrypt
• store: the key store containing the private key
• keyID: the key ID used for encryption
• keyIDField: JSON path where the keyID is stored

func Encrypt

func Encrypt(model any, fields []string, publicKey *rsa.PublicKey, keyID, keyIDField string) (any, error)

Encrypt encrypts specified fields in a struct using hybrid encryption. The model can be any struct that is JSON-serializable. Fields are specified as dot-separated JSON paths (e.g., "source.ssh.privateKey"). Returns a new struct of the same type with encrypted fields.

Parameters:

• model: any JSON-serializable struct
• fields: list of dot-separated JSON paths to encrypt
• publicKey: RSA public key for encryption
• keyID: identifier for the key (stored in the result for decryption)
• keyIDField: JSON path where the keyID should be stored (e.g., "encryptionKeyId")

Example:

fields := []string{"source.ssh.privateKey", "destination.minio.secretKey"}
encrypted, err := Encrypt(model, fields, pubKey, "key-123", "encryptionKeyId")

func ParsePublicKeyBundle

func ParsePublicKeyBundle(bundle PublicKeyBundle) (*rsa.PublicKey, error)

ParsePublicKeyBundle parses a public key bundle and returns the RSA public key.

Types

type KeyPair

type KeyPair struct {
	ID         string
	PublicKey  *rsa.PublicKey
	PrivateKey *rsa.PrivateKey
	ExpiresAt  time.Time
}

KeyPair holds an RSA key pair with metadata.

func (*KeyPair) ExportPublicBundle

func (kp *KeyPair) ExportPublicBundle() (PublicKeyBundle, error)

ExportPublicBundle creates a bundle containing the public key for client use.

func (*KeyPair) IsExpired

func (kp *KeyPair) IsExpired() bool

IsExpired returns true if the key pair has expired.

type KeyStore

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

KeyStore manages encryption key pairs with automatic expiration.

func NewKeyStore

func NewKeyStore() *KeyStore

NewKeyStore creates a new key store.

func (*KeyStore) Delete

func (ks *KeyStore) Delete(id string)

Delete removes a key pair from the store.

func (*KeyStore) DeleteExpired

func (ks *KeyStore) DeleteExpired() int

DeleteExpired removes all expired keys from the store.

func (*KeyStore) GenerateKeyPair

func (ks *KeyStore) GenerateKeyPair(validity time.Duration) (*KeyPair, error)

GenerateKeyPair creates a new RSA-2048 key pair with the given validity duration.

func (*KeyStore) Get

func (ks *KeyStore) Get(id string) (*KeyPair, bool)

Get retrieves a key pair by ID.

func (*KeyStore) StartCleanupRoutine

func (ks *KeyStore) StartCleanupRoutine(interval time.Duration, stop <-chan struct{})

StartCleanupRoutine starts a background goroutine that periodically removes expired keys.

type PublicKeyBundle

type PublicKeyBundle struct {
	KeyID     string `json:"keyId"`
	Algorithm string `json:"algorithm"`
	PublicKey string `json:"publicKey"` // PEM encoded
	ExpiresAt string `json:"expiresAt"` // RFC3339 format
}

PublicKeyBundle contains the public key data for transmission to clients.