Encryption

How Ballast encrypts sensitive data.

Ballast uses encryption to protect sensitive data at multiple layers.

Credential Encryption

Source credentials (OAuth tokens, database passwords, API keys) are encrypted before storage:

Algorithm

  • AES-256 encryption
  • CFB mode (Cipher Feedback)
  • Random IV per encryption

Key Management

The encryption key is:

  • Set via ENCRYPTION_KEY environment variable
  • Base64-encoded 32-byte key
  • Must be kept secret and backed up

What’s Encrypted

DataEncrypted
OAuth access tokensYes
OAuth refresh tokensYes
Database passwordsYes
API credentialsYes
Connection stringsYes

API Key Storage

API keys are hashed, not encrypted:

  • bcrypt hashing with salt
  • Cannot be recovered after creation
  • Verified by comparing hashes

This means:

  • Ballast cannot show you your key after creation
  • Lost keys must be replaced with new ones
  • Even database access doesn’t reveal keys

Data at Rest

PostgreSQL

Content stored in PostgreSQL includes:

  • Entity content (searchable text)
  • Metadata
  • User information

PostgreSQL encryption at rest depends on your deployment:

  • Self-hosted: Configure PostgreSQL’s native encryption
  • Cloud: Use managed database encryption features

Qdrant

Vector embeddings in Qdrant:

  • Contain numerical representations of content
  • Not directly readable as text
  • But could theoretically be inverted

Qdrant encryption depends on your deployment configuration.

Data in Transit

All network communication uses TLS:

ConnectionProtocol
API requestsHTTPS (TLS 1.2+)
DatabaseTLS (configurable)
QdrantTLS (configurable)
OAuth flowsHTTPS

Generating Encryption Keys

Generate a secure encryption key:

openssl rand -base64 32

Example output:

aaxqwQD9JlKPkyhBoZbpjwQysmeVAovra2FTMUOa6Vo=

Store this securely and back it up. If lost, encrypted credentials become unrecoverable.

Key Rotation

To rotate the encryption key:

  1. Export current credentials (decrypted)
  2. Update ENCRYPTION_KEY
  3. Re-encrypt all credentials
  4. Verify connections work

Key rotation requires downtime and is not automated.

Self-Hosting Considerations

For self-hosted deployments:

  • Store encryption key in secrets manager
  • Use separate key per environment
  • Back up keys securely
  • Enable database encryption at rest
  • Use TLS for all connections