CipherStash - Protect Data, Not Just Systems.

Configuration file

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

The comnfiguration 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.

Environment variables will overide the configuration values specified in the file.

Configuration options

This file contains the following settings.

Setting	Description	Default	Environment Variables
host	IP address the proxy listens on	`0.0.0.0`	`CS_HOST`
port	Port number the proxy listens on	`6432`	`CS_PORT`
username	Username for proxy authentication	None (Required)	`CS_USERNAME`
password	Password for proxy authentication	None (Required)	`CS_PASSWORD`
workspace_id	Identifier for the workspace using the proxy	None (Required)	`CS_WORKSPACE_ID`
client_access_key	Access key for clients to authenticate with the proxy	None (Required)	`CS_CLIENT_ACCESS_KEY`
encryption.mode	Encryption mode; can be `encrypted` or `passthrough`	`passthrough`	`CS_ENCRYPTION__MODE`
encryption.client_id	Client ID for encryption, *required if mode is `encrypted`	None (*Required)	`CS_ENCRYPTION__CLIENT_ID`
encryption.client_key	Client key for encryption, *required if mode is `encrypted`	None (*Required)	`CS_ENCRYPTION__CLIENT_KEY`
audit.mode	Audit mode; can be `audit` or `passthrough`	`passthrough`	`CS_AUDIT__MODE`
audit.primary_key_injection	Disable primary key injection	`true`	`CS_AUDIT__PRIMARY_KEY_INJECTION`
prometheus_metrics	Enable Prometheus metrics	`false`	`CS_PROMETHEUS_METRICS`
prometheus_port	Port for Prometheus metrics	`9930`	`CS_PROMETHEUS_PORT`
use_dedicated_connection	Whether to use a dedicated connection for each client	`false`	`CS_USE_DEDICATED_CONNECTION`
pool_mode	Mode of connection pooling, `Session` or `Transaction`	`Transaction`	`CS_POOL_MODE`
pool_size	Maximum number of connections in the pool	`20`	`CS_POOL_SIZE`
min_pool_size	Minimum number of connections in the pool	`pool_size / 4` or `1`	`CS_MIN_POOL_SIZE`
log_ingest_endpoint	Upstream logging endpoint to send logs to	None (Optional)	`CS_LOG_INGEST_ENDPOINT`
query_logging	Enable query logging	`false`	`CS_QUERY_LOGGING`
unsafe_logging	Enable logging of sensitive information	`false`	`CS_UNSAFE_LOGGING`
database.name	Name of the upstream database being proxied	None (Required)	`CS_DATABASE__NAME`
database.host	IP address of the upstream database	`127.0.0.1`	`CS_DATABASE__HOST`
database.port	Port number of the upstream	`5432`	`CS_DATABASE__PORT`
database.username	Username for the upstream database connection	None (Required)	`CS_DATABASE__USERNAME`
database.password	Password for the upstream database connection	None (Optional)	`CS_DATABASE__PASSWORD`

Note

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

Example configuration file

1username = "proxy-user"
2password = "proxy-password"
3
4workspace_id = "12345678-1234-1234-1234-123456789012"
5client_access_key = "12345678-1234-1234-1234-123456789012"
6
7[database]
8name = "stash"
9username = "postgres"
10password = "password"
11

Note - username and password appear twice. The proxy defines a username and password as the credentials that applications will use to connect to the proxy. The database credentials are required so the proxy can connect to the downstream database.

The url to connect to the proxy with this configuration is:

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

Environment variables

CipherStash Proxy can also be configured using environment variables rather than a configuration file as shown in the table above.

Software Updates

Automated vs Manual Updates

CipherStash will publish regular updates to the CipherStash Proxy and will follow a standard release schedule. Customers can choose to update automatically or manually based on their 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

The 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, the 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 the CipherStah Proxy.

Routing Modifications

Ensure that routing configurations allow for uninterrupted communication between the 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. The 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. Customers are responsible for monitoring their 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

Logs 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 the Proxy

To update the 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 the 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.

Deployment of 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 the 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.