Configuration

This configures the behavior of the Encryption Proxy, including logging, storage, encryption, HTTP services, and the PostgreSQL proxy.

All configurations are in YAML form, but can be modified with ENV variable with EP_ prefix

EP_PROXY_POSTGRES_UPSTREAM_HOST="localhost:5432"
EP_PROXY_MYSQL_UPSTREAM_HOST="localhost:3306"

License

The license section defines how the application loads its licensing credentials. Licensing is used to enforce access control, features, or trial periods based on the certificate provided.

license:
  file: "licenses/client/trial_cert.pem"
  remote:
    url: "https://license-server.com/license.pem"

---

file

• Type: string

• Description: Specifies the local path to a PEM-encoded license file.

• Example: "licenses/client/trial_cert.pem"

• Behavior: The application will attempt to load the license from this file first.

---

remote.url

• Type: string

• Description: Fallback URL to fetch the license from a remote server if the local file is missing or fails to load.

• Example: "https://license-server.com/license.pem"

• Use Case: Useful for centralized license management or cloud environments where licenses are issued dynamically.

---

Behavior Summary

1. If license.file is provided and readable, the application will load the license from disk.

2. If license.file is missing or fails to load, it will try downloading the license from license.remote.url.

3. If both fail, the application may refuse to start or run in restricted mode depending on implementation.

---

Best Practices

• Use the local file option for offline deployments.

• Use the remote.url for centralized license distribution in CI/CD or dynamic environments.

• Keep the license file secure and ensure it is not exposed publicly.

Logging

log:
  level: trace
  format: pretty
  sync: false

level

Sets the verbosity of the logs. Available options:

• trace: Most detailed logs, including internal debugging.

• debug: Developer-focused logs.

• info: General system events (recommended default).

• warn: Unexpected, non-critical conditions.

• error: Only logs critical errors.

Use trace or debug in development; prefer info or warn in production.

---

format

Specifies the log output format:

• pretty: Human-readable output with structured indentation.

• json: Machine-readable JSON format, better for log aggregation tools (e.g., ELK, Datadog).

---

sync

• false (default): Logging is asynchronous for better performance.

• true: Forces synchronous logging; useful for debugging or troubleshooting.

⚠️ Do not use sync: true in production unless absolutely necessary.

Server

The server section controls the HTTP API server for the encryption services and migration system.

server:
  enabled: true
  listen: "0.0.0.0:9191"
  metrics_enabled: true
  services_enabled: true

---

enabled

• Type: boolean

• Description: Enables or disables the HTTP server.

• Default: true

When false, the encryption API and migration endpoints will not be started.

---

listen

• Type: string

• Description: The network address the server will bind to.

• Example: "0.0.0.0:9191" binds to all interfaces on port 9191.

Use "127.0.0.1:9191" for local access only, or bind to a specific interface if deploying in production.

---

metrics_enabled

• Type: boolean

• Description: Enables Prometheus-compatible metrics endpoint at /metrics.

• Default: true

Enabling this allows observability tools to scrape metrics for monitoring and alerting.

---

services_enabled

• Type: boolean

• Description: Toggles the encryption service APIs.

• Default: true

If set to false, the server will still run but the encryption endpoints (e.g., /encrypt, /decrypt) will be disabled.

---

Typical Use Cases

Mode	Configuration
Full service	All options enabled (default)
Metrics-only monitor	services_enabled: false for health/metrics-only
Migration-only node	Use alongside migration config, disable API if needed

Storage

storage:
  driver: "postgres"
  cleanup_token_interval: 30
  sqlite_config:
    path: "./proxy_data"
    in_memory: false
  postgres_config:
    host: "encryption-proxy-dev:5432"
    user: "dev"
    password: "dev"
    database: "proxy"
    ssl_mode: "require"
    ca_cert: "/etc/proxy/ssl/ca/ca.crt"
    client_cert: "/etc/proxy/ssl/client/client.crt"
    client_key: "/etc/proxy/ssl/client/client.key"

---

driver

• Specifies which backend to use for internal data storage:

  • "sqlite": Lightweight file-based DB (useful for development).

  • "postgres": Production-grade storage with advanced features.

---

cleanup_token_interval

• Defines how frequently (in seconds) expired authentication tokens are cleaned up.

• Default recommended: 30 seconds for active sessions.

---

sqlite_config

Used when driver: "sqlite".

• path: Filesystem path to the .sqlite file.

• in_memory: If true, data is stored in memory (non-persistent).

  ⚠️ Use only in testing/development environments.

---

postgres_config

Used when driver: "postgres".

Connection Details

• host: Hostname and port of the PostgreSQL server.

• user / password: PostgreSQL credentials.

• database: Database name used for storing proxy metadata.

TLS/SSL Options

• ssl_mode: Controls how TLS is negotiated. Options:

  • disable: No TLS

  • prefer: Use TLS if available

  • require: Enforce TLS (no server identity verification)

  • verify-ca: Verify server cert against CA

  • verify-full: Also verify server hostname matches cert

Recommended: require or verify-full in production.

• ca_cert: Path to the CA certificate for validating the server.

• client_cert: TLS certificate used by the proxy to authenticate to the PostgreSQL server.

• client_key: Private key for the client_cert.

---

Notes

• TLS files must be in PEM format and mounted into the container securely.

• Ensure PostgreSQL has ssl = on and is configured to accept TLS client certs if using verify-*.

• Database user should have full CRUD access on the selected schema.

Encryption

The encryption block controls how the system performs data encryption and decryption. This configuration is shared between the encryption services and the database proxy layer.

encryption:
  default_algorithm: "aes-128-gcm"
  envelope: false
  provider:
    database:
      id: "env"
      default: true
      key_prefix: "ENC_KEY_V"

---

default_algorithm

• Type: string

• Options: "aes-128-gcm", "aes-256-gcm"

• Description: Sets the default encryption algorithm used when no algorithm is specified in a rule.

GCM (Galois/Counter Mode) provides both confidentiality and integrity. Use aes-256-gcm for stronger encryption at the cost of performance.

---

envelope

• Type: boolean

• Default: false

• Description: Enables envelope encryption, a method where data is encrypted using a Data Encryption Key (DEK), which is then encrypted using a Key Encryption Key (KEK).

When true, the system stores encrypted DEKs with the ciphertext and uses a KEK (managed by the provider) to decrypt the DEK at runtime.

---

provider

Defines the key provider configuration. Each provider must have a unique ID, and one provider should be marked as the default.

provider:
  database:
    id: "env"
    default: true
    key_prefix: "ENC_KEY_V"

🔹 id

• Type: string

• Example: "env"

• Description: A unique identifier for this key provider instance.

---

default

• Type: boolean

• Description: Whether this provider is used as the default for all encryption operations (unless overridden by a rule or API input).

Only one provider should be marked as default: true.

---

key_prefix

• Type: string

• Example: "ENC_KEY_V"

• Description: Prefix used to load encryption keys from environment variables.

Example:

If key_prefix is "ENC_KEY_V":

• You can define multiple environment keys like:

  export ENC_KEY_V1="val1"
  export ENC_KEY_V2="val2"

These are versioned keys, which allows for rotation strategies or A/B testing.

---

Database Proxy

The proxy section enables transparent database proxying, allowing encryption and decryption of sensitive data on-the-fly. Currently, only PostgreSQL is supported.

proxy:
  postgres:
    enabled: true
    listen: "0.0.0.0:5432"
    ssl: true
    private_key: "/etc/proxy/ssl/proxy/server.key"
    cert: "/etc/proxy/ssl/proxy/server.crt"
    ca_cert: "/etc/proxy/ssl/ca/ca.crt"
    client_verification: false
    upstream:
      host: postgres-native:5432
      ssl: true
      private_key: "/etc/proxy/ssl/client/client.key"
      cert: "/etc/proxy/ssl/client/client.crt"
      ca_cert: "/etc/proxy/ssl/ca/ca.crt"
      client_verification: true

---

postgres.enabled

• Type: boolean

• Description: Enables or disables the PostgreSQL proxy.

When true, the proxy listens on the defined port and routes traffic to the upstream database, applying encryption/decryption rules as configured.

---

postgres.listen

• Type: string

• Description: Network address and port the proxy listens on for incoming PostgreSQL client connections.

Example: 0.0.0.0:5432 accepts connections on all interfaces, port 5432.

---

TLS Configuration

If ssl: true, the proxy server will serve over TLS.

private_key

Path to the TLS private key for the proxy server.

cert

Path to the TLS certificate used by the proxy server.

ca_cert

Path to the CA certificate used to verify client certificates.

client_verification

• Type: boolean

• Default: false

• Description: If true, clients must present a valid certificate to connect.

---

upstream

Defines the configuration for the real (native) PostgreSQL server that the proxy connects to.

host

• Host and port of the upstream PostgreSQL instance.

ssl

• Type: boolean

• Description: Whether to use TLS when connecting to the upstream PostgreSQL server.

private_key, cert, ca_cert

• TLS key/cert pair and CA certificate used when connecting to the upstream database.

client_verification

• Type: boolean

• Description: If true, the proxy will authenticate itself using the provided client certificate and private key when connecting to the upstream server.

---

Example Scenario

Component	Configuration Path	Description
TLS listener	proxy.postgres.ssl = true	Enables secure connections from clients
Client auth	proxy.postgres.client_verification	Optional: client must present TLS cert
TLS to upstream	upstream.ssl = true	Encrypt traffic to upstream database
Mutual TLS	upstream.client_verification = true	Proxy presents cert to authenticate to server

Rules (rules.sql)

The rules.sql section defines field-level encryption policies for each database and table. It controls how data is encrypted, hashed, or excluded from encryption during write operations. These rules allow flexible, fine-grained control over which fields are encrypted or hashed when inserted or updated through the proxy.

rules:
  sql:
    dev:
      compatibility_mode: false
      scheme: public
      log_original_query: true
      write:
        sample_data:
          username:
            hash: true
          phone_number:
            hash: true
            is_array: true
          balance:
            hash: false
          pin:
            hash: true
          ip_address:
            hash: true
          secret:
            hash: false
          notes:
            hash: false
          owner:
            json: true
            fields:
              name:
                hash: false
              email:
                hash: true
          companies:
            json: true
            fields:
              name:
                hash: false

---

sql

This block is for SQL databases, such as PostgreSQL.

---

dev

• Type: string

• Description: Name of the database to apply encryption rules to. You can define multiple databases under rules.sql.

---

compatibility_mode

• Type: boolean

• Default: true

• Description: Enables compatibility mode that relaxes some strict checks to allow smoother data migration. Turn this off once migration is complete to enable stricter validation and enforcement.

---

scheme

• Type: string

• Default: "public"

• Description: The schema name in the database. Typically "public" for default PostgreSQL setups.

---

log_original_query

• Type: boolean

• Description: Logs the unmodified original SQL queries before encryption for debugging purposes. ⚠️ Do not use in production – it may leak sensitive data.

---

write

This section defines field-level rules for each table where encryption or hashing should be applied during data writes (INSERT, UPDATE,DELETE).

---

Table Field Rules

Each table contains a list of columns with encryption instructions:

Example: sample_data

Field	Type	Hash	Is JSON	Is Array
username	string	✅	❌	❌
email	string	✅	❌	❌
name	string	❌	❌	❌
phone_number	array	✅	❌	✅
balance	number	❌	❌	❌
pin	string	✅	❌	❌
ip_address	string	✅	❌	❌
secret	string	❌	❌	❌
notes	string	❌	❌	❌
owner	json	⚠️	✅	❌
└ name	string	❌	-	-
└ email	string	✅	-	-
companies	json[]	⚠️	✅	❌
└ name	string	❌	-	-

---

Field Options

hash

• Type: boolean

• Description: If true, the field is hashed (e.g., for lookup). The original data also encrypted.

is_array

• Type: boolean

• Description: Indicates that the field is an array (PostgreSQL arrays). Encryption is applied per element.

json

• Type: boolean

• Description: Indicates that the field contains a JSON object. Subfields can be individually encrypted or hashed.

fields

• Description: Defines encryption rules for subfields in a JSON object.

---

Use Cases

• ✅ Compliance: Enforce encryption for fields like email, pin, and ip_address.

• ✅ Selective JSON Encryption: Encrypt only sensitive parts of nested JSON fields like owner.email.