Configuring CipherStash Proxy

Configuration

CipherStash Proxy is configured using a configuration file or environment variables.

The configuration file uses the TOML format. The default path of the file is ./cipherstash-proxy.toml in the same directory as the executable. If using Docker, the file is mounted into the Docker container at /etc/cipherstash-proxy/cipherstash-proxy.toml YAML and JSON formats are also supported. see [Command line arguments]((#cli-args) for more details.

Environment variables will be used if the the configuration file is not present, and will also override configuration values specified in the file.

Example configuration

Connect using default host and port values and reuse the database.username and database.password as the proxy connection. Audit will be enabled by default and outputs Data Access Events to stdout.

1[database]
2name = "stash"
3username = "postgres"
4password = "password"

Core

Connects CipherStash Proxy to a database.

Most minimal configuration

Connect using default host and port values and reuse the database.username and database.password as the proxy connection.

1[database]
2name = "stash"
3username = "postgres"
4password = "password"

With this configuration, the connection string to connect to CipherStash Proxy will be:

1postgres://postgres:password@0.0.0.0:6432/stash"

Config as env variables:

1export CS_DATABASE__NAME=stash
2export CS_DATABASE__USERNAME=postgres
3export CS_DATABASE__PASSWORD=password

Slightly less minimal configuration

Connect using default host and port values, and configure a username and password as the proxy connection.

1username = "proxy-user"
2password = "proxy-password"
3
4[database]
5name = "stash"
6username = "postgres"
7password = "password"

With this configuration, the connection string to connect to CipherStash Proxy will be:

1postgres://proxy-user:proxy-password@0.0.0.0:6432/stash"

Minimal configuration using both file and env variables

./cipherstash-proxy.toml:

1[database]
2name = "stash"
3username = "postgres"

Env variables:

1export CS_DATABASE__NAME=database_name
2export CS_DATABASE__PASSWORD=password

With this configuration, the connection string to connect to CipherStash Proxy will be:

1postgres://postgres:password@0.0.0.0:6432/database_name"

The CS_DATABASE__NAME variables takes precedence and overrides the name defined in the file.

The file does not define a password at all, and the CS_DATABASE__PASSWORD env value is used.

Minimal configuration using both file and env variables

./cipherstash-proxy.toml:

1[database]
2name = "stash"
3username = "postgres"

Env variables:

1export CS_DATABASE__NAME=database_name
2export CS_DATABASE__PASSWORD=password

With this configuration, the connection string to connect to CpherStash Proxy will be:

1postgres://postgres:password@0.0.0.0:6432/database_name"

The CS_DATABASE__NAME variables takes precedence and overrides the name defined in the file.

The file does not define a password at all, and the CS_DATABASE__PASSWORD env value is used.

CipherStash credentials

Credentials are required to use the Audit and Encrypt products.

A workspace groups one or more protected databases. Your account can have many workspaces each identified by a workspace_id. Each protected database needs some configuration in order to use Encrypt and Audit products, and this configuration lives inside the workspace. A workspace is roughly analogous to an environment, and it's not unusual to have a development and production workspace.

The proxy needs a client_access_key for the workspace in order to connect and authenticate.

For details on setting up these credentials, see Getting started with CipherStash Proxy.

Audit

Audit is enabled by default and outputs Data Access Events to stdout.

The cipherstash subscriber needs to be configured to send data events for analysis with CipherStash Audit.

Example Audit configuration

CipherStash Credentials are required to connect Audit to CipherStash.

1workspace_id = "workspace_id"
2client_access_key = "client_access_key"
3
4[audit]
5subscriber = "cipherstash"

max_primary_key_per_aggregate

The max_primary_key_per_aggregate setting is used to specify the maximum record count of an aggregate query for injecting primary keys.

Aggregate queries may reveal information about the underlying data, paticularly in cases where a small number of records are used in the calculation. If an aggregate query returns a number of records less than the max_primary_key_per_aggregate value, primary keys will be injected into the query.

The injection uses the array_agg PostgreSQL function. The performance impact on the database is neglible as the primary key is by definition indexed, and the referenced tables are already present in the SQL statement.

Encrypt

Encrypt needs additional dataset configuration and is not enabled by default.

Example Encrypt configuration

CipherStash Credentials are required to connect Audit to CipherStash.

1workspace_id = "workspace_id"
2client_access_key = "client_access_key"
3
4[encryption]
5mode = "encrypted"
6client_id = "client_id"
7client_key = "client_key"

Pool configuration

pool_mode

Session mode has the same semantics and behaviour as a direct connection to the database. The client talks to one server for the duration of the connection. Session mode supports prepared statements, SET, and advisory locks.

In Transaction mode, a client talks to one server for the duration of a single transaction. At the end of the transaction, the server is returned to the pool. Transaction mode uses connections more efficiently but does not support SET and advisory locks. Use SET LOCAL and pg_advisory_xact_lock which are scoped to the transaction. Prepared statements are supported, but some database drivers and frameworks may not play nicely. Testing is recommended before using in production.

connect_timeout

The proxy will automatically retry connection creation on failure, until the connect_timeout has expired. This can be useful for transient connectivity errors, or in cases where container orchestration may not be sequential.

The retry has exponential backoff, so the actual timeout may be longer than connect_timeout, but will never be less.

The min_pool_size must be set to at least 1 to ensure that the pool attempts to connect on startup.

That is: don't set the min_pool_size to 0 if you want an extended connect_timeout.

test_on_checkout

When enabled, test_on_checkout ensures that a health check is made every time a connection is acquired from the pool. If the connection fails the check, a new connection is established, within the constraints of the pool configuration and capacity.

Enabling test_on_checkout may be required to mitigate ConnectionReset - Connection reset by peer errors in CI environments. Test suites that drop and recreate the test database between test runs invalidate any open connections in the pool and trigger ConnectionReset errors. See Proxy operations & troubleshooting for more details

The health check query is the string literal ; and apart from network transmission is a noop. However, as the setting does introduce additional latency it is generally not recommended for production.

use_dedicated_connection

The use_dedicated_connection setting bypasses the connection pool. Like test_on_checkout, enabling use_dedicated_connection may be required to mitigate ConnectionReset - Connection reset by peer errors in CI environments.

As the pool is bypassed, the number of open connections may exceed the configured pool capacity and test_on_checkout is generally a better option.

Prometheus configuration

Logging configuration

| query_logging | Enable query logging | false | CS_QUERY_LOGGING | | unsafe_logging | Enable logging of sensitive information | false | CS_UNSAFE_LOGGING |

Command line arguments

1Usage: cipherstash-proxy [OPTIONS] [CONFIG_FILE]

Config file examples

Provide alternative path:

1cipherstash-proxy ./config/config.toml

Use YAML configuration:

1cipherstash-proxy cipherstash-proxy.yaml

Use JSON configuration:

1cipherstash-proxy cipherstash-proxy.json

Optimise logging for Observability

To run CipherStash Proxy with structured json logs, all log output to stdout and with color disable:

1cipherstash-proxy --log-format structured --log-output stdout --nocolor true

Extended configuration

CipherStash Proxy is based on the excellent pgcat.

The --config-extended command line option enables the Proxy to be run using the full pgcat configuration. All of the pgcat features are available, with support for sharding, load balancing, failover and mirroring.

Running with extended configuration:

1cipherstash-proxy --config-extended pgcat.toml

Example configuration with Audit and Encrypt

1host = "proxy.cipherstash.com"
2port = 6432
3username = "proxy-user"
4password = "proxy-password"
5
6workspace_id = "workspace_id"
7client_access_key = "client_access_key"
8
9pool_size = 3
10pool_mode = "Session"
11
12[audit]
13subscriber = "cipherstash"
14
15[encryption]
16mode = "encrypted"
17client_id = "client_id"
18client_key = "client_key"
19
20[database]
21name = "stash"
22host = "postgres.cipherstash.com"
23port = 5432
24username = "postgres"
25password = ""

Software updates

Automated vs manual updates

CipherStash will publish regular updates to CipherStash Proxy and will follow a standard release schedule. You can choose to update automatically or manually based on your operational requirements. It's recommended to stay up-to-date with the latest releases to benefit from new features and security patches.

The docker registry will be updated with the latest version of the CipherStash Proxy. Customers can pull the latest image and redeploy the container to update to the latest version.

Maintenance effort

Routine updates require minimal effort from your team. Major updates may require review and testing to ensure compatibility with existing systems.

Log configuration

All CipherStash Proxy containers log to both stderr and stdout. These logs can be configured to be stored locally on the server or can be integrated with existing log management tools using standard logging protocols. You have the flexibility to choose based on compliance and operational preferences.

Hardware prerequisites

Instance sizing

CipherStash Proxy can run on a variety of hardware configurations, depending on the expected load and redundancy requirements. Performance benchmarks and traffic analysis should guide the decision-making process. The Proxy is designed to be lightweight and efficient, so it can run on modest hardware configurations.

Suggested minimum requirements

• CPU: 0.5 vCPUs
• Memory: 0.5 GB

Networking prerequisites

Required ports

By default, CipherStash Proxy listens on port 6432, which is configurable. Ensure this port is open in your firewall settings to allow communication from your client applications to CipherStah Proxy.

Routing modifications

Ensure that routing configurations allow for uninterrupted communication between CipherStash Proxy and the PostgreSQL databases it manages. You may need to adjust routing rules to accommodate the Proxy's network requirements to communicate with the upstream databases.

Identity prerequisites

Credential requirements

Standard PostgreSQL credentials are used for authentication. Ensure that these credentials are securely managed and rotated regularly.

Optional credentials

SSL/TLS certificates can be optionally configured for enhanced security during data transmission.

Monitoring/Ops processes

Known failure scenarios

Common failure scenarios include network interruptions, misconfigured firewall rules, or authentication failures.

Monitoring guidelines

Monitor connection counts, response times, and error rates to detect anomalies that may indicate operational issues. CipherStash Proxy exposes Prometheus metrics that can be used for monitoring and alerting. Configure alerts based on these metrics to proactively address potential issues.

Shared responsibilities

CipherStash is responsible for maintaining the software's integrity and providing updates. You are responsible for monitoring your instances and managing the containers securely.

Logging

Log access

Logs are accessible within the Docker container and can be streamed to a centralized logging solution as configured.

Configuration options

Log verbosity can be adjusted via the configuration file. Customers can choose to log only essential information or enable detailed logging for troubleshooting purposes. Referer to the configuration file options above for available logging options.

Upgrades

Updating CipherStash Proxy

To update CipherStash Proxy, pull the latest Docker image from the repository and restart the container with the new image. CipherStash is committed to providing regular updates and security patches to ensure Proxy's reliability and security and will ensure backward compatibility with existing configurations.

Notification of new versions

Subscribe to release notifications via the console dashboard to stay informed about new versions.

Deploying upgrades

Deploy upgrades by redeploying the Docker container with the latest image. Ensure minimal downtime by testing in a staging environment before production deployment.

System health checks

Error monitoring

Regularly check the health of CipherStash Proxy by monitoring logs for error messages and by checking the Docker container’s status. Set up alerts for critical errors to ensure timely resolution. Monitor the Prometheus metrics for performance and resource utilization.