CipherStash Proxy config

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.

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"

Connects CipherStash Proxy to a database.

The addtional _ in the CS_DATABASE_ environment variables is intentional and is used to separate the nested configuration options.

The proxy username and password are the credentials applications will use to connect to CipherStash Proxy. If not supplied, the database.username and database.password will be used (the proxy username and password will be the same as the database username and password). The database credentials are always required so CipherStash Proxy can connect to the downstream database.

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:[email protected]:6432/stash"

Config as env variables:

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

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:[email protected]:6432/stash"

./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:[email protected]: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-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:[email protected]: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.

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 the introduction to CipherStash Proxy.

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 Audit.

CipherStash Credentials are required to connect Audit to CipherStash.

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

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 needs additional dataset configuration and is not enabled by default.

The addtional _ in the CS_ENCRYPTION_ environment variables is intentional and is used to separate the nested configuration options.

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"

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.

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.

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 and 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.

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.

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

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

1Usage: cipherstash-proxy [COMMAND]

Provide alternative path:

1cipherstash-proxy ./config/config.toml

Use YAML configuration:

1cipherstash-proxy cipherstash-proxy.yaml

Use JSON configuration:

1cipherstash-proxy cipherstash-proxy.json

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

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

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 = ""

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.

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

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.

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.

• CPU: 0.5 vCPUs
• Memory: 0.5 GB

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.

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.

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

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

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

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.

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

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

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.

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.

Subscribe to release notifications via the CipherStash Dashboard to stay informed about new versions.

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

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.