Merge pull request #244 from cipherstash/rh/tls-docs

docs: Adds TLS and Docker configuration docs.

Author: damncabbage

docs/reference.md

@@ -6,6 +6,7 @@ This page contains reference documentation for configuring CipherStash Proxy and
 
 - [Proxy config options](#proxy-config-options)
   - [Recommended settings for development](#recommended-settings-for-development)
+  - [Docker-specific configuration](#docker-specific-configuration)
 - [Prometheus metrics](#prometheus-metrics)
   - [Available metrics](#available-metrics)
 - [Supported architectures](#supported-architectures)
@@ -32,7 +33,7 @@ host = "0.0.0.0"
 # Env: CS_SERVER__PORT
 port = "6432"
 
-# Enforce TLS connections
+# Enforce TLS connections from the Client to Proxy
 # Optional
 # Default: `false`
 # Env: CS_SERVER__REQUIRE_TLS
@@ -57,7 +58,7 @@ worker_threads = "4"
 # Env: CS_SERVER__THREAD_STACK_SIZE
 thread_stack_size = "2097152"
 
-
+### Proxy -> Backing database connection settings
 [database]
 # Database host address
 # Optional
@@ -92,7 +93,7 @@ password = "password"
 # Env: CS_DATABASE__CONNECTION_TIMEOUT
 connection_timeout = "300000"
 
-# Enable TLS verification
+# Enable TLS verification between Proxy and the backing database.
 # Optional
 # Default: `false`
 # Env: CS_DATABASE__WITH_TLS_VERIFICATION
@@ -115,22 +116,30 @@ config_reload_interval = "60"
 schema_reload_interval = "60"
 
 
+### Client->Proxy TLS Settings:
+# This section configures how the Proxy accepts connections from your client.
+# A Public Certificate and Private Key pair is required to correctly enable TLS.
+# Fill out:
+# - a Certificate Path and a Private Key Path, *or*
+# - a Certificate PEM string and a Private Key PEM string, *or*
+# - neither, removing this section, to disable Client->Proxy TLS.
+#   (This is a misconfiguration if `require_tls` above is enabled.)
 [tls]
-# Certificate path
+# Path to the Public Certificate .crt file.
 # Env: CS_TLS__CERTIFICATE_PATH
-certificate_path = "./server.cert"
+certificate_path = "./server.crt"
 
-# Private Key path
+# Path to the Private Key file.
 # Env: CS_TLS__PRIVATE_KEY_PATH
 private_key_path = "./server.key"
 
-# Certificate path
+# The Public Certificate PEM as a string.
 # Env: CS_TLS__CERTIFICATE_PEM
-certificate_pem = "..."
+certificate_pem = "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----"
 
-# Private Key path
+# The Private Key as a string.
 # Env: CS_TLS__PRIVATE_KEY_PEM
-private_key_pem = "..."
+private_key_pem = "-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----"
 
 
 [auth]
@@ -207,17 +216,35 @@ Although Proxy attempts to detect the environment and set a sensible default for
 To turn on human-friendly logging:
 
 ```bash
-CS_LOG__FORMAT = "pretty"
-CS_LOG__ANSI_ENABLED = "true"
+CS_LOG__FORMAT="pretty"
+CS_LOG__ANSI_ENABLED="true"
 ```
 
 If you are frequently changing the database schema or making updates to the column encryption configuration, it can be useful to reload the config and schema more frequently:
 
 ```bash
-CS_DATABASE__CONFIG_RELOAD_INTERVAL = "10"
-CS_DATABASE__SCHEMA_RELOAD_INTERVAL = "10"
+CS_DATABASE__CONFIG_RELOAD_INTERVAL="10"
+CS_DATABASE__SCHEMA_RELOAD_INTERVAL="10"
+```
+
+### Docker-specific configuration
+
+As a convenience for local development, if you use [Proxy's Docker container](../proxy.Dockerfile) with its default entrypoint and the below environment variables set, the EQL SQL will be applied to the database, and an example schema (for example, with the `users` table, from the [README Getting Started example](../README.md#getting-started)) will be loaded. These are turned on by default in the [development `docker-compose.yml`](../docker-compose.yml):
+
+(It is not recommended to use either of these in production.)
+
+```bash
+CS_DATABASE__INSTALL_EQL="true"
+CS_DATABASE__INSTALL_EXAMPLE_SCHEMA="true"
+```
+
+As a convenience for production deployments, with the below environment variable set, the Proxy container will add the AWS RDS global certificate bundle to the operating system's set of trusted certificates. This is recommended when running Proxy on AWS.
+
+```bash
+CS_DATABASE__INSTALL_AWS_RDS_CERT_BUNDLE="true"
 ```
 
+
 ## Prometheus metrics
 
 To enable a Prometheus exporter on the default port (`9930`) use either: